TDD skill for Claude Code: what it does and how to install it

Source: mattpocock/skills · Maintainer: community: Matt Pocock · License: MIT · Checked: 23 October 2026

What is the tdd skill?

The tdd skill gives Claude Code, Codex and other agents a red-green test-driven development loop: one failing test at a boundary you agreed on, just enough code to pass it, then the next behavior. It is for developers who want agent-written tests that check real behavior and survive a refactor.

It comes from mattpocock/skills, which Matt Pocock describes in the README as "My agent skills that I use every day to do real engineering - not vibe coding." The skill's description reads: "Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests."

The README's case for it is about feedback: "Without feedback on how the code it produces actually runs, the agent will be flying blind." As of 23 October 2026, its skills.sh page listed about 1.1 million installs.

What does it do?

The skill is model-invoked, so the agent can load it on its own when a task fits, or you can type /tdd. The repo's docs for tdd describe it as "a reference, not a driver": it holds the rules, and you (or the repo's implement skill) run the session.

What's in the folder:

• SKILL.md: the loop, where tests go, and the anti-patterns.
• tests.md: good and bad test examples in TypeScript, such as testing "user can checkout with valid cart" instead of asserting that a payment service was called.
• mocking.md: mock at system boundaries only (external APIs, time and randomness, sometimes the database or file system), never your own modules, plus advice on dependency injection and SDK-style API wrappers.
• agents/openai.yaml: Codex display metadata ("TDD").

The main rules in the SKILL.md:

• Test through public interfaces. "Code can change entirely; tests shouldn't."
• Test only at pre-agreed seams. A seam is the public boundary where you observe behavior. Before writing any test, the agent lists the seams it wants to test, with a note on what each catches and misses, and waits for you to confirm.
• Avoid three anti-patterns. Implementation-coupled tests (mocking internals, testing private methods), tautological tests (the expected value is computed the same way the code computes it), and horizontal slicing (all tests first, then all code).
• Work in vertical slices. One seam, one test, one minimal implementation per cycle.
• No refactor step. "Refactoring is not part of the loop." It belongs to the repo's code-review skill.

It also tells the agent to read GLOSSARY.md, if one exists, so test names match your project's terms, and to respect ADRs in the area it's changing. Those files come from the domain modeling skill.

How do you install the tdd skill?

The README gives a plugin route and an editable-files route, and says to pick one per agent so you don't get every skill twice.

Claude Code plugin (whole set, updates itself). This installs the collection from Anthropic's official plugin marketplace:

claude plugin install mattpocock-skills@claude-plugins-official

Plugin skills are namespaced as /plugin-name:skill-name, so it appears as /mattpocock-skills:tdd.

Codex plugin. From the README:

codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock

Just this skill, as editable files. The docs list one prerequisite: codebase-design must be installed, because tdd uses its vocabulary for modules, interfaces and seams. The skills CLI takes --skill more than once:

npx skills add mattpocock/skills --skill tdd --skill codebase-design

Add -g for all projects or -a claude-code to target Claude Code directly. The folders land in .claude/skills/tdd/ in your project, or ~/.claude/skills/tdd/ with -g, the standard Claude Code skill locations. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

The README also suggests running /setup-matt-pocock-skills once per repo if you install the engineering set, to choose an issue tracker, triage labels and a docs location. The tdd docs themselves name only codebase-design as a prerequisite.

How do you use it?

Give it a concrete behavior with inputs and an observable output. The docs say it fits business logic, request and response contracts, transformations and validation best.

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

• /tdd Add a discount code to checkout: one code per order, expired codes rejected.
• Fix the bug where invoices round tax down. Write a failing test first.
• Let's do red-green-refactor on the CSV import parser. Start by proposing the seams.
• Add integration tests for the signup endpoint before we change how it validates emails.

Expect it to stop first and name the seams it plans to test. If you're unsure which to pick, the docs suggest asking the agent for the trade-offs of each seam before you answer.

There are no packages or API keys in the skill. You need your project's own test runner; the examples in tests.md use Jest-style test and expect.

How does it compare with the Superpowers TDD skill?

Superpowers has its own test-driven-development skill. Both are MIT licensed and both insist on a failing test before code, but they take different stances.

Pick Superpowers if you want TDD enforced on everything as part of a fixed workflow. Pick tdd if you want a lighter reference that you or another skill call at chosen boundaries.

Tips and limits

From the repo's docs, not from testing:

• The description says refactor; the skill doesn't. The refactor phase was removed in June 2026 because agents rarely did it. The phrase still triggers the skill, and the mismatch is an open issue.
• No rule for when TDD isn't worth it. Config, wiring, glue and simple CRUD have no independent truth to assert against, which leads to tautological tests. The docs say to make that call yourself or add a rule to CLAUDE.md.
• Agents sometimes write code first. The docs say no instruction gets 100% compliance; watch the run when strict order matters.
• Browser tests first are slow. The docs suggest stating in your CLAUDE.md that browser or end-to-end tests come after the behavior works.
• It sees one ticket at a time. Run against a single ticket, it can propose work that belongs to a sibling ticket. Passing the spec alongside helps, and the repo's implement-spec skill works a spec's tickets together as one task graph.

The skill runs no scripts and writes no files of its own. Under the MIT License you can copy and change it as long as 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 its files, including tests.md and mocking.md; for a repo with many skills it shows a list to pick from, so you can take codebase-design too. 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

• Grill me skill: settle the plan before you write the first test.
• Domain modeling skill: builds the GLOSSARY.md that tdd reads for test names.
• Superpowers skills: a full workflow with its own stricter TDD skill.
• Webapp testing skill: Anthropic's skill for testing local web apps with Playwright, useful for the browser checks that come after the unit loop.