debugging · akillness — Claude Code skill: reproduce, isolate, verify
A skill that walks the agent through a reproduce → isolate → verify loop for concrete bugs, regressions and flaky failures. Useful once you already have a failing test or request.
npx skills add akillness/jeo-skills --skill debugging -a claude-codeWhat debugging does
The skill gives the agent an eight-step frame. It starts by freezing the failure definition: expected behavior, actual behavior, trigger, environment, and how confident you are. Then it picks the cheapest evidence source — rerun the failing command, compare recent changes for a regression, repeat runs for a flaky test, diff configs when the failure only shows up in CI or staging.
From there the agent builds the smallest reproducer and narrows the boundary: UI versus API, database, worker, config, dependency. One check per hypothesis, not five patches at once. Three references ship with it: references/debug-loop.md for the full experiment scaffold, references/mode-selection-and-fast-checks.md with packets for regressions, flakes, env mismatches and artifact-led cases, and references/handoff-boundaries.md so work that belongs elsewhere stays elsewhere.
Tool access is limited to Read, Grep, Glob, Bash and Write. The skill does not take raw logs without a narrowed symptom, test-policy design, PR review or performance tuning — it hands those off. When reproduction or isolation still fails, the agent is told to state low confidence and ask for one missing artifact instead of guessing at a root cause.
What it helps with
- reproduce a failing test in isolation
- narrow a failure to one module or config branch
- find the commit that introduced a regression
- gather repeated-run evidence for a flaky test
- compare local behavior against CI
Example prompts for the agent
- Reproduce the failure in
test_checkout.pyand narrow it to one module - This is a regression — find the change window and try
git bisect - The test fails intermittently; measure the rate with repeated runs and isolate one case
How to install debugging
1Skills CLI (Vercel)
npx skills add akillness/jeo-skills --skill debugging -a claude-code2Manually: put the files in place
~/.claude/skills/debugging/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/debugging/
1Skills CLI (Vercel)
npx skills add akillness/jeo-skills --skill debugging -a codex2Manually: put the files in place
.agents/skills/debugging/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add akillness/jeo-skills --skill debugging -a cursor2Manually: put the files in place
.cursor/skills/debugging/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install akillness/jeo-skills debugging2Manually: put the files in place
.github/skills/debugging/SKILL.md1Skills CLI (Vercel)
npx skills add akillness/jeo-skills --skill debugging -a gemini-cli2Platform CLI
gemini skills install https://github.com/akillness/jeo-skills --path .agent-skills/debuggingManually: put the files in place
.devin/skills/debugging/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add akillness/jeo-skills --skill debugging -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about debugging
How do I install debugging in Claude?
Run npx skills add akillness/jeo-skills --skill debugging -a claude-code. The skill file then lives at ~/.claude/skills/debugging/SKILL.md.
What does the debugging skill do?
It drives the agent through defining the failure, reproducing it, isolating the boundary, testing one hypothesis at a time, and verifying the fix. Output is a short debugging brief or plan.
When should I not use this skill?
If all you have is logs and stack traces with no narrowed symptom, that goes to log-analysis. Test-program design, PR review and performance tuning are outside its scope too.
Similar skills
All skills for Agent setup: memory, context, orchestration →debugging by other authors comes first.
