# Skills That Make Agents Test and Debug Properly

URL: https://developertoolkit.ai/en/ecosystem/skills/testing-debugging-skills/
Description: Install tdd, diagnosing-bugs, systematic-debugging and verification-before-completion in Claude Code, Codex and Cursor, and prove every fix.

Testing and debugging skills are Agent Skills that make a coding agent reproduce a bug, write the failing test first and show command output before it claims "fixed": Matt Pocock's `tdd` and `diagnosing-bugs`, Superpowers' `test-driven-development`, `systematic-debugging` and `verification-before-completion`, and Anthropic's `webapp-testing`. The skills shape behaviour but enforce nothing; CI and a protected test suite do.

The pattern they fix: a customer reports a wrong date, the agent edits three lines and says "Fixed", and nothing shows the bug reproduced or the fix proven. A week later the bug is back in another time zone. This page is for developers who want the agent to debug like a careful colleague, and for tech leads who want every agent fix to arrive with evidence a reviewer can check without rereading the diff.

## What you get from testing and debugging skills

- A shortlist of six skills, what each one makes the agent do, and which to combine so they do not fight
- Install commands for Claude Code, Codex and Cursor, checked against the skills CLI 1.7.0 on 2026-09-26
- A worked `systematic-debugging` session, from a customer bug report to a regression test that failed before it passed
- A red-green-refactor workflow that ends in pasted verification evidence, not a claim
- The gates outside the agent that prove the skills worked, and the failure modes to watch for

## Which testing and debugging skills are worth installing?

Six skills cover testing and debugging. They come from three repositories: `mattpocock/skills`, `obra/superpowers` (the Superpowers methodology) and `anthropics/skills`.

| Skill | Repository | What it makes the agent do | Fires |
| --- | --- | --- | --- |
| `tdd` | mattpocock/skills | Agrees the test seams with you first, then one failing test and the minimum code per slice. Refactoring moves to the review stage | When you ask for test-first work, red-green-refactor or integration tests |
| `diagnosing-bugs` | mattpocock/skills | Builds a fast pass/fail feedback loop that goes red on this bug before any theory, then 3–5 ranked, falsifiable hypotheses | When you say "diagnose" or "debug this", or report something broken or slow |
| `test-driven-development` | obra/superpowers | Strict red-green-refactor. Code written before its test is deleted and rewritten | Before any feature or bugfix code |
| `systematic-debugging` | obra/superpowers | Four phases: root-cause investigation, pattern analysis, one hypothesis at a time, then a failing test and a single fix. Stops after three failed fixes to question the design | On any bug, test failure or unexpected behaviour |
| `verification-before-completion` | obra/superpowers | No success claim without fresh output from the command that proves it | Before the agent says done, fixed or passing, or commits |
| `webapp-testing` | anthropics/skills | Writes Python Playwright scripts against a local web app, with a server-lifecycle helper, screenshots and console logs | When you ask it to test or debug a local web UI |

**Popularity, as of 2026-09-26:** all-time installs on skills.sh were `tdd` 966,524, `diagnosing-bugs` 665,090, `systematic-debugging` 271,653, `test-driven-development` 236,900, `verification-before-completion` 221,579 and `webapp-testing` 164,051. These counts come from the third-party `LinklyAI/best-skills` scrape dated 2026-09-26 (a secondary source; check the live numbers on skills.sh). GitHub stars on the same date: obra/superpowers 291.7k, mattpocock/skills 269.8k, anthropics/skills 178.4k.

**`/debug` is not a debugging method**

In Claude Code 2.1.283, `/debug` is a bundled skill that turns on session debug logging and reads the Claude Code session log. It troubleshoots Claude Code itself, not your application. For an application bug, use `systematic-debugging` or `diagnosing-bugs`. The bundled `/verify` skill is closer to this page's topic: it builds and runs your app to confirm a change.

### Pocock or Superpowers: which set should you pick?

Pick one family for tests and one for debugging. Two skills that fire on the same trigger give the agent two conflicting procedures.

| If your team… | Install | Why |
| --- | --- | --- |
| wants to agree what gets tested before any code | `tdd` + `diagnosing-bugs` (Pocock) | `tdd` refuses to test at a seam you have not confirmed; `diagnosing-bugs` refuses to theorise before a red-capable command exists |
| already runs the Superpowers workflow (brainstorm, plan, subagents) | `test-driven-development` + `systematic-debugging` + `verification-before-completion`, through the Superpowers plugin | The plugin's session-start bootstrap makes the skills fire without being asked; the three cross-reference each other |
| wants lightweight skills plus a hard "show me the output" rule | `tdd` + `diagnosing-bugs` + `verification-before-completion` | Pocock's set had no dedicated completion gate on 2026-09-26; the Superpowers skill fills it and installs on its own |
| builds a web UI and wants browser checks | add `webapp-testing`, or [agent-browser](/en/ecosystem/skills/agent-browser/) | Unit tests do not prove what the user sees |

The two debugging skills differ in their first move. `diagnosing-bugs` spends most of its effort on one command that goes red on the reported symptom in seconds, then ranks several hypotheses and shows you the list. `systematic-debugging` starts from evidence (the full error, recent changes, logs at each component boundary), then tests one hypothesis with the smallest possible change. Pick `diagnosing-bugs` for bugs you can script, `systematic-debugging` for failures spanning CI, services and configuration.

## How do you install the test-and-debug set in Claude Code, Codex and Cursor?

The portable route is one skills CLI command (npm `skills` 1.7.0). Codex and Cursor read the copy in `.agents/skills/`; Claude Code reads `.claude/skills/`. The plugin route adds updates and, for Superpowers, the bootstrap that makes the method fire automatically.

1. **Install the skills at project scope.** Run this in the repository root.

    **Claude Code**

    ```bash
    # Option A: plugins from the official marketplace (update themselves)
    claude plugin install mattpocock-skills --scope project
    claude plugin install superpowers@claude-plugins-official --scope project

    # Option B: portable copies of the recommended mix, no plugins
    npx skills add mattpocock/skills --skill tdd codebase-design diagnosing-bugs -a claude-code -y
    npx skills add obra/superpowers --skill verification-before-completion -a claude-code -y
    ```

    Plugin skills are namespaced: `/mattpocock-skills:tdd`, `/superpowers:systematic-debugging`. Portable copies keep the bare name: `/tdd`, `/diagnosing-bugs`. `--scope project` records the plugin in `.claude/settings.json`, which you commit. If `claude plugin install` reports that the marketplace is unknown (for example, in a fresh CI container), run `claude plugin marketplace add anthropics/claude-plugins-official` first. The official marketplace pins Superpowers 6.4.1; the author's `superpowers-marketplace` carries 6.4.2 (both checked 2026-09-26).

    **Codex**

    ```bash
    npx skills add mattpocock/skills --skill tdd codebase-design diagnosing-bugs -a codex -y
    npx skills add obra/superpowers --skill verification-before-completion -a codex -y
    ```

    Codex reads `.agents/skills/`; `/skills` in the TUI lists what loaded, and `$diagnosing-bugs` invokes a skill by name. For the full Superpowers method, install the plugin instead: type `/plugins` in the Codex TUI, search for "superpowers" and choose **Install**. It is listed in OpenAI's `openai-curated` marketplace.

    **Cursor**

    ```bash
    npx skills add mattpocock/skills --skill tdd codebase-design diagnosing-bugs -a cursor -y
    npx skills add obra/superpowers --skill verification-before-completion -a cursor -y
    ```

    Cursor reads the same `.agents/skills/` copies. For the full Superpowers method, type `/add-plugin superpowers` in Agent chat (the route the Superpowers README documents). Cursor's skills docs (checked 2026-10-12) list `.agents/skills/` among the places it loads skills from; if a skill does not appear, ask the agent to use it by name.

    If the team uses more than one agent, install once for all of them: `npx skills add mattpocock/skills --skill tdd codebase-design diagnosing-bugs -a claude-code -a codex -a cursor -y`. In a test run with skills 1.7.0 on 2026-09-26, that wrote one copy to `.agents/skills/` and symlinked it into `.claude/skills/`; a Claude Code-only install copies straight into `.claude/skills/`. The Pocock README also asks for `setup-matt-pocock-skills`; neither `tdd` nor `diagnosing-bugs` calls it, so add it only if you use the rest of the set.

2. **Add `webapp-testing` if you test a web UI.** `npx skills add anthropics/skills --skill webapp-testing -a claude-code -a codex -a cursor -y`, or in Claude Code `/plugin marketplace add anthropics/skills` then `/plugin install example-skills@anthropic-agent-skills` (a bundle of 12 skills). The skill writes Python, so the machine needs Python with the `playwright` package (1.63.0 on PyPI on 2026-09-26) and a browser from `python -m playwright install chromium`.

3. **Check what landed.** `npx skills list` shows the installed skills. `codebase-design` must sit next to `tdd`: `tdd` calls it when the shape of an interface is in question. In Claude Code, `claude plugin details mattpocock-skills` prints the plugin's inventory and projected token cost.

4. **Read what you installed, then commit it.** Skills run with the agent's permissions. Commit `.agents/skills/`, `.claude/skills/` and `skills-lock.json` (or `.claude/settings.json` for plugins), so a pull request, not a chat message, changes the team's set.

**Traps when installing testing and debugging skills**

- **`diagnose` is the old name.** Pocock renamed it `diagnosing-bugs`; the old folder returns 404 on `main`, yet `mattpocock/skills@diagnose` still shows 239,259 installs in the 2026-09-26 snapshot. A high count does not mean the skill still installs.
- **`--skill=<name>` is silently ignored** by skills CLI 1.7.0. With `-y` it installs every skill in the repository. Write `--skill tdd` with a space.
- **The portable Superpowers copy does not bootstrap.** `npx skills add obra/superpowers` has no session-start hook, so `systematic-debugging` fires only from its description or when you name it. The plugin fires the method on its own.
- **`systematic-debugging` ships test fixtures.** The install includes `test-academic.md` and `test-pressure-1.md` to `test-pressure-3.md`; the pressure tests tell the reader "This is a real scenario. You must choose and act" (reported in issue #2277 on 2026-09-10; still shipped in the 2026-09-26 install). They are pressure tests for the skill, not instructions for your repository. Read them before you commit the folder.
- **Install from the canonical owners.** skills.sh lists unrelated repositories named `*/superpowers` with six-figure counts. Only `obra/superpowers` is the Superpowers methodology.

## What does a systematic-debugging session look like on a real bug report?

The bug report below is the input. The transcript is an abridged illustration of the steps the `systematic-debugging` skill prescribes. It is not a recorded run, and the repository, commit and numbers are invented for the example.

```text
Issue #318  Renewal date shown one day early for NZ customers
Customers in Auckland see "Renews on 14 March 2027" on the account page.
The card is charged on 15 March. Started after release 3.8.0.
```

**Copy-paste prompt: debug a bug report without guessing**

```text
Use the systematic-debugging skill on issue #318 (renewal date shown one day early for
customers in New Zealand, since release 3.8.0). Complete phase 1 before you propose any
fix: reproduce the exact symptom with a command I can rerun, read the full error or
output, and list the commits since 3.7.2 that touch src/billing. State one hypothesis
and the smallest experiment that would prove it wrong. Write the failing regression
test before the fix. Do not change more than one thing per experiment.
```

What the agent does, phase by phase:

```text
Phase 1: root cause investigation
  Symptom is the displayed date; the charge date is correct.
  $ TZ=Pacific/Auckland npx vitest run src/billing/renewal.test.ts
    6 passed                       <- existing tests do not cover the symptom
  $ TZ=Pacific/Auckland npx tsx scripts/print-renewal.ts --sub sub_1042
    renewsOn: 2027-03-14           (charge job uses 2027-03-15)
  $ git log --oneline v3.7.2..v3.8.0 -- src/billing
    a41c9e2 replace date-fns addMonths with native Date arithmetic

Phase 2: pattern analysis
  Working: src/invoices/period.ts builds dates with Date.UTC(...)
  Broken:  src/billing/renewal.ts builds new Date(year, month + 1, day) in local time,
           then serialises with toISOString()

Phase 3: hypothesis and minimal test
  Hypothesis: local midnight in UTC+13 serialises to the previous day in UTC.
  Prediction: the same script with TZ=UTC prints 2027-03-15.
  $ TZ=UTC npx tsx scripts/print-renewal.ts --sub sub_1042
    renewsOn: 2027-03-15           prediction holds

Phase 4: implementation
  Failing test first: "renews on the same calendar day in UTC+13"
  $ TZ=Pacific/Auckland npx vitest run src/billing/renewal.test.ts
    1 failed, 6 passed  expected '2027-03-15', received '2027-03-14'
  Single fix: addBillingMonths() builds the date with Date.UTC
  $ TZ=Pacific/Auckland npx vitest run src/billing/renewal.test.ts
    7 passed
```

That transcript shows what you pay the skill for: the agent proved the existing tests were blind to the symptom, named the commit that introduced the bug, and made the regression test fail with the customer's exact symptom before the fix turned it green. Had the fix failed, the skill would send the agent back to phase 1; after three failed fixes it stops and asks whether the design is wrong.

For the same bug with `diagnosing-bugs`, expect a different shape: the agent first builds the `TZ=Pacific/Auckland` script as its one red-capable command, shrinks the scenario to the smallest input that still fails, then shows you three to five ranked hypotheses before it tests any of them. It tags temporary logs with a prefix such as `[DEBUG-a4f2]` and removes them with one `grep` at the end.

**Copy-paste prompt: build the feedback loop first**

```text
Use the diagnosing-bugs skill. The CSV export on /reports times out for accounts with
more than 10,000 rows since Tuesday's deploy. Phase 1 only for now: build one command
that reproduces the timeout in seconds, run it, and show me the invocation and its
output with secrets redacted. Then minimise the scenario and show me your 3 to 5 ranked
hypotheses, each with the prediction that would falsify it. Wait for my reply before
you instrument or change code.
```

## How do you run red-green-refactor with verification evidence before "done"?

The skills slot into one loop. The loop is the same in all three agents; only the invocation differs. It starts from a bug report or an acceptance criterion and ends with evidence a reviewer can check without reading every line.

1. **Record the baseline.** Before any change, the agent runs the full suite, the type check and the linter and saves the result. A test that was already red is recorded as known, so it cannot later hide or pose as a regression.

2. **Agree the seam (Pocock `tdd`).** The agent names the public interface it will test through and waits for your confirmation. For a bug, the seam is where the reported symptom is observable. A seam too shallow to express the bug gives false confidence; `diagnosing-bugs` treats "no correct seam exists" as a finding in its own right.

3. **Red.** One failing test for one behaviour. The agent runs it and shows the failure message, which must be the expected failure (the wrong date), not a typo or a missing import. Superpowers' skill states the reason: if you did not watch the test fail, you do not know it tests the right thing.

4. **Green.** The minimum code that passes. No speculative options, no neighbouring clean-up.

5. **Refactor while green.** Superpowers refactors inside the loop and re-runs the tests after each change. Pocock's `tdd` moves refactoring to the review stage and its `code-review` skill. Either way, the tests stay green through every structural change.

6. **Prove the test can catch the bug.** Revert the fix, run the new test and watch it fail; restore the fix and watch it pass. `verification-before-completion` names this red-green cycle as the proof that a regression test works; a test that passes once proves nothing.

7. **Show the evidence, then claim done.** The agent runs the full suite, the type check, the linter and, for UI changes, a browser check. It pastes the commands with their exit codes and failure counts, then compares them with the baseline from step 1.

8. **Hand off to CI and review.** The pull request carries the evidence; CI re-runs the same commands on clean infrastructure. A red CI run overrides any "done" in the chat.

**Copy-paste prompt: a test-first fix with a red-green check**

```text
Fix issue #318 test-first. First run the full test suite, the type check and the linter
and record the baseline. Tell me which public interface you will test through and wait
for my OK. Then: write one failing test that reproduces the reported symptom, run it and
show me the failure message; write the minimum fix; run it green. Finally revert only the
fix, show the new test failing, restore the fix and show it passing. Do not edit or
delete any existing test.
```

**Copy-paste prompt: evidence before you say done**

```text
Before you tell me this is finished, use verification-before-completion. Run, fresh in
this turn: the full test suite, the type check and the linter. Paste each command with
its exit code and pass/fail counts, and compare them with the baseline you recorded at the
start. List every acceptance criterion from the issue with the command or test that
proves it. If anything is unverified or red, say so plainly instead of summarising.
```

**Claude Code**

With plugins, name the skill when you want it for certain: `/superpowers:systematic-debugging`, `/mattpocock-skills:tdd`. Add `/verify` after step 7 when the change is visible in the running app; it builds and drives the app rather than relying on tests. Put the step 1 baseline and step 6 red-green rule in `CLAUDE.md`, so they hold even when a skill does not fire.

**Codex**

Invoke skills with `$`: `$diagnosing-bugs`, `$tdd`, `$verification-before-completion`. Codex runs commands inside its sandbox, so a test that needs a network port or a local database may fail there and pass on your machine. Read that as a sandbox difference to resolve, not as a flaky test to retry. Run Codex's built-in `/review` on the diff before you open the pull request.

**Cursor**

Name the skill in Agent chat ("use the systematic-debugging skill"), or type it as a slash command if your Cursor build lists it. Keep the whole loop in one chat so the baseline from step 1 stays in context, and add the step 6 rule to your project rules, so it applies to agents that did not load the skill.

## How do you check a web UI with webapp-testing?

`webapp-testing` covers bugs that only show in the browser. It teaches a "reconnaissance-then-action" pattern: wait for the page to settle, take a screenshot or read the DOM, find selectors from what rendered, then act. Its `scripts/with_server.py` helper starts one or more dev servers, waits for their ports and runs your Playwright script against them.

**Copy-paste prompt: reproduce a UI bug in a real browser**

```text
Use the webapp-testing skill. Start the app with scripts/with_server.py (run it with
--help first) using "npm run dev" on port 5173. Reproduce this report: submitting the
settings form with an empty email shows no validation error. Write a headless Playwright
script that fills the form, submits it, saves a full-page screenshot to
.evidence/settings-empty-email.png and prints every console error. Tell me whether the
bug reproduces, with the script output. Do not change application code yet.
```

Once the bug reproduces in the browser, the script becomes the red-capable command for the loop above. When the fix lands, promote it into your [end-to-end suite](/en/workflows/test/e2e-testing/) so it runs on every change. If your agents already use `agent-browser`, stay with it: same CLI in all three agents, no Python. The [agent-browser page](/en/ecosystem/skills/agent-browser/) compares both with the Playwright and Chrome DevTools MCP servers.

## How do you prove the skills did their job?

A skill changes what the agent tends to do. It does not guarantee it: a skill can fail to fire, and an agent can misread its own output. The proof therefore sits outside the agent.

- **CI re-runs the evidence.** The commands the agent pasted run again in CI on the pull request. The pasted output is a convenience for the reviewer; the CI result is the gate.
- **The test is protected.** A debugging agent under pressure can "fix" a failing test by editing the assertion. Put tests under the deny rules and CODEOWNERS described in [protecting the oracle](/en/workflows/test/protect-the-oracle/), and fail any pull request that deletes or skips a test without a named approver.
- **The red-green check is in the pull request.** The reviewer checks one thing: the new test failed with the reported symptom before the fix and passes after. Attach it to the [evidence bundle](/en/workflows/ship/evidence-bundle/) with the root-cause commit the agent found.
- **The skill set is tested too.** Before you standardise a skill for the team, check that it triggers on your prompts. In Claude Code 2.1.283, `claude plugin eval` runs a plugin's eval cases against a no-plugin baseline; Anthropic's `skill-creator` skill runs test prompts with and without a skill.

**Who signs off.** The developer who opens the pull request owns the evidence. The reviewer approves on the red-green check, the root cause and a green CI run, and reads code line by line only for high-risk paths (auth, money, schema migrations). The tech lead owns the committed skill set and changes it through review, like any other code.

## What do testing and debugging skills cost in context?

Each installed skill puts its name and description into every session; the body loads only when the skill fires. Measured on 2026-09-26:

| What loads | When | Size |
| --- | --- | --- |
| `tdd` / `diagnosing-bugs` `SKILL.md` | When the skill fires | 3,549 / 8,529 bytes |
| `test-driven-development` / `systematic-debugging` `SKILL.md` | When the skill fires | 9,578 / 9,465 bytes |
| `verification-before-completion` / `webapp-testing` `SKILL.md` | When the skill fires | 3,646 / 3,913 bytes |
| `superpowers@claude-plugins-official` plugin (15 skills) | Every session | about 838 tokens, `claude plugin details` in Claude Code 2.1.283 |
| `mattpocock-skills@claude-plugins-official` plugin (25 skills) | Every session | about 1,609 tokens, same measurement |

A fired debugging skill costs about 2,000–2,500 tokens (roughly four bytes per token). The larger cost is duplicates: the Superpowers plugin plus a portable copy of the same skills lists each one twice. In Claude Code, compare `/context` before and after an install.

## What breaks when agents follow testing and debugging skills?

**Two skills fire on the same bug.** With `diagnosing-bugs` and `systematic-debugging` both installed, the agent starts one procedure and drifts into the other. Recovery: keep one debugging skill per repository and `npx skills remove` the other.

**The agent writes a test that passes at once.** The test was written against the current behaviour, or its assertion recomputes the expected value the way the code does. Pocock's `tdd` names that second case "tautological". Recovery: insist on a red run with the reported symptom in the failure message, and on the revert-the-fix check before any "done".

**The skill does not fire on a terse request.** "fix the date thing" may not match a skill's description. Recovery: name the skill in the prompt, install Superpowers as a plugin so the bootstrap runs, or add a line to `CLAUDE.md` or `AGENTS.md`: "For any bug report, use the systematic-debugging skill before proposing a fix."

**The feedback loop is flaky.** A test that fails one run in three turns every hypothesis into noise. Recovery: pin the time, seed randomness and isolate the filesystem, as `diagnosing-bugs` prescribes. For intermittent tests, replace fixed sleeps with condition polling (Superpowers' `condition-based-waiting.md`). When a test leaves stray files, use `find-polluter.sh` from the same skill folder to bisect which test creates them.

**The agent loops through fixes.** Each fix reveals a new symptom somewhere else. Recovery: stop after the third failed fix, which `systematic-debugging` requires, and discuss the design with a human before any fourth attempt.

**Verification stalls on tests that were red before you started.** Without a baseline, the agent cannot tell an old failure from a new regression and keeps retrying. Recovery: record the baseline first (step 1 of the loop) and report old failures separately; never let the agent skip a test file without a written team policy.

## Where to go next with testing and debugging skills

- [Test-driven development with AI](/en/method/principles/test-driven-development/) — The method behind the skills: why the confirmed red step matters and how to split the loop into turns.
- [The 25 most-installed practice skills](/en/ecosystem/skills/top-practice-skills/) — The wider ranking, and the grill, spec, tdd and review loop these skills slot into.
- [Code review skills](/en/ecosystem/skills/code-review-skills/) — The stage after the loop: review skills and bots that check the diff against your standards and the spec.
- [Superpowers](/en/ecosystem/frameworks/superpowers/) — The full methodology that ships test-driven-development, systematic-debugging and verification-before-completion.
- [Protecting the oracle](/en/workflows/test/protect-the-oracle/) — Stop a debugging agent from editing the test instead of the code.
- [Skill supply-chain security](/en/ecosystem/skills/skill-security/) — How to review third-party skills and their bundled scripts before the team runs them.

For tool-specific debugging workflows, see [debugging in the Claude Code CLI](/en/claude-code/test/debugging/), [systematic debugging in Codex](/en/codex/test/bug-hunting/) and [AI-assisted debugging in Cursor](/en/cursor-ide/test/bug-hunting/).
