Source: mattpocock/skills · Maintainer: community: Matt Pocock · License: MIT · Checked: 23 October 2026
What is the diagnosing bugs skill?
diagnosing-bugs is a debugging skill for Claude Code and other agents that stops the agent from reading code and guessing. It must first build a fast command that fails on your exact bug, then shrink the repro, rank hypotheses, test them, and fix with a regression test. It is for developers chasing hard bugs: intermittent flakes, regressions between two known states, slow endpoints.
It lives in mattpocock/skills, where the README describes it as wrapping "best debugging practices into a disciplined loop, gated phase by phase." The skill's description: "Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow."
As of 23 October 2026, its skills.sh page listed about 830,000 installs.
What does it do?
The SKILL.md calls Phase 1 "the skill" and treats everything after it as mechanical. The phases are gates: the agent cannot move on until each condition holds.
- Build a feedback loop. One command, already run once, that drives the real code path, asserts your exact symptom, gives the same verdict every run, finishes in seconds and runs without you. The skill lists ten ways to build one, in rough order: a failing test, a curl script against a dev server, a CLI run diffed against a snapshot, a headless browser script, a replayed trace, a throwaway harness, a fuzz loop, a
git bisect runharness, a differential run of old against new, and as a last resort a human-in-the-loop script. For flaky bugs the goal is a higher reproduction rate, not a clean repro. If no loop is possible, the agent must stop, list what it tried, and ask you for access, an artifact, or permission to add instrumentation. - Reproduce and minimise. Confirm it is your failure, not a nearby one, then cut inputs and steps one at a time until every remaining piece is needed.
- Hypothesise. Write 3 to 5 ranked hypotheses, each with a prediction that could prove it wrong, and show you the list before testing.
- Instrument. One variable at a time, debugger first, then targeted logs tagged with a unique prefix like
[DEBUG-a4f2]so cleanup is one grep. For performance bugs: measure a baseline, then bisect. - Fix and regression test. Write the failing test before the fix, but only at a seam that reproduces the real bug pattern. If no such seam exists, that is reported as a finding.
- Clean up. Re-run the loop, remove tagged logs and throwaway code, and name the correct hypothesis in the commit or PR message.
A Redact section tells the agent to replace secrets with <REDACTED> in anything it shows, and to keep credentials in environment variables.
What's in the folder:
SKILL.md: the six phases and their checklists.scripts/hitl-loop.template.sh: a short bash template for bugs that need a human to click. The agent copies and edits it; when run, it prints instructions in your terminal and reads your answers withread, then prints them asKEY=VALUElines for the agent.agents/openai.yaml: Codex metadata ("Diagnosing Bugs").
How do you install the diagnosing bugs skill?
Pick one route per agent; the README warns that a plugin plus file install gives you every skill twice.
Claude Code plugin (whole set). From the README, via Anthropic's official plugin marketplace:
claude plugin install mattpocock-skills@claude-plugins-official
Look for it as /mattpocock-skills:diagnosing-bugs, since Claude Code namespaces plugin skills.
Codex plugin. From the README:
codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock
Just this skill. It loads no other skills, so one flag is enough with the skills CLI:
npx skills add mattpocock/skills --skill diagnosing-bugs
Add -g for every project. For Claude Code the folder lands in .claude/skills/diagnosing-bugs/, or ~/.claude/skills/diagnosing-bugs/ with -g, the standard Claude Code skill locations. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills. The skill runs commands against your code, so it belongs in a coding agent rather than a claude.ai chat.
How do you use it?
Type /diagnosing-bugs with the symptom, or describe the bug and let the agent load it. The docs page says to save it for hard bugs: it is slow and thorough on purpose.
Example prompts (suggestions, not quotes from the repo):
/diagnosing-bugs The export button throws "undefined is not a function" for about one user in ten.- "Debug this: the nightly import job started taking 40 minutes after last Tuesday's deploy. It used to take 5."
- "This test fails on CI maybe 1 run in 20 and never locally. Diagnose it."
- "Checkout returns 500 only when the cart has a discount code. Find the cause and lock it down with a test."
No packages or keys are required. It uses whatever your project already has: a test runner, curl, Playwright or git bisect. If it cannot reach the environment that reproduces the bug, it will ask you.
How does it compare with systematic-debugging?
The other widely used option is systematic-debugging from obra/superpowers, also MIT licensed. Both refuse to let the agent jump to a fix, but they put the gate in different places.
| diagnosing-bugs | systematic-debugging | |
|---|---|---|
| Central rule | No hypotheses until a tight, red-capable loop exists | "NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST" |
| Phases | Six: loop, minimise, hypothesise, instrument, fix, clean up | Four: root cause, pattern analysis, hypothesis and testing, implementation |
| Triggers on | Hard bugs, "diagnose", "debug this", broken or slow | Any bug, test failure or unexpected behavior |
| Extras | Human-in-the-loop script, tagged debug logs, redaction rules | Supporting notes on root cause tracing, defense in depth, condition-based waiting |
In short, diagnosing-bugs is the heavier tool for bugs you can't crack at first look, and systematic-debugging is meant to run on every bug, simple ones included.
Tips and limits
From the repo's docs, not from testing:
- It can fire too eagerly. The docs report it triggering on simple questions with some models and building a repro before answering. Say what you want, or disable model invocation for it.
- No pause before the fix. The only human checkpoint is the hypothesis list. If you want to approve the root cause before code changes, say so when you start.
- Not an audit. It diagnoses one named failure. It won't sweep a codebase for performance problems.
- Missing seams. When it can't write an honest regression test, the docs point you to the improve codebase architecture skill.
- Secrets. The SKILL.md asks the agent to redact, but check pasted logs, HAR files and dumps yourself before they go into an issue or PR.
- Security audits. As of 23 October 2026, skills.sh showed Gen Agent Trust Hub, Socket and Snyk all as Pass. The docs mention an earlier Snyk flag, caused by the shipped shell script, which they call a false positive. The script only prompts and reads input; review it before use.
- License. MIT.
Save it in your Kipt library
In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and its files, including the script; for a repo with many skills, like this one, it shows a list to pick from. You can also drop the folder or a .zip. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Matt Pocock or mattpocock/skills.
Similar skills
- Systematic debugging skill: the Superpowers alternative compared above.
- TDD skill: Matt Pocock's red-green loop for building, the natural next step once a bug is pinned by a test.
- Improve codebase architecture skill: for when the bug has no good seam to test at.
- Superpowers skills: the full Superpowers workflow that systematic-debugging belongs to.