Guide · Agent skill
How to use the TDD agent skill (tdd): setup and examples
Updated · written with AI from the project's own documentation and checked against our catalogue data
The tdd skill is a set of instructions that an AI coding agent reads while it works on your code. Once it is installed, the agent follows a test-first loop when you build a feature or fix a bug: it writes a failing test, then only enough code to make that test pass, one small slice at a time. This guide explains what the skill changes, how to install it, how to ask for it, and what to watch for.
Test-Driven Developmentmattpocock/skills · MIT Download the skill Quick start
- 1Download the ZIP. Get the tdd skill ZIP from this page.
- 2Unzip it into the right folder. Use ~/.claude/skills/ for a personal install or .claude/skills/ in your project for a project-only install.
- 3Or upload it in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload the skill.
- 4Set up a test runner. The loop depends on running tests, so make sure your project already has one configured.
- 5Describe a test-first task. Ask for a feature or bug fix test-first, or mention red-green-refactor.
- 6Confirm the seams. When the agent proposes test boundaries, review them and agree before it writes any tests.
What does the tdd skill make the agent do?
The skill is built around the red, green loop of test-driven development. The agent writes a failing test first (red), then the minimum code to pass it (green). It works in vertical slices: one test, one implementation, then repeat, with each test responding to what the previous cycle taught.
The skill also tells the agent to check that tests verify public behavior rather than internal details, to avoid tests that just recompute the code's own logic, and to agree on the test boundaries, called seams, with you before writing any tests. If the project has a GLOSSARY.md or ADRs, the agent reads them so test names match your domain language.
- Writes a failing test before any implementation code
- Proposes seams (test boundaries) and asks you to confirm them first
- Flags tests that mock internal collaborators, test private methods or repeat the code's logic
- Keeps refactoring out of the red to green cycle; the skill points to the code-review skill for that stage
How do you install the tdd skill?
Download the ZIP from the skill's page on this directory, then unzip it. You can install it for yourself or for a single project. For a personal install, unzip it into ~/.claude/skills/. For a project install, unzip it into the project's .claude/skills/ folder.
Alternatively, in the Claude apps go to Settings, then Capabilities, then Skills, and upload the skill there.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
tdd/
SKILL.md
tests.md
mocking.md
agents/openai.yamlHow do you trigger the tdd skill?
You do not need a special command. The skill's description says it applies when you want to build features or fix bugs test-first, when you mention red-green-refactor, or when you want integration tests. Describe your task in those terms and the agent can pick up the skill.
Be explicit about the outcome you want. Phrases that name the testing approach, such as 'test-first' or 'integration tests', make it more likely the skill is used.
- Build a checkout flow test-first, starting with the first failing test.
- Fix this bug using red-green-refactor: write the failing test first.
- Add integration tests for the order API before changing the handler.
- Use TDD for the new invoice export feature.
What does a good test look like with this skill?
The skill favors tests that read like specifications. The example in the source is a test named 'user can checkout with valid cart' that adds a product to a cart, runs checkout, and asserts the result status is confirmed. It uses only the public interface and does not care how checkout works internally, so it survives refactors.
The source also shows a bad example: a test that checks checkout calls paymentService.process. It is coupled to internal structure, and the skill treats that as a warning sign.
- Good: tests observable behavior through the public API, one logical assertion per test
- Bad: mocks internal collaborators, tests private methods, asserts on call counts or order
- Expected values should come from a known-good literal, worked example or the spec, not from re-running the code's own logic
When should the agent mock, and when should it not?
The bundled mocking.md guide says to mock only at system boundaries: external APIs such as payment or email, databases (sometimes, preferring a test database), time and randomness, and the file system (sometimes). The guide advises against mocking your own classes, internal collaborators, or anything you control.
For code that talks to external services, the guide recommends dependency injection, where dependencies are passed in rather than created inside the function, and SDK-style functions for each external operation instead of one generic fetcher.
- Mock: external APIs, sometimes databases, time/randomness, sometimes the file system
- Do not mock: your own modules, internal collaborators, anything you control
Which projects and tasks suit this skill?
The skill fits developers who want features or bug fixes built test-first, and teams that want tests which survive refactoring. It is especially useful when the project uses GLOSSARY.md or ADRs, because the agent aligns test names with that vocabulary.
It is a poor fit for quick throwaway scripts or prototypes, where agreeing seams and writing tests first costs more than it saves. It also depends on running tests, so a project with no test runner set up will not get the benefit.
- Good fit: features and bug fixes built test-first, teams wanting specification-style tests
- Poor fit: throwaway scripts and prototypes, projects with no test runner
What people use it for
- Building a new feature such as a checkout flow one failing test at a time
- Fixing a bug by writing a test that reproduces it before changing the code
- Adding integration tests for an API while keeping mocks limited to external services
- Keeping test names aligned with a project's GLOSSARY.md vocabulary
Frequently asked questions
How do I install the tdd agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for a personal install or into .claude/skills/ inside your project. In the Claude apps you can instead upload it under Settings, then Capabilities, then Skills.
Does the tdd skill require anything else?
The source lists no specific requirements. In practice the loop depends on running tests, so your project needs a working test runner.
Is the tdd skill free to use?
The skill is published under the MIT licence. The source does not mention prices, so check the licence text for the terms.
Does the tdd skill run scripts or use the network?
According to this listing it runs no scripts and makes no network calls. It consists of Markdown guidance and an agents/openai.yaml file.
What is the difference between red-green-refactor and this skill?
Red-green-refactor is the general loop. The skill enforces that loop with rules on seams, test quality and mocking. It leaves refactoring out of the loop and assigns it to a review stage, such as the code-review skill.
Why does the agent ask me to confirm test seams before writing tests?
The skill requires agreeing on the seams under test before any test is written. This focuses testing effort on critical paths and complex logic, instead of covering every edge case.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use the tdd skill if you want features or bug fixes built test-first and want your tests to describe behavior rather than implementation. Skip it for throwaway scripts or prototypes, or for projects without a test runner, where the overhead outweighs the benefit.
Download the skill