Test driven development skill: how Superpowers enforces TDD for agents

Source: obra/superpowers · Maintainer: community: Jesse Vincent (Prime Radiant) · License: MIT · Checked: 24 October 2026

What is the test driven development skill?

The test driven development skill makes a coding agent follow strict red, green, refactor: write one failing test, watch it fail for the right reason, write the least code that passes, watch it pass, then clean up. If the agent writes production code before a test, the skill tells it to delete that code and start again.

It ships in Superpowers, the open source skill library by Jesse Vincent and Prime Radiant. The skill's description is short: "Use when implementing any feature or bugfix, before writing implementation code".

Its core principle: "If you didn't watch the test fail, you don't know if it tests the right thing." As of 24 October 2026, its skills.sh page listed about 259,100 installs (snapshot, 24 October 2026).

What does it do?

The Superpowers README places it at step five of the workflow: it "Activates during implementation." It applies to new features, bug fixes, refactoring and behavior changes. The listed exceptions are throwaway prototypes, generated code and configuration files, and the agent is told to ask you before using one.

The folder holds two files:

• SKILL.md: the cycle, the rules, a bug fix example, a checklist and a table of excuses with rebuttals.
• writing-good-tests.md: the reference the agent reads whenever it writes or changes a test, adds a mock or adds a test helper.

The rule everything hangs on is the "Iron Law":

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

The cycle has five stops:

1. Red. Write one minimal test for one behavior, with a clear name and real code. Mocks only if unavoidable.
2. Verify red. Marked "MANDATORY. Never skip." The test must fail, not error, with the expected message, because the feature is missing rather than because of a typo. A test that passes at once is testing existing behavior.
3. Green. Write the simplest code that passes. No extra options, no refactoring of other code.
4. Verify green. The new test passes, other tests still pass, and the output has no errors or warnings. The skill is explicit that this means running the project's whole test command, not only the file you touched, and reporting any failure by name, even one you didn't cause.
5. Refactor. After green only: remove duplication, improve names, extract helpers, keep tests green, add no behavior.

The rest of the SKILL.md is aimed at the excuses agents (and people) make. A table answers lines such as "Too simple to test", "I'll test after" and "Deleting X hours is wasteful". A red flags list (code before test, a test that passes immediately, "just this once") ends with an instruction to delete the code and start over with TDD. For bugs, the rule is "Never fix bugs without a test."

What writing-good-tests.md adds

The reference rests on two principles: "Every test names the break it catches" and "Every test exercises the real thing". In practice that means:

• Name the break first. Before writing the test body, say which production change should make it fail.
• Derive expected values by hand. A value computed by the code under test passes no matter what the code does.
• No change detectors. Don't assert a constant's value or exact wording; test the behavior that depends on it.
• The mock earns no assertions. Assert the real component's behavior, mock only the slow or external level, and mirror real data structures completely.
• Run the mutation check. Before finishing, imagine a wrong constant, a wrong branch, a missing side effect, an empty return or missing validation. At least one test should fail for each.

How do you install the test driven development skill?

As part of Superpowers in Claude Code. The README's install section installs it from Anthropic's official marketplace:

/plugin install superpowers@claude-plugins-official

Plugin skills are namespaced as /plugin-name:skill-name per the Claude Code skills docs, so it appears as /superpowers:test-driven-development. The README also documents the obra/superpowers-marketplace route and installs for Codex, Cursor, Gemini CLI, GitHub Copilot CLI and other agents.

Just this skill. The skills CLI copies one folder, as shown on the skills.sh page:

npx skills add https://github.com/obra/superpowers --skill test-driven-development

Add -g to install for all projects. The folder lands in .claude/skills/test-driven-development/ in your project, or ~/.claude/skills/test-driven-development/ with -g. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

claude.ai. The Claude help article on skills lets you upload a skill folder as a ZIP in Customize > Skills. That works under the MIT License, but the skill is most useful where the agent can run your test suite.

How do you use it?

In the full plugin it activates on its own once implementation starts. On its own, any request to build a feature or fix a bug can trigger it, or you can name it.

Example prompts (suggestions, not quotes from the repo):

• /superpowers:test-driven-development Add rate limiting to the login endpoint: 5 attempts per minute per IP.
• Fix the bug where an empty email passes signup validation. Reproduce it with a failing test first.
• Refactor the invoice totals module. Use test-driven-development and add tests for the current behavior before changing anything.
• Review the tests in cart.test.ts against writing-good-tests.md and run the mutation check.

Requirements: a working test runner in your project. The examples use TypeScript with Jest-style test and expect, and the skill names npm test, pytest and cargo test as typical suite commands. No packages, keys or scripts come with it.

How does it compare with Matt Pocock's tdd skill?

Both skills insist on a failing test before code and both are MIT licensed. They differ on scope and on refactoring. Our tdd skill page covers Matt Pocock's version in detail.

Pick Superpowers if you want TDD applied to every change as part of a fixed workflow. Pick Matt Pocock's skill if you want to agree up front where tests go and keep refactoring for review.

Tips and limits

From the files, not from testing:

• It is strict on purpose. "Violating the letter of the rules is violating the spirit of the rules." If you want exceptions beyond the three listed, say so in your instructions; Superpowers says your instructions take precedence over its skills.
• Expect deleted code. If you paste half-finished code and ask for tests, the skill's rule is to throw it away and rebuild test-first. Tell the agent if you want characterization tests for existing code instead.
• Full suite every time. Verify green means the whole project suite. On a slow suite, that adds time to each cycle.
• No scripts run. The skill is instructions only; the agent runs your own test command.
• Audits. As of 24 October 2026, skills.sh showed Pass from Gen Agent Trust Hub, Socket and Snyk.
• License. Superpowers is MIT, so you can copy and edit the skill if you keep the copyright notice.

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 writing-good-tests.md; for a repo with many skills it shows a list to pick from, so you can take systematic-debugging and verification-before-completion in the same import. 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 Jesse Vincent, Prime Radiant or Superpowers.

Similar skills

• TDD skill: Matt Pocock's TDD reference that tests only at agreed seams.
• Systematic debugging skill: find the root cause, then write the failing test that proves the fix.
• Verification before completion skill: fresh test output before the agent claims anything is done.
• Requesting code review skill: the review step that checks tests and code after each task.