Skip to main content
skill CX Codex

debug · pwguler — Claude Code skill: what it does, how to install

debug is a Claude Code and Cursor skill that traces bug root causes step by step and verifies regression tests.

MIT 1,000 installs ★ 10 updated 2026-10-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pwguler/skills --skill debug -a claude-code
Open on GitHub

What debug does

The agent builds a task list to isolate the root cause, creates a minimal reproduction, and tests hypotheses before editing code. Dead code gets removed from modified files prior to the fix. A regression test is added once the issue is resolved.

The process halts after three consecutive invalid hypotheses or when reproduction data is missing. The rule triggers on mentions of errors, bugs, or failing tests.

What it helps with

  • find root cause of a bug step by step
  • build minimal reproduction for failure
  • add regression test for a fix
  • remove dead code before editing

Example prompts for the agent

  • Fix the bug in the auth module
  • The test is failing unexpectedly, investigate
  • The code is broken after update

How to install debug

1Skills CLI (Vercel)

npx skills add pwguler/skills --skill debug -a claude-code

2Manually: put the files in place

~/.claude/skills/debug/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/debug/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about debug

How to install debug in Claude Code?

Run npx skills add pwguler/skills --skill debug -a claude-code followed by ~/.claude/skills/debug/SKILL.md.

What does debug do?

Finds the primary cause of a bug, builds a reproduction test, checks hypotheses, and adds a regression test after fixing.

When does the skill trigger?

The agent activates the skill when you mention a bug, error, broken code, or when a test fails unexpectedly.

Source text

SKILL.md · MIT
---
name: debug
description: Find the root cause of a bug before you fix it. Read this skill before you fix any bug. Read it also when the fix looks obvious. Use it when the user says "fix", "broken", "not working", "error", "failing", or "bug". Use it also when a test fails unexpectedly during other work.
---

Do not fix a bug before you know its root cause. The search starts at the symptom, but it does not end there.

Fast path: when the error output shows the first cause directly, skip the hypothesis steps. An example is a stack line that points at the cause. Do not skip the reproduction, the regression test, or the `verify` skill in step 8. If the visible fix does not make the reproduction pass on the first try, the cause was not visible. Then do all the steps.

1. Before you reproduce the bug, create a task list with these steps as its items. If a task list already exists, add the steps to it. Each step is one item. When you skip a step, mark it done and add `skip: <reason>` to its text. The fast path skips the hypothesis steps this way. To go back to an earlier step, add that step and each step after it again as new items. Then delete the unfinished items that the new items replace.
2. Reproduce the bug first. Build the smallest reproduction that fails every time. If you cannot reproduce the bug, collect evidence until you can: logs, inputs, and versions. Do not guess.
3. Read the actual error. Find the first cause in the chain of causes, not the nearest symptom.
4. Make one hypothesis. Write it with the observation that would confirm it or refute it. Get that observation before you start a fix: a log line, an assertion, or a probe. If the evidence does not exist yet, add instrumentation. Keep the instrumentation small and easy to remove, and remove it when it has given its answer.
5. When two hypotheses compete, design one observation that shows which one is true. Do not try fixes one after another.
6. Fix the root cause, one fix at a time. Flag another problem that you find, such as a second bug, but do not fix it. Dead code is not another problem. Before the fix, delete the dead code in each file that the fix changes, as `implement` does. Do this also when the bug did not touch that code. Dead code is functions, imports, and parameters that no caller uses, and branches that no caller reaches. It is also stale flags, and validators that repeat a check that a boundary already did. It is also comments that repeat the code or excuse a workaround. Keep dead code that a non-goal puts out of scope. Read [fix root causes](references/fix-root-causes.md) before a fix that adds a guard, a catch, or a comment that defends it. Read it also when the same cause can occur elsewhere, or when the failure shows only after a restart.
7. Add the regression test that would have caught this bug. It fails on the old code and passes with the fix.
8. Before you report the fix, read the `verify` skill and follow it. Your report claims that the bug is fixed, and `verify` proves that claim. When the bug appeared inside a slice, the full gate waits for the slice's commit.

Rules:

- Do not try several fixes at random to see if one helps.
- Stop the loop after three refuted hypotheses in a row. Stop it also when the available evidence cannot give a reproduction. Then report what you tried and which observation is missing, and let the user decide.
- If the fix does not make the reproduction pass, the hypothesis was wrong. Go back to step 4. Do not keep the failed fix and add a second fix. When two failed fixes shared one premise, read [attack the premise](references/attack-the-premise.md).
- If the root cause shows a design problem, say so. Offer to run `drill` on the redesign. Do not hide the problem under a workaround.
- When the cause took more than one hypothesis to find, propose a cheap signal that stays on. It is a log line, a metric, or an assertion that would have shown this cause at once. Add it when the user agrees.

© pwguler · MIT · pwguler/skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

debug by other authors comes first.

debug official anthropics debug is a Claude Code skill that reproduces errors, traces their causes, and proposes fixes. It starts from an error message, stack trace, or unexpected behavior. CX Codex +1 6,100installs debug jsmastery-pro debug runs a structured investigation loop to find a bug's root cause, applies the minimal fix, and prepares a regression test. CX Codex +1 5,100installs debug Yeachan-Heo debug diagnoses broken OMC sessions, workflow failures, and repo state issues using traces and targeted reproduction. CX Codex +1 705installs debug cyrusagents debug works through a reported bug from reproduction to a minimal fix. Use it when you need to trace an error and verify the result. CX Codex +1 871installs debug parcadei debug is a Claude Code skill that investigates issues through logs, database state, and Git history. It starts during manual testing or implementation when something goes wrong. CX Codex +1 511installs ce-debug EveryInc ce-debug — a skill for Claude Code traces bugs and slow behavior to their cause. It starts when asked to investigate or fix a failure. CX Codex +1 3,700installs debug-systematic travisjneuman debug-systematic — a four-phase debugging skill for hard-to-reproduce failures, race conditions, and unexplained behavior. It guides the agent from reproduction to verified fix. CX Codex +1 152installs doca-debug NVIDIA doca-debug finds the failing DOCA layer, from installation and linking to runtime and drivers. Use it for unresolved symbols, DOCAERROR results, silent tools, and crashes. CX Codex +1 162installs sleuth parcadei sleuth — a subagent that systematically debugs issues by forming diagnostic questions, tracing code paths, analyzing logs, and documenting findings in a structured report. CX Codex ★ 3,951repo stars gjalla-debug gjalla gjalla-debug — a skill that guides agents to find the root cause of a bug with evidence before proposing a fix. Works with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. CX Codex +1 357installs debug-mantra thananon debug-mantra is a Claude Code skill that guides debugging through reproduction, failure tracing, hypothesis testing, and experiment review. It activates with /debug-mantra or when a debugging request or error log appears. CX Codex +1 5,100installs

From the same set15

The whole set →
write-skill write-skill — a Claude Code skill that creates and edits agent documents with behavioral verification. Activated when writing system prompts, CLAUDE.md, AGENTS.md, or repeating agent corrections. CX Codex +1 1,000installs parallel This Claude Code skill runs independent tasks through subagents in parallel. It activates only when asked to parallelize work, compare attempts, or split a job into parts. CX Codex +1 1,000installs core-interview core-interview — a skill for Claude Code that runs an interview loop through decision trees until every branch is settled. CX Codex +1 1,000installs research The research Claude Code skill traces library and API behavior to primary sources, or investigates why code took its current shape. It activates for lookups and questions about the history of a setting or constant. CX Codex +1 1,000installs verify verify — a skill for Claude Code checks claims about completed or fixed work against fresh command output. It runs before a commit or PR, after changes, and before reporting that work is done or tested. CX Codex +1 1,000installs land land is a Claude Code skill that finishes a development branch through merge, PR, keep, or discard. It runs after implementation is complete. CX Codex +1 1,000installs drill A skill for Claude Code interviews the user about a plan or design until its decisions are settled. It runs for new features, unresolved designs, or a request to “drill this.” CX Codex +1 1,000installs implement implement — a skill for Claude Code and Codex that executes settled plans in thin test-driven slices. Runs when prompted to build code from a spec or slice plan. CX Codex +1 1,000installs

Project sponsors

Companies that keep this analytics open