How to use the tdd agent skill: test-first coding with an agent

What the tdd skill makes the agent do

Without the skill, an agent may write code and tests in whatever order it likes. With the skill installed, the agent follows a strict loop: write the next test at a seam, run it, and confirm it fails for the reason you expect. Only then does it write the smallest change that makes that test pass, and then it repeats.

A seam is a place in the code where a test is allowed to enter. The skill says seams must be agreed with you before the first test is written. A seam nobody approved gets no tests.

• One test, then one implementation, then repeat.
• A test that cannot fail is not counted as a test.
• Expected values come from a spec, a worked example or documented output, not from the code under test.
• Test doubles are used only at the boundary class recorded for each seam.
• Refactoring is kept out of the red-green loop.
• A bug fix starts with a failing test that reproduces the bug.

Install the tdd skill

Download the ZIP for the skill from this page. Then install it in one of two ways. For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

The skill's package includes a single file, SKILL.md. Check that the folder ends up containing that file after unzipping.

• Personal install: ~/.claude/skills/ (unzip the ZIP here).
• Project install: .claude/skills/ inside your project (unzip the ZIP here).
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP.

Trigger the skill with natural requests

You do not need a special command. Describe the work in plain terms and mention test-first or TDD so the agent knows to apply the skill. The skill is most useful when you name the seams up front, because the agent will stop and ask for them if they are missing.

Good requests name the behaviour, the bug or the feature, and the places you want tested. For example, you might say that you want the agent to fix a bug using a failing test first, or to add a feature test-first at the seams you have already agreed.

• Add a discount rule to checkout, test-first, at the pricing and order seams we agreed.
• Reproduce this bug with a failing test before you try to fix it.
• Use TDD for the export feature. Confirm the seams with me first.

What the agent reports back

When the skill is working, the agent's output is organised around evidence. It lists the seams it used, with each seam's boundary class and a line on what that seam catches and what it lets through. It shows the failing run and the passing run for the tests. If no approved seam fits some behaviour, it reports that as a finding rather than inventing a new seam or testing through internals.

Those findings are meant to feed other skills named in the source, architecture-survey and refit.

• Seam list with boundary classes and catch/miss lines.
• Red and green test evidence.
• Seam-absence findings, where nothing testable fits.

Safety notes: scripts and network

According to the skill's listing, it requires nothing beyond itself, it does not run scripts, and it does not use the network. It consists of one instruction file, SKILL.md. The agent still runs your tests through whatever tooling your project already uses, so the normal rules for your own test commands apply.

• Requires: nothing listed.
• Runs scripts: no.
• Uses network: no.
• Files: SKILL.md only.

Tips for getting good results

Agree the seams before you start. If you have a seam list from a previous review, give it to the agent. The skill is strict about this, and a vague request will likely make the agent pause and ask.

Keep the loop small. The skill asks for tracer bullets, so a good first test covers a narrow but complete path through the behaviour, not a whole layer. Skip the skill for refactoring, which it explicitly excludes.

• Give the agent your agreed seams and boundary classes up front.
• Ask for a bug reproduction test before any fix.
• Expect a pause if no seam fits; that is intended behaviour.
• Do not use it for throwaway scripts where test discipline adds overhead.