How to use the Structured 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 with instructions that an AI agent loads when a task matches the skill's description. This one is from the QwenLM/qwen-code project, licensed under Apache-2.0, and is designed for hard bugs such as flaky tests, intermittent failures and behaviour that seems impossible.

The skill follows a six-step cycle: hypothesize, design instrumentation, verify data collection, run and observe, document findings, and iterate. It also warns the agent against three traps: jumping to fixes without evidence, blaming external systems such as models or APIs without inspecting their inputs, and reframing the user's report instead of investigating it.

Install the structured-debugging skill

Download the ZIP from the skill's page on this directory and unzip it. Then place the skill folder in one of these locations, depending on how you want it available:

• Personal use across projects: unzip into ~/.claude/skills/
• One project only: unzip into the project's .claude/skills/ folder
• Claude apps: upload the skill under Settings → Capabilities → Skills

Trigger the skill with natural requests

You do not need a special command. The SKILL.md description tells the agent to use the skill when investigating non-trivial bugs, unexpected behaviour, flaky tests, or issues traced through complex systems. It also asks the agent to activate proactively when a first fix attempt failed or when it is tempted to blame an outside system.

You can make it explicit in plain language, for example: "This test fails about one run in five. Use structured debugging to find the cause before changing anything."

• Name the symptom and say it is intermittent, flaky or impossible
• Mention that a previous fix did not work, so the agent starts from evidence
• Ask for the investigation notes file if you want a record across sessions

What the investigation looks like in practice

For bugs expected to take more than one round, the method asks the agent to create a side note file in the location the project uses for such notes. The file holds the hypothesis, the evidence from each run and the next hypothesis. The agent re-reads it at the start of each round.

The worked example in the skill concerns a qwen-code command that printed nothing in a zsh terminal while output captured through a pipe looked correct. The skill uses it to show that a contradiction between environments is evidence, and that the data flowing through the code matters as much as whether the code runs.

• Write a specific hypothesis before touching code
• Log values (return codes, payloads, message bodies) rather than simple presence checks
• Confirm logs are not discarded, for example by 2>/dev/null, before running
• After 3 rounds without progress, question your assumptions
• Apply a fix only once logs confirm the root cause, then remove instrumentation and verify with a clean run

Check persistent state first

The skill names persistent state as a common source of impossible bugs. Caches, session recordings, message queues, temp files and database rows can carry leftovers from previous runs, so the code is correct but the data is wrong. When behaviour seems irrational, the agent checks whether state persists across runs, whether it was cleared, and whether the system is reading stale data.