debug
Skill8 starsChanged 35 days agoMITView on GitHub
Diagnose and fix a failing test, error, or unexpected behavior. Routes to the appropriate engineer based on the error context. Lighter than /implement — no worktree isolation, no full pipeline ceremony. Trigger this when someone says: something is broken, fix this error, my test is failing, why is this not working, I'm getting an exception, this is throwing an error, debug this, why does this crash. Do NOT use when the root cause is already known and the fix is small — use /hotfix instead. Do NOT use for architectural changes — use /implement instead.
191 other projects use a version of this.
Adopted by
Most recently taken up by
- automagik-dev/omnitheir own version, first seen Nov 15, 2026
- patrickjaja/claude-desktop-extratheir own version, first seen Nov 15, 2026
- NVIDIA/Model-Optimizertheir own version, first seen Nov 15, 2026
- drosam/agentstheir own version, first seen Nov 15, 2026
- shivasaini04/nanocrewtheir own version, first seen Nov 15, 2026
- markmhendrickson/neotomatheir own version, first seen Nov 15, 2026
Used with
Projects with it also use add-discord, add-slack and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
MicrosoftSkilladd-discord
Add Discord bot channel integration via Chat SDK.
Also in 11 projects that use this
MicrosoftSkilladd-slack
Add Slack channel integration via Chat SDK.
Also in 11 projects that use this
- +10 more from microsoft
Other versions191 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 191
- Yeachan-Heo/oh-my-claudecode★ 41ksame name
- Yeachan-Heo/oh-my-claude-sisyphus★ 41ksame name
- anthropics/knowledge-work-plugins★ 36ksame name
- gavrielc/nanoclaw★ 31ksame name
- nanocoai/nanoclaw★ 31ksame name
- qwibitai/nanoclaw★ 31ksame name
- openai/symphony★ 27ksame name
- FalkorDB/FalkorDB★ 11ksame name
- NVIDIA/Model-Optimizer★ 5.6ksame name
- NVIDIA/TensorRT-Model-Optimizer★ 5.6ksame name
181 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository30 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- backlogSkill
- conventionsSkill
- devops-azureSkill
- devops-githubSkill
- devopsSkill
- hotfixSkill
- implementSkill
- interview-meSkill
- lint-agentsSkill
- memory-auditSkill
- memory-querySkill
- obsidian-briefSkill
- obsidian-captureSkill
- obsidian-dailySkill
- obsidian-recapSkill
- obsidian-searchSkill
- obsidianSkill
- onboardSkill
- pack-reviewSkill
- planSkill
- refactorSkill
- repo-mapSkill
- review-prSkill
- scaffoldSkill
- setup-projectSkill
- smellSkill
- spec-intakeSkill
- system-checkSkill
- whatSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. 0 are common, 15 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 175 edited versions we read keep these.
15
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 12
Ask for (or extract from what the user provided):
- Distinctive: line 18
If the user has already provided all of this, skip asking and proceed.
- Distinctive: line 22
Run git branch --show-current.
- Distinctive: line 26
Before routing to an engineer:
- Distinctive: line 27
Read the files mentioned in the error or stack trace.
- Distinctive: line 28
If a test is failing, read the test file and the code it exercises.
- Very specific: line 29
Check memory//*.md (if the directory exists) for any known-issues entries that match the symptom.
- Distinctive: line 34
If the error is localized to one layer, select based on file type:
- Distinctive: line 43
Multi-layer errors: If the error spans layers (e.g., a frontend test failing because a backend API is broken), route to the layer …
- Distinctive: line 53
After the engineer returns:
- Distinctive: line 54
Run the failing test or repro steps to confirm the fix works.
- Distinctive: line 55
If the fix introduces new failures, loop back to the engineer with the new errors.
- Distinctive: line 59
Run code-reviewer on the changed files only.
- Very specific: line 78
Run the project's test suite (dotnet test, npm run test, or pytest) and confirm all tests pass.
- Distinctive: line 91
Fixing the symptom, not the root cause: Always state your root-cause hypothesis before routing to an engineer.
- Distinctive: line 93
Fix breaks other tests: After the engineer returns, run the full test suite (or at minimum the suite for the changed module), not just the …
- Distinctive: line 94
Hypothesis not passed to the engineer: If you route to an engineer without a clear hypothesis, the engineer will re-investigate from …
“Common” is measured: kept by at least 6 in 10 of the 175 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Debug
Diagnose and fix the error, failing test, or unexpected behavior the user described.
1. Gather context
Ask for (or extract from what the user provided):
- The error message or stack trace (exact text preferred)
- The file(s) involved, if known
- How to reproduce the problem (command, test name, steps)
- Whether the error is new (regression) or has existed for a while
If the user has already provided all of this, skip asking and proceed.
2. Confirm the working branch
Run git branch --show-current. If the branch is main or master, warn the user and ask whether to create a fix branch before making changes. Do not create or switch branches automatically — just ask.
3. Read before acting
Before routing to an engineer:
- Read the files mentioned in the error or stack trace.
- If a test is failing, read the test file and the code it exercises.
- Check
memory/**/*.md(if the directory exists) for any known-issues entries that match the symptom. - Form a hypothesis about the root cause. State it explicitly.
4. Route to the appropriate engineer
If the error is localized to one layer, select based on file type:
| File type | Engineer |
.cs / .NET | csharp-engineer |
.ts / .vue | frontend-engineer |
.ts in an MCP server | mcp-engineer |
| SQL / migration | database-engineer |
Multi-layer errors: If the error spans layers (e.g., a frontend test failing because a backend API is broken), route to the layer containing the root cause first. Fix that layer, verify the downstream symptom resolves, then return here if the downstream layer also needs changes.
Pass the engineer:
- The error message and stack trace
- The files to read and modify
- Your root-cause hypothesis
- How to verify the fix (the test command or repro steps)
5. Verify the fix
After the engineer returns:
- Run the failing test or repro steps to confirm the fix works.
- If the fix introduces new failures, loop back to the engineer with the new errors.
6. Lightweight review
Run code-reviewer on the changed files only.
Skip security-reviewer and performance-reviewer unless:
- The fix touches auth, authorization, data access, or secrets → invoke security-reviewer
- The fix touches a hot path → invoke performance-reviewer
State your reasoning either way.
7. Wrap up
Report:
- Root cause (confirmed or best explanation)
- What was changed and why
- Whether any follow-up work is needed (e.g., the fix revealed a broader pattern issue)
This skill is diagnosis-and-fix, not full pipeline delivery. Do not run test-engineer, merge-reviewer, or git-engineer unless the user asks.
If the user asks to commit the fix, apply these minimum gates before git-engineer commits:
- Run the project's test suite (
dotnet test,npm run test, orpytest) and confirm all tests pass. If any fail, loop back to the engineer before proceeding. - Route through merge-reviewer as the commit gate — do not use git-engineer Mode B directly. merge-reviewer will run the test suite (Step 0b), apply the gate checklist, and produce the commit.
The purpose of /debug is speed of diagnosis. The purpose of committing is permanence. Once the user decides to commit, the same safety guarantees as /implement apply.
One guarantee that deliberately does not apply: the plan gate. This skill passes no
plan_id, so merge-reviewer's gate 4a reports "not applicable" and neither the acceptance bars nor the## Deviationschecks run. Plan consumption is opt-in per invocation, and a diagnosis has no plan because it skipped planning. Do not addplan_idhandling here without first deciding who would write the plan and when.
Gotchas
- Fixing the symptom, not the root cause: Always state your root-cause hypothesis before routing to an engineer. If the hypothesis turns out to be wrong after the fix, loop back — do not close out just because the immediate error is gone.
- Multi-layer errors: A frontend error that says "404 Not Found" is often a backend routing bug, not a frontend bug. Read the network request and the backend logs before deciding which layer to fix. Route to the root-cause layer first.
- Fix breaks other tests: After the engineer returns, run the full test suite (or at minimum the suite for the changed module), not just the originally failing test. A fix that breaks three other tests is not a fix.
- Hypothesis not passed to the engineer: If you route to an engineer without a clear hypothesis, the engineer will re-investigate from scratch. Save time by passing the exact error, the files involved, and your best theory.
- Unclear hot path: Tight loops over large collections, endpoints under high traffic, and database queries in critical flows (login, checkout, search) all qualify. If uncertain, include performance-reviewer — it is faster than explaining why you skipped it.
- Escalating too quickly to /implement: Debug is the right skill for most errors. Only escalate to /implement if the fix requires new files, new dependencies, or an architectural change that is out of scope for a targeted patch.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

