Skip to content
Get packs

Diagnosing Bugs

Guides the agent through a disciplined loop to reproduce, narrow down and fix hard bugs

Source Download skill
Repository
mattpocock/skills
Stars
309,658
Licence
MIT
Files
3 files

What it does

When you ask the agent to debug something broken, failing, slow or throwing errors, this skill makes it follow a strict process: first build a fast, repeatable test that fails on your exact bug, then shrink that test to the smallest failing case, list ranked guesses about the cause, and only then add targeted logging to check them. It also tells the agent to hide secrets such as credentials and auth headers when it shows command output, and to ask you for more information if it cannot reproduce the problem.

Great for

  • Developers stuck on an intermittent, hard-to-reproduce, or performance-regression bug
  • Teams that want an AI agent to avoid guessing at fixes without first reproducing the problem
  • Situations where a human must click through a UI, so a structured manual reproduction loop is useful

Skip it if

  • Simple typos or obvious errors where a quick direct fix is enough, since the process is deliberately heavy (the skill says skip phases only when explicitly justified)
  • Codebases where the agent cannot run anything, because the core method depends on executing a reproduction loop
  • Anyone expecting the skill to guarantee secrets never leak: it relies on the agent redacting output correctly, which is not enforced by code

Try asking

  • “Debug this: the export button throws an error after login”
  • “The checkout page is much slower since last week's release, diagnose it”
  • “Diagnose why the import job sometimes fails about one run in twenty”
  • “This API endpoint returns the wrong total, can you debug it?”
Step-by-step guide: how to use Diagnosing BugsInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 3 original files, the MIT licence and an attribution note.

    diagnosing-bugs.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip diagnosing-bugs.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip diagnosing-bugs.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 the exact symptom, error text, and steps to trigger it so the feedback loop targets the right bug
  • Keep secrets in environment variables so the agent can run the loop without them appearing in shared output
  • Review the ranked hypotheses the agent shows before it tests them, since you may know something that re-ranks them

What's inside

  • agents/openai.yaml
  • scripts/hitl-loop.template.sh
  • SKILL.md

Redistributed unmodified from mattpocock/skills under the MIT 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.