You just shipped a feature. Claude wrote most of it. The tests pass, the types check, the linter is quiet. Everything looks fine.
But "looks fine" is doing a lot of heavy lifting. You scan the code yourself and nothing jumps out. You also know that the bugs that take down production at 3 AM never jump out. They hide in async flows you didn't trace, in error handlers that swallow the thing you needed to see, in off-by-one conditions that only matter when the data gets big enough.
The LLM that wrote the code won't find its own blind spots. It generated confidently and moved on. You need something that reads adversarially, not generatively.
load the debug-full skill and review src/services/ for bugs
Now you've got a structured audit. Every candidate gets traced, classified, and either proven or dismissed. Nothing gets reported on vibes. Nothing gets skipped quietly. You get findings you can act on, or you get a clean bill of health that actually means something because it shows its work.
debug-light — Quick scan. Three passes: basic logic, async/timing, silent failures. Local analysis only, no cross-file tracing. Use after edits, refactoring, or when you want a fast sanity check. Three outcomes: BUG, QUESTION, SKIP.
debug-full — Deep investigation. Six categories (logic, async, resources, errors, contracts, concurrency), cross-file tracing, formal evidence classification, disconfirmation searches. Every finding goes through a structured outcome check with explicit yes/no gates. Five outcomes: BUG, QUESTION, SKIP, DEFERRED, Dismissed.
debug-security — Vulnerability hunter. Traces attacker-controlled input to dangerous sinks. Threat modeling, attack surface mapping, concrete exploit payloads. If it can't prove an attacker can reach the sink with a working payload, it doesn't call it a vulnerability. Four outcomes: VULN, QUESTION, SKIP, DEFERRED.
Pick the depth that matches the stakes. Routine change? Light. Pre-release review? Full. Handling user input? Security.
You just refactored something and want a quick check.
Moved some async logic around, tests pass, but you're not sure about the error paths.
load the debug-light skill and scan src/handlers/orderProcessor.ts
You're about to merge and want real confidence.
The PR touches payment flows. "Tests pass" isn't enough.
load the debug-full skill and review src/payments/ for bugs, focus on error handling and async flows
You're building an API that takes user input.
File uploads, query parameters, form data. You want to know what an attacker sees.
load the debug-security skill and audit src/routes/ for vulnerabilities
The code looks correct but something feels off.
A race condition that only shows up under load. A promise chain that works 99% of the time.
load the debug-full skill and review src/workers/queueConsumer.ts, focus on concurrency and async
You inherited a codebase and don't trust it.
No tests, no docs, and it's been running in production for two years.
load the debug-security skill and audit the HTTP routes in src/api/ — assume unauthenticated attacker
Prerequisites:
- Claude Code installed
Install:
git clone https://github.com/Alex-R-A/claude-debug-skills.git
mkdir -p ~/.claude/skills
cp -r claude-debug-skills/debug-light ~/.claude/skills/
cp -r claude-debug-skills/debug-full ~/.claude/skills/
cp -r claude-debug-skills/debug-security ~/.claude/skills/Run your first audit:
load the debug-light skill and scan src/ for bugs
Start with light. If it finds things that concern you, escalate to full. If you're handling untrusted input, go straight to security.
You're building a webhook handler. It parses incoming JSON, validates a signature, and dispatches events to different processors. Claude wrote it in twenty minutes. Clean code, good types, handles the happy path well.
You run debug-security on it:
load the debug-security skill and audit src/webhooks/ — assume attacker controls HTTP request
Two findings come back. One is a QUESTION: the signature verification uses string comparison instead of timingSafeEqual, and the skill can't determine if the timing difference is exploitable in your deployment. It tells you exactly what to check and what the answer means: if the comparison leaks timing information over the network, it's a VULN; if not, it's a SKIP.
The other is a VULN: the event type from the payload is used to construct a file path without sanitization. Concrete payload included. Trace from entry point to sink. The fix is obvious once you see it.
You patch both in ten minutes. The kind of bugs that would have survived code review, passed all tests, and waited patiently for someone to find them in production.
"Can't the LLM just hallucinate bugs?"
That's exactly what these skills are designed to prevent. Every finding requires traced evidence, not pattern-matching. debug-full and debug-security both enforce structured outcome checks: a series of yes/no gates that must all pass before a finding gets classified as BUG or VULN. If the evidence isn't there, the finding gets downgraded to QUESTION or SKIP. The skill can't "feel like" something is a bug and report it anyway.
"What about false negatives?"
The skills track what they checked and what they didn't. The Session Context at the top of every report lists categories scanned, categories skipped, and why. If coverage was partial, the report says so. A clean result from a partial scan doesn't claim to be comprehensive. DEFERRED findings explicitly flag areas where investigation was cut short.
"How is this different from just asking Claude to review my code?"
Structure. An unstructured review produces prose that sounds authoritative but has no accountability. These skills force a specific workflow: identify candidates, trace evidence, attempt disconfirmation, check outcome gates, classify. The format makes it obvious when reasoning is incomplete. You can look at a QUESTION finding and see exactly what's missing, what would resolve it, and which way the answer would go.
"Which languages?"
Currently targeting JavaScript and TypeScript. The analysis patterns and evidence methodology are language-agnostic; additional language support is in progress.
For the curious.
debug-light runs three focused passes (logic, async/timing, silent failures) with local-only analysis. No cross-file tracing, no formal evidence hierarchy. Designed for speed.
debug-full enforces a formal evidence system. Every finding gets an EvidenceClass (Semantic, ClosedWorld, OpenWorld, PatternOnly) and a Reachability status (Proven, BoundBypassed, BoundedSafe, Unproven). Findings go through disconfirmation: the skill actively searches for evidence that the bug doesn't exist. Budget limits prevent unbounded investigation (3 callsites, 2 hops; 5 and 3 for critical/high severity). The outcome check is a checklist of 8 binary conditions that must all be satisfied for BUG classification.
debug-security adds threat modeling, attack surface mapping, and an attacker-centric trace direction (backward from dangerous sinks to attacker-controlled sources). Evidence classes shift to exploit-oriented: Proven exploit, Closed-world trace, Open-world trace, Pattern-only. Findings require concrete attack payloads. Budget is 4 handlers and 3 trust boundaries (6 and 4 for critical/high). The OWASP-aligned security checklist covers injection, path traversal, SSRF, auth bypass, secrets exposure, insecure randomness, mass assignment, open redirects, prototype pollution, and timing attacks.
All three skills share a core principle: no finding without evidence, no evidence without a search, no search without showing the output.