Skip to content
Get packs

Structured Debugging

Makes the agent debug hard bugs with hypotheses, targeted instrumentation and evidence instead of guessing.

Source Download skill
Repository
QwenLM/qwen-code
Stars
28,880
Licence
Apache-2.0
Files
2 files

What it does

It changes how the agent approaches difficult bugs. Instead of guessing a cause and trying fixes, the agent writes down a specific hypothesis, adds a few targeted debug logs, checks that the output will actually be captured, runs the test, and records what the data showed before iterating. It also warns the agent against blaming outside systems like models or APIs without inspecting their inputs first.

Great for

  • Developers stuck on flaky tests, intermittent failures or behaviour that seems impossible
  • Teams whose agents keep trying random fixes after a first attempt fails
  • Debugging sessions that span several rounds and need a persistent investigation journal

Skip it if

  • Simple, obvious bugs where a quick fix is enough, since the multi-step process adds overhead
  • Projects that forbid agents from creating side note files, because the method asks for a persistent notes file in the project's notes location

Try asking

  • “Our integration test hangs intermittently, help me debug it systematically”
  • “The fix I applied didn't work and the behaviour still seems impossible, investigate step by step”
  • “Trace why the agent's subprocess output is empty when run in the background”
Step-by-step guide: how to use Structured DebuggingInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 2 original files, the Apache-2.0 licence and an attribution note.

    structured-debugging.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip structured-debugging.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip structured-debugging.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Give the agent a concrete symptom and a way to reproduce it so it can run the instrumented test
  • Review the side note file it creates to see the hypotheses and evidence before accepting a fix
  • Ask it to check environment differences (TTY vs pipe, env vars, prior state) when your run doesn't match a reported bug

What's inside

  • examples/headless-bg-agent-empty-stdout.md
  • SKILL.md

Redistributed unmodified from QwenLM/qwen-code under the Apache-2.0 licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.