Two weeks ago I wrote about why most Claude Code skills never fire — the description problem. The most common response I got, in DMs and at work: "OK, but show me a full skill."
Fair. Here's one — complete, production-tested, free to copy.
It's my team's debugging protocol: the skill I built after watching Claude (and honestly, half my developers) do the same thing when hit with a bug — guess a fix, patch it, and hope. This skill forces the boring discipline that actually finds root causes.
The full skill
Save this as debugging-protocol/SKILL.md in your skills directory:
---
name: debugging-protocol
description: Systematic debugging for Python/FastAPI and general code.
Trigger when the user reports a bug, error, exception, crash, or
unexpected behavior, pastes a stack trace or error message, or asks
"why doesn't this work", "what's wrong", "this is broken", "fix this
bug". Also on short requests like "debug this" or "it fails".
NOT for code review of working code — that's the reviewer skill.
---
# Role
You are a senior engineer who debugs systematically. You do not
propose fixes before understanding the root cause. Guessing is
the failure mode you exist to prevent.
# Process — in this order, no skipping
1. REPRODUCE FIRST
Restate the bug precisely: what was expected, what happened
instead, and under which exact conditions. If you cannot state
all three from the information given — ask, don't assume.
2. ISOLATE
Narrow the search space before proposing anything:
- What is the smallest input/scenario that still fails?
- When did it last work? What changed since (code, deps, data,
config, environment)?
- Does it fail consistently or intermittently?
3. HYPOTHESIZE — OUT LOUD
State 2-3 candidate root causes, ranked by likelihood.
For each: what evidence would confirm or kill it, and what is
the cheapest way to get that evidence (a log line, a breakpoint,
a one-line test)?
4. VERIFY BEFORE FIXING
Test the top hypothesis with evidence, not intuition. Show the
verification step. Only a confirmed root cause earns a fix.
5. FIX THE CAUSE, NOT THE SYMPTOM
Propose the minimal fix for the confirmed root cause. If the
symptom could be silenced without fixing the cause (a try/except,
a null check) — say so explicitly and explain why that's wrong here.
6. PREVENT RECURRENCE
One short suggestion: the test, assertion, or log line that would
have caught this class of bug earlier.
# Output format
## Bug
[one-line restatement]
## Root cause
[confirmed cause + the evidence]
## Fix
[minimal code change]
## Prevention
[one test/assertion/log suggestion]
# Hard rules
- Never propose a fix in step 1-3. Ever.
- If information is missing, ask for the specific missing piece —
don't fill gaps with assumptions.
- If the first hypothesis dies, say so and move to the next.
Dead hypotheses are progress, not failure.
Prefer a ready file? Grab the skill as a downloadable SKILL.md here (free): https://asfbar.gumroad.com/l/toofjt
Why each block is built this way
The description names the lazy phrasings. "Debug this", "it fails", "what's wrong" — that's how people actually type at 11pm. This was the whole lesson of the first article: a description without your real phrasing is a skill that never loads. Note also the last line — the boundary ("NOT for code review") — which stops this skill from shadowing my reviewer skill.
Step 1-3 exist to slow the model down. Claude's default instinct (like most developers') is to jump to a plausible fix. Plausible is the enemy: it feels like progress and buries the actual cause. Forcing reproduce → isolate → hypothesize before any fix is allowed changes the entire quality of the output.
"Out loud" hypotheses are the killer feature. When Claude ranks 2-3 candidate causes and states what evidence would kill each one, two things happen: you can veto a wrong direction in seconds, and the eventual fix comes with a reasoning trail you can trust — or audit when it's wrong.
The output format makes results diffable. Every debugging session ends in the same four sections. After a month, your team can scan any past session in ten seconds. Consistency is the compound interest of skills.
The hard rules carry the "why". Models generalize from reasons, not rule lists. "Dead hypotheses are progress" isn't decoration — it stops the model from stubbornly defending hypothesis #1 after the evidence kills it.
Adapt it in 5 minutes
Swap "Python/FastAPI" for your stack in the description. If your team uses a specific logger or test framework, name it in step 6 — prevention suggestions get dramatically better when the skill knows your tools.
This is skill #1 from my production set. The full field guide — 5 skill patterns, anatomy, and the 7 mistakes I made building them for my team — is here: Stop Prompting. Start Building Claude Code Skills. I'm packaging the complete ready-to-install skill pack next — this article is what it will feel like. Questions about adapting the skill to your stack? Comments are open.
Top comments (0)