How to use the Systematic Debugging agent skill

What is an agent skill and what does this one make the agent do?

An agent skill is a folder containing a SKILL.md file and optional supporting files. The agent reads the skill when it matches the task, so you do not have to paste instructions into every chat.

This skill applies whenever the agent hits a bug, test failure or unexpected behavior. Its core rule is to find the root cause before attempting fixes, and it states that the agent must complete Phase 1 before proposing any fix.

• Phase 1, Root Cause Investigation: read error messages carefully, reproduce the problem consistently, check recent changes, gather evidence in multi-component systems, and trace data flow backward.
• Phase 2, Pattern Analysis: find working examples in the same codebase, compare against references, list every difference, and check dependencies.
• Phase 3, Hypothesis and Testing: state a single hypothesis, make the smallest possible change, and test one variable at a time.
• Phase 4, Implementation: create a failing test first, implement a single fix, verify it, and if three or more fixes have failed, question the architecture instead of trying another patch.

Install the systematic-debugging skill

Download the ZIP for this skill from this page and unzip it. The result should be a folder named systematic-debugging that contains SKILL.md. Place that folder in one of these locations, depending on how you want to use it:

• Personal use across projects: unzip into ~/.claude/skills/ so the folder sits at ~/.claude/skills/systematic-debugging/.
• One project only: unzip into the project's .claude/skills/ folder so the skill travels with that repository.
• Claude apps: upload the skill under Settings → Capabilities → Skills.

How do you trigger the skill with a natural request?

You do not need a special command. The skill's description tells the agent to use it when encountering any bug, test failure, or unexpected behavior, before proposing fixes, so a plain description of the problem is usually enough.

Describe the symptom, the context and what you have already tried. Naming the skill directly is also reasonable if you want to be sure it is used.

• "Our checkout tests fail only in CI. Use systematic debugging before changing anything."
• "The build breaks after the last merge. Investigate the root cause first and don't propose a fix yet."
• "I've tried two fixes for this flaky test and neither worked. Follow the systematic debugging process."

What does a debugging session look like?

With the skill active, expect the agent to ask questions and gather evidence before it edits code. It should reproduce the failure, read the full stack trace, and look at recent commits or config changes. If the failure sits deep in a call stack, the skill points to root-cause-tracing.md for the backward tracing technique.

If the agent starts suggesting a quick patch, the skill's red-flag list tells it to stop and return to Phase 1. You can also apply the same redirections yourself, such as asking whether the assumption was verified or asking it to stop guessing.

Use the bundled tools and guides

The folder includes supporting guides and one script. condition-based-waiting.md covers replacing arbitrary delays in flaky tests, and defense-in-depth.md covers validating data at every layer. find-polluter.sh bisects a test suite to find which test leaves unwanted files or state behind.

The script needs Bash and Node/npm, because it runs the project's test commands (npm test) repeatedly. condition-based-waiting-example.ts is illustrative code that requires a TypeScript environment; it is not a standalone package.

• find-polluter.sh: runs the project's tests repeatedly to locate the test that causes pollution. Run it only on repositories you trust.
• condition-based-waiting-example.ts: an example of waiting for a condition instead of a fixed timeout.
• test-pressure-1.md, test-pressure-2.md, test-pressure-3.md and test-academic.md: test files included with the skill.

What does the skill need and what are the safety notes?

The skill itself is instructions, but its folder runs scripts. According to the listing, it runs scripts and does not use the network. The process guidance assumes Git is available for checking recent changes.

Because find-polluter.sh executes your project's test commands repeatedly, review the script and the repository before running it. Do not run it on untrusted code.

• Requires Bash and Node/npm for find-polluter.sh.
• Requires a TypeScript environment only if you want to run the condition-based-waiting example.
• Assumes Git for the recent-changes step.
• Runs scripts: yes. Uses network: no.

Tips for getting the most from it

Give the agent the exact error text and the steps to reproduce. The skill's first phase depends on evidence, so the more concrete the report, the faster the agent can move on.

Use the skill for real bugs, not trivial ones. For an obvious typo, the full process adds overhead and slows things down.

• Paste full stack traces rather than summaries.
• State whether the failure is reproducible every time.
• If the agent has already made several fixes, say so; the skill is designed to question the architecture after three failed attempts.
• Pair it with the test-driven-development and verification-before-completion skills, which the process references by name.