Skills Prompts

Popular categories

Agent skill · Skills for Real Engineers

/diagnosing-bugs A gated debugging loop for hard bugs

The diagnosing-bugs skill gives a coding agent a fixed sequence for hard bugs and performance regressions: build a fast loop that reproduces the failure, shrink it, rank testable hypotheses, probe one variable at a time, then fix with a regression test. Each phase has exit criteria, which stops the agent from guessing at causes too early.

Works with

  • Claude Code
  • Codex
  • GitHub Copilot
  • Gemini CLI
  • Cursor, OpenCode, Windsurf, Amp and others

Used forDebugging

When to use it

  • Something is broken, throwing or failing and the cause is not obvious.
  • A feature has become noticeably slower and you need to find out why.
  • A bug is intermittent and earlier attempts to fix it did not hold.

How it works

  1. 1
    Build a feedback loop

    The agent creates one fast, repeatable command, such as a failing test, curl script or browser script, that shows the reported symptom.

  2. 2
    Reproduce and minimise

    It confirms the loop shows the user's exact failure, then removes inputs and steps until only essential ones remain.

  3. 3
    Rank hypotheses

    It lists three to five falsifiable explanations, each with a prediction, and shows them to you before testing.

  4. 4
    Instrument

    It probes one variable at a time with a debugger or tagged logs, or measures a baseline first for performance issues.

  5. 5
    Fix and clean up

    It writes a regression test at a suitable seam, applies the fix, re-runs the original loop and removes debug code.

What it steers the agent away from

  • Reading code and theorizing before the bug can be reproduced
  • Fixing a nearby failure instead of the one the user reported
  • Leaving stray debug logs and throwaway harnesses in the codebase

Install this skill

It installs with the Skills for Real Engineers pack.

Claude CodeInstalled as a plugin that updates itself by default.
claude plugin install mattpocock-skills@claude-plugins-official
CodexUpdates at startup.
codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock
GitHub CopilotWorks in the CLI and VS Code; the README also shows a one-time settings.json entry to enable auto-update.
copilot plugin marketplace add mattpocock/skills
copilot plugin install mattpocock-skills@mattpocock
Gemini CLIRe-run both commands to update.
gemini skills install https://github.com/mattpocock/skills.git --path skills/engineering
gemini skills install https://github.com/mattpocock/skills.git --path skills/productivity
Cursor, OpenCode, Windsurf, Amp and othersCopies editable files into your project; update with npx skills@latest update. Use either this or a plugin per agent, not both.
npx skills@latest add mattpocock/skills -a <agent>

Commands come from the author’s README; check it for changes before you run them.

Questions

What if the bug cannot be reproduced?

The skill tells the agent to stop, list what it tried and ask you for environment access, a redacted log or trace, or permission to add temporary instrumentation.

Does it handle performance problems?

Yes. For regressions it measures a baseline with timers, a profiler or query plans and bisects, rather than relying on logs.

More guides from Skills for Real Engineers

Also in this pack

All 39 skills →

Summary by trendhub. The skill itself lives in mattpocock/skills/skills/engineering/diagnosing-bugs by Matt Pocock (MIT); read the full, current text there.