Agent skill

Sdc Diagnose

by puritysb in puritysb/AgentDeck

Diagnose AgentDeck Stream Deck/PTY option synchronization, cursor state, hook ingestion, and bridge state-machine issues.

MITAuto-check passedTesting & QA

Install Sdc Diagnose

skills CLI
$ npx skills add puritysb/AgentDeck --skill sdc-diagnose -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install puritysb/AgentDeck sdc-diagnose --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/puritysb/AgentDeck.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/sdc-diagnose .claude/skills/sdc-diagnose && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
sdc-diagnose
GitHub stars
260
Token cost
~1.5k tokens
SKILL.md length
322 words
Files
1
Skills in repo
6
Repo updated
First seen
Licence
MIT

At a glance

Diagnose AgentDeck Stream Deck/PTY option synchronization, cursor state, hook ingestion, and bridge state-machine issues.

  • Works in 5 steps: Collect Diagnostic Data → Analyze for Known Failure Patterns → Add Regression Tests → …
  • Testing & QA work in your project
  • SKILL.md covers Step 1: Collect Diagnostic Data, Step 2: Analyze for Known…, Step 3: Add Regression Tests and Step 4: Run & Verify, plus 2 more sections
  • Calls git and pnpm

What it does

Sdc Diagnose is an agent skill from puritysb/AgentDeck. Diagnose AgentDeck Stream Deck/PTY option synchronization, cursor state, hook ingestion, and bridge state-machine issues. Collects diagnostics, searches known failure patterns, adds focused regression tests, and verifies with pnpm tests.

Its SKILL.md is about 1.5k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Testing & QA. It works with pnpm. The repository describes itself as: Local dashboards and physical controls for AI coding agents — native 3D aquariums, Stream Deck, Apple/Android apps, e-ink, ESP32 and LED displays. The licence is MIT.

When your agent uses it

  • Testing & QA work in your project

Example prompts

  • “/sdc-diagnose”

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Collect Diagnostic Data
  2. Analyze for Known Failure Patterns
  3. Add Regression Tests
  4. Run & Verify
  5. Report

What it can do on your machine

Read from SKILL.md and the folder at commit 0b812da. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • git
    • pnpm

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git and pnpm, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Sdc Diagnose loads about 1.5k tokens when it runs. Until then it costs about 63 tokens; SKILL.md has 322 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~63
When it runs · the whole SKILL.md, loaded when a task matches
~1.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from puritysb/AgentDeck at commit 0b812da, republished under its MIT licence (© puritysb). 322 words, ~1,453 tokens.

Download SKILL.mdSave it as .claude/skills/sdc-diagnose/SKILL.md (or your agent's skills folder).
name
sdc-diagnose
description
Diagnose AgentDeck Stream Deck/PTY option synchronization, cursor state, hook ingestion, and bridge state-machine issues. Collects diagnostics, searches known failure patterns, adds focused regression tests, and verifies with pnpm tests.

AgentDeck Diagnostic Skill

Canonical diagnostic procedure for AgentDeck bridge synchronization issues between device displays and agent terminals (cursor desync, false idle, stale options, action dispatch races, hook ingestion gaps, state-machine regressions). This file is the single source of truth — .claude/skills/sdc-diagnose is a tracked directory symlink to this skill.

Step 1: Collect Diagnostic Data

From the repo root, try the live bridge first. Start narrow: ~100 journal entries, filtered to the event types the Step 2 patterns use. Widen (--tail 300, then drop the filter) only when the window does not contain the failure.

bash
cd "$(git rev-parse --show-toplevel)"
EVENTS='state_change|hook|error|option_prompt|navigate_option|cursor_update|select_option|idle|codex_'
agentdeck diag --tail 100 2>/dev/null | grep -E "$EVENTS" | tail -100 \
  || echo "Bridge not running (or no matching events) — using journal files directly"

If the bridge isn't running, read journal/log files directly, with the same filter:

bash
ls -t ~/.agentdeck/journal/*.jsonl 2>/dev/null | head -3
ls -t ~/.agentdeck/journal/*.jsonl 2>/dev/null | head -1 | xargs tail -n 400 | grep -E "$EVENTS" | tail -100
grep -E "$EVENTS" /tmp/sdc-debug.log 2>/dev/null | tail -100 || echo "No debug log found"

If access fails, follow AGENTS.md Agent working agreements for execution-policy failures. Treat unreadable diagnostics as unknown, not proof that the bridge is stopped.

Step 2: Analyze for Known Failure Patterns

2a. Cursor Desync

navigate_option followed by a stale cursor_update with conflicting indices.

Pattern: navigate_option cursor=X->Y ... cursor_update cursorIndex=X (reverted)
Root cause: PTY confirmation overwrites optimistic update
Fix: cursor authority system (A3) — optimistic suppresses PTY within 200ms
2b. False Idle

option_prompt followed by idle within 500ms.

Pattern: option_prompt (N options) ... idle_detected (< 500ms gap)
Root cause: Small chunk with "❯ No" misclassified as idle prompt
Fix: Semantic idle check (A2) — only "❯" or ">" as sole non-ws content
2c. Stale Options

option_prompt with missing or non-contiguous indices.

Pattern: option_prompt indices=[0,1,3] (missing 2)
Root cause: Buffer corruption or partial redraw parsed as complete
Fix: Buffer tail re-parse with debounce
2d. Action Dispatch Race

select_option overlapping rapid state transitions.

Pattern: select_option ... state AWAITING->PROCESSING->AWAITING (rapid cycle)
Root cause: Enter sent before arrow navigation completes
Fix: Proportional delay (A4) — 50 + |delta| * 20ms
2e. ANSI Cursor Invisible

Terminal keyboard input without a corresponding cursor_update for >500ms.

Pattern: (arrow key in terminal) ... no cursor_update for >500ms
Root cause: ink repositions cursor via ANSI sequences without ❯ in chunk
Fix: ANSI reposition detection (A1) — re-parse buffer on small non-❯ chunks
2f. Codex Hook Gap

Missing codex_user_prompt_submit, codex_tool_start, codex_tool_end, or codex_stop in daemon hook logs.

Pattern: Codex session active but lifecycle hooks absent from hook log
Root cause: ~/.codex/config.toml hooks not installed/migrated, or fence corrupted
Fix: re-run `agentdeck codex` (installs/migrates) or inspect installCodexHooksIfNeeded

Step 3: Add Regression Tests

Add focused tests near the subsystem under change:

  • Parser / state-machine / cursor issues: bridge/src/__tests__/cursor-sync.test.ts, state-machine.test.ts, or parser tests.
  • Codex hook issues: hooks/src/__tests__/codex-install.test.ts, bridge/src/__tests__/state-machine.test.ts, or the Codex APME adapter tests.
  • Apple timeline/rendering issues: apple/AgentDeckTests/.

Template (cursor desync, vitest):

typescript
it('reproduces cursor desync from journal entry', () => {
  const sm = bootToIdle();
  sm.handleParserEvent('option_prompt', {
    options: [/* options from journal */],
    navigable: true,
    cursorIndex: 0,
  });

  sm.updateCursorIndex(/* target */, 'optimistic');
  vi.advanceTimersByTime(/* gap from journal */);
  sm.updateCursorIndex(/* stale PTY value */, 'pty');

  expect(sm.getCursorIndex()).toBe(/* expected */);
});

Step 4: Run & Verify

Run the narrowest useful tests first, then broaden when shared behavior changed:

bash
cd "$(git rev-parse --show-toplevel)"
pnpm test
pnpm -r exec tsc --noEmit

Check that all existing tests pass, new regression tests pass, and there are no TypeScript errors.

Step 5: Report

## Diagnostic Report

### Issues Found
1. [PATTERN]: Description
   - Journal entries: [timestamps]
   - Expected: X
   - Actual: Y
   - Fix: [A1/A2/A3/A4/A5/codex] — description

### Tests Generated
- <file>: N new tests
- Regression coverage: [patterns covered]

### Verification
- pnpm test: PASS/FAIL
- TypeScript: PASS/FAIL

### Recommendations
- [Any additional fixes or monitoring suggestions]

Key Files Reference

FilePurpose
bridge/src/output-parser.tsPTY output parsing, cursor detection
bridge/src/state-machine.tsState transitions, cursor authority
bridge/src/index.tsBridge wiring, command handlers
bridge/src/__tests__/cursor-sync.test.tsCursor sync test suite
hooks/src/codex-install.tsCodex lifecycle hook installer (hook-gap issues)
~/.agentdeck/journal/Event journal files
/tmp/sdc-debug.logDebug log (when -d flag used)

© puritysb, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/sdc-diagnose of puritysb/AgentDeck.

Open the folder on GitHubat commit 0b812da

Compare with similar skills

Sdc Diagnose next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Sdc Diagnose compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Sdc Diagnose this skillpuritysb/AgentDeck260—~1.5kAutomated safety check: PassMIT
DeerFlow Smoke Testbytedance/deer-flow84k—~2.5kAutomated safety check: NotesMIT
OpenWork Desktop CDP Driverdifferent-ai/openwork24k—~465Automated safety check: PassCustom licence
E2Egronxb/hot-updater1.8k—~1.6kAutomated safety check: PassCustom licence
Cloud Agents Starterscalar/scalar16k—~1.4kAutomated safety check: PassMIT
Desktop Dual Repo TestEynzof/Hermes-CN-Desktop1.8k—~1.8kAutomated safety check: PassCustom licence

Similar skills

  • DeerFlow Smoke Test

    bytedance/deer-flow

    Walks through an end-to-end smoke test of a DeerFlow deployment: pull the latest code, deploy with Docker or locally, verify services, run health checks and write a report.

    84k GitHub stars~2.5k tokensUpdated today
    Testing & QAAuto-check: notes
  • OpenWork Desktop CDP Driver

    different-ai/openwork

    Drives a running OpenWork desktop window over CDP from the shell to evaluate JS, take screenshots, start sessions and send prompts for hand checks.

    24k GitHub stars~465 tokensUpdated today
    Testing & QAAuto-check passed
  • E2E

    gronxb/hot-updater

    Run end-to-end OTA verification for examples/v0.85.0 with agent-device.

    1.8k GitHub stars~1.6k tokensUpdated today
    Testing & QAAuto-check passed
  • Minimal starter runbook for cloud agents to install dependencies, run packages, execute tests, and troubleshoot the Scalar monorepo quickly.

    16k GitHub stars~1.4k tokensUpdated today
    Testing & QAAuto-check passed
  • Desktop Dual Repo Test

    Eynzof/Hermes-CN-Desktop

    A skill your agent uses when starting or verifying Hermes Agent CN Desktop with the latest Hermes-CN-Desktop and Hermes-CN-Core branches — dev smoke test (pnpm tauri:dev), packaged beta/release…

    1.8k GitHub stars~1.8k tokensUpdated 19 days ago
    Testing & QAAuto-check passed
  • Local CI

    module-federation/core

    Run this repository's local CI parity commands and pnpm run ci:local jobs.

    2.7k GitHub stars~914 tokensUpdated today
    Testing & QAAuto-check passed

More from puritysb/AgentDeck

  • Session End

    puritysb/AgentDeck

    A skill your agent uses when the user asks to end, wrap up, clear, hand off, or prepare continuity for a Codex/AgentDeck session.

    260 GitHub stars~709 tokensUpdated yesterday
    Auto-check passed
  • Agentdeck Deploy

    puritysb/AgentDeck

    Build, install, launch, and configure AgentDeck on connected Android, Apple, ESP32, Stream Deck, Ulanzi Studio, or daemon targets.

    260 GitHub stars~5.4k tokensUpdated yesterday
    Auto-check passed
  • Esp32 Heap Discipline

    puritysb/AgentDeck

    Memory-allocation discipline for AgentDeck ESP32 firmware (esp32/).

    260 GitHub stars~1.5k tokensUpdated yesterday
    Auto-check passed
  • Agentdeck Workflows

    puritysb/AgentDeck

    A skill your agent uses for AgentDeck build, dev-server, Stream Deck plugin, Android release, or Apple/Xcode diagnostic workflows.

    260 GitHub stars~429 tokensUpdated yesterday
    Auto-check passed
  • Agentdeck Report

    puritysb/AgentDeck

    Read, claim and report an explicitly shared AgentDeck request using its request ID through an already approved local MCP connection.

    260 GitHub stars~351 tokensUpdated yesterday
    Auto-check passed

Works with

Categories

Questions about Sdc Diagnose

What does Sdc Diagnose do?

Diagnose AgentDeck Stream Deck/PTY option synchronization, cursor state, hook ingestion, and bridge state-machine issues. Sdc Diagnose is an agent skill from puritysb/AgentDeck. Diagnose AgentDeck Stream Deck/PTY option synchronization, cursor state, hook ingestion, and bridge state-machine issues.

When should I use Sdc Diagnose?

Sdc Diagnose fits situations like: testing & QA work in your project.

How do I install Sdc Diagnose in Claude Code?

Run `npx skills add puritysb/AgentDeck --skill sdc-diagnose -a claude-code`. Or copy the skill folder (.agents/skills/sdc-diagnose in puritysb/AgentDeck) into .claude/skills/sdc-diagnose in your project. Claude Code loads it when a task matches its description.

How do I install Sdc Diagnose in Codex?

Run `npx skills add puritysb/AgentDeck --skill sdc-diagnose -a codex`. Or copy the skill folder (.agents/skills/sdc-diagnose in puritysb/AgentDeck) into .agents/skills/sdc-diagnose in your project. Codex loads it when a task matches its description.

Can I use Sdc Diagnose in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add puritysb/AgentDeck --skill sdc-diagnose -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/sdc-diagnose, .gemini/skills/sdc-diagnose, .github/skills/sdc-diagnose and .opencode/skills/sdc-diagnose in your project.

What does Sdc Diagnose need to run?

Going by SKILL.md and its folder, Sdc Diagnose needs the command-line tools its instructions call (git and pnpm).

Does Sdc Diagnose access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Sdc Diagnose safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Sdc Diagnose use?

Sdc Diagnose is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Sdc Diagnose use?

About 1.5k tokens (SKILL.md is roughly 5.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Sdc Diagnose?

Skills that share tags, products or a category with Sdc Diagnose: DeerFlow Smoke Test (bytedance/deer-flow, 84k stars), OpenWork Desktop CDP Driver (different-ai/openwork, 24k stars), E2E (gronxb/hot-updater, 1.8k stars) and Cloud Agents Starter (scalar/scalar, 16k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Sdc Diagnose?

puritysb (a GitHub user) maintains it in puritysb/AgentDeck, which has 260 GitHub stars. The repository holds 6 skills in this directory. The repository was last updated on October 9, 2026.

Source: puritysb/AgentDeck on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.