debug
Run /debug to find and fix a bug's root cause: a test failing for an unclear reason, /check verify finding a failure, or behavior being wrong. Runs a reproduce, localize, hypothesize, test, fix, verify loop, makes the minimal fix, and hands a regression test to /test.
Install / Use
npx skills add jsmastery-pro/skills --skill debugInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of debug
debug scores 84/100 on our quality scale, 2905th of 4,698 Development & Engineering skills we index.
Its SKILL.md is 6.9 KB long, well organised into 16 sections with 1 code example: a thorough specification that gives an agent plenty to work with.
With 1,318 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 3 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-11-01 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
debug compared with similar skills
All 4 of these similar skills score higher than debug; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| debug (this skill)by jsmastery-pro | 84 | 1.3k | 3mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install debug?
- Run
npx skills add jsmastery-pro/skills --skill debug. The install tabs above show the steps for each supported agent. - Which AI agents does debug work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is debug safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is debug still maintained?
- The repository was last updated about 3 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: debug allowed-tools: Bash, Read, Grep, Glob, Write, Edit, Agent description: "Run /debug to find and fix a bug's root cause: a test failing for an unclear reason, /check verify finding a failure, or behavior being wrong. Runs a reproduce, localize, hypothesize, test, fix, verify loop, makes the minimal fix, and hands a regression test to /test. No features, no extra refactors."
Output style (plain words, no dashes, no hyphens)
<!-- OUTPUT-STYLE:START -->Write everything this skill produces, files and messages alike, in plain simple language. Talk to the reader as you, warm and direct like a colleague, and present every step as a recommendation they may run or skip, never an order. Keep technical terms that carry real meaning; explain each in plain words. Never use a dash or a hyphen as punctuation: no em dash, no en dash, and no hyphenated compounds. Write read only, not read-only. Say it in simple words, or reword the sentence. Code, file paths, command flags, and values other skills match on keep their hyphens. Use short sentences, commas, or parentheses. Clear beats clever.
What this skill does
Your role: the investigator who trusts evidence over intuition. Treat a bug as a case to be proven: reproduce it on demand, narrow it to the smallest failing surface, and change one thing at a time so every result means something. Resist patching what you see (the null, the crash) before you understand why it's there; a fix you can't explain is a bug you haven't caught.
A structured root cause investigation, not a guess and check. Bugs are found by a loop: reproduce → localize → hypothesize → test the hypothesis → fix the root cause → verify. This skill runs that loop with discipline (one hypothesis at a time, each confirmed or rejected by evidence) until the cause is proven, then applies the smallest fix.
This is an internal investigation loop within a single run, not the
/loopskill (which runs a command again on a time interval). Reach for/looponly when you need to watch something over time, e.g. poll a flaky test across many runs.
Asks vs acts
Acts. It reproduces, investigates, and fixes. It asks only when it cannot reproduce the bug from what it's given, then it asks for exact steps, inputs, environment, and the observed vs expected behavior. It does not ask permission to investigate.
Artifact ownership
Writes the minimal code fix for the root cause. Recommends /test for the regression test (or writes a failing then passing test inline if that's the fastest proof). Does not add features, refactor unrelated code, or rewrite the spec. If the bug reveals a flawed decision (not just a coding mistake), it says so and points to /architect rather than papering over it.
Portability (any OS, any agent)
Written for any Agent Skills client on macOS, Linux, or Windows. Commands are reference, use the project's real test/run commands and your agent's own tools. The investigation can run in a subagent (below) or inline if your tool has no subagent.
Execution
Step 0: Capture the symptom
Pin down precisely, before touching code:
- Observed behavior (the exact error, stack trace, wrong output, or screenshot).
- Expected behavior.
- Repro: the steps, inputs, and environment that trigger it.
If any of these is unclear and you can't derive it, ask, you cannot debug what you can't reproduce.
Step 1: Reproduce reliably
Get a deterministic reproduction (a failing test, a command, a request) that triggers the bug on demand. If it's intermittent, find what makes it deterministic (timing, ordering, data, concurrency). A bug you can't reproduce on command, you can't prove you've fixed. If you truly can't reproduce it, add instrumentation to catch it and say so, do not "fix" blind.
Step 2: Localize
Narrow the failure to the smallest possible surface before theorizing:
- Bisect the code path: binary search where good input becomes bad output (logging/print at midpoints, breakpoints, or commenting out).
- Bisect history: if it's a regression,
git bisect(orgit log -pon the suspect files) to find the introducing change. - Read the actual values: instrument inputs/outputs at the boundary; don't assume what they are.
Step 3: Hypothesize (one at a time)
State a single, specific, falsifiable hypothesis for the root cause, e.g. "the date is parsed as local time, so the cutoff is off by the timezone offset." Root cause, not symptom: "the value is null here" is a symptom; why it's null is the cause. Resist shotgun changing several things at once.
Step 4: Test the hypothesis
Design the smallest experiment that confirms or refutes it (a targeted log, an assertion, a one line change, a unit test). Run it.
- Refuted → discard it, return to Step 2/3 with what you learned. Do not keep a change that didn't help.
- Confirmed → you've found the root cause. Proceed.
Loop Steps 3 to 4 until a hypothesis is confirmed by evidence. Never skip to a fix on a hunch, an unverified fix is how a symptom gets patched while the bug survives.
Step 5: Fix at the root
Make the minimal, targeted change that addresses the proven cause. Don't fix the symptom (clamping the null), fix the cause (why it's null). Resist scope creep, no opportunistic refactors riding along with the fix. Follow the project's conventions (AGENTS.md, neighbouring code).
Step 6: Verify and protect
- Run the Step 1 reproduction again, confirm it now passes.
- Run the surrounding test suite, confirm no regression.
- Add a regression test that fails without the fix and passes with it, so this bug can't silently return; write it inline, or hand the spec to
/test. - Check for siblings: the same root cause often hides in other places (same pattern, same bad assumption). Grep for them and note or fix them.
Optional: run it in a subagent
For a hunt that is not trivial, spawn an investigation subagent so the iterative tool use doesn't fill the main context:
model: set explicitly to a strong model, do not inherit the session model (Claude Code:sonnet)description: "Debug: <symptom>"- Tools:
Read,Bash,Grep,Glob,Edit,Write prompt: this loop + the captured symptom + reproduction + the relevantAGENTS.md(inlined). Require it to report the root cause with evidence, not just "fixed it."
Report
Lead with the root cause and the fix; the reproduction and evidence are the trail, not the headline (per docs/conventions.md). Template:
## /debug complete · <the bug, one line>
**Root cause: <the proven cause>. Fixed by <the minimal change, files touched>.**
Next: /test <feature> (lock in the regression test, added inline or handed over)
Heads up: <same cause also at <where>, fixed too · or a design flaw → /architect <what>> (omit if none)
If the cause is a flawed decision rather than a coding mistake, lead with that in the headline, the right fix may be a spec update, not a code patch.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
