How to use the Systematic Debugging agent skill

What does the systematic-debugging skill make the agent do?

The core rule of the skill is that the agent must find the root cause before trying any fix. Its stated iron law is that no fix proposals are allowed without completing root-cause investigation first. The skill is written in Chinese and organised into four phases that the agent should finish in order: root-cause investigation, pattern analysis, hypothesis and testing, and implementation.

In the investigation phase the agent reads the full error message and stack trace, reproduces the problem reliably, checks recent changes such as git diffs and new dependencies, and, in multi-component systems, adds diagnostic logging at each boundary to find where the fault lies. It then traces the bad value back to where it originated.

• Reproduce the problem before changing anything
• Gather evidence instead of guessing
• Trace the data flow back to its source and fix there
• Compare with a working example in the same codebase
• Change one thing at a time and verify each hypothesis
• After three or more failed fixes, question the architecture rather than trying again

How do you install the systematic-debugging skill?

Download the ZIP file for the skill from this page and unzip it. You can install it for yourself across all projects or for a single project. For a personal install, unzip it into ~/.claude/skills/. For a project-only install, unzip it into the .claude/skills/ folder inside your project.

If you use the Claude apps rather than a local setup, you can upload the skill instead. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill there.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into .claude/skills/ in your project folder
• Claude apps: Settings → Capabilities → Skills, then upload

Check the files in the skill folder

The main file is SKILL.md, which holds the instructions the agent reads. The folder also contains supporting reference documents: root-cause-tracing.md for following a bad value back through the call stack, defense-in-depth.md for adding validation at several layers, and condition-based-waiting.md for replacing fixed timeouts with condition-based waits. Other files such as find-polluter.sh, condition-based-waiting-example.ts, CREATION-LOG.md and the test-*.md files are also included.

• SKILL.md: the main instructions
• root-cause-tracing.md, defense-in-depth.md, condition-based-waiting.md: referenced techniques
• find-polluter.sh and condition-based-waiting-example.ts: bundled scripts and example code
• test-pressure-1.md, test-pressure-2.md, test-pressure-3.md, test-academic.md: test documents

How do you trigger the skill with a natural request?

You do not need a special command. The skill's description says it should be used whenever you hit any bug, failing test or unexpected behaviour, and before proposing a fix. So a plain request that describes the problem is usually enough. Say what broke, what you expected and what you have already tried, so the agent has the context it needs to start its investigation.

If you want the agent to skip the quick patch and explain the cause first, say so directly. Phrases like 'find the root cause before changing code' match the skill's purpose.

• "The login tests pass locally but fail in CI. Find the root cause before changing any code."
• "The build fails after yesterday's dependency update. Walk through the error and recent changes first."
• "I've tried two fixes for this timeout and neither worked. Stop guessing and investigate."

What does a debugging session look like?

Suppose a multi-step release pipeline produces a build that will not sign. The skill directs the agent to check each layer in turn: whether the secret is available in the workflow, whether it reaches the build script, what the keychain state is, and then the actual signing command. The aim is to find which boundary breaks before anyone edits a script.

When the agent does write a fix, the skill asks for a failing test first, a single change, and verification before claiming success. It also references the test-driven-development and verification-before-completion skills for those steps, so you may need those installed as well.

What are the safety notes?

The skill runs scripts and does not use the network, according to its listing. Bundled scripts such as find-polluter.sh and the example code in condition-based-waiting-example.ts are included in the folder. Read any script before running it, and be aware that the example debugging commands in SKILL.md, such as those that inspect the keychain or run codesign, act on your machine when the agent runs them. The listing does not require any other tools, but the skill references other skills that may need installing separately.

• The listing says the skill runs scripts; review them before the agent executes them
• The listing says it does not use the network
• Some example commands inspect system state, such as keychain contents, so check what the agent runs

Tips for getting the best results

Give the agent the exact error text and the steps to reproduce it. The skill's first phase depends on evidence, so a clear error message speeds up the work. If a problem is truly environmental or timing-related, the skill says to record what you checked, add retries, timeouts or error messages, and add logging, rather than forcing a fix.

Use it for problems that resist quick fixes. For a small obvious change, the process adds overhead you may not need.

• Paste the full stack trace, not a summary
• Name the files or components involved
• Ask the agent to explain the cause before editing code
• Use it for flaky tests, CI failures and multi-component issues