How to use the Test-Driven Development agent skill

What does the skill make the agent do?

When the skill is installed, the agent follows a strict red-green-refactor cycle whenever it implements a feature, fixes a bug, refactors, or changes behaviour. It writes one minimal test, runs it, and confirms that it fails because the feature is missing, not because of a typo or setup error. Only then does it write the least code needed to make the test pass. Finally it tidies the code while keeping the tests green.

The skill is built on one rule: no production code without a failing test first. If the agent wrote code before the test, the skill tells it to delete that code and start over. It also pushes back on shortcuts such as skipping tests or writing them after the code, and it points to a companion file, writing-good-tests.md, with rules for writing honest tests.

• Red: write one failing test and watch it fail for the right reason.
• Green: write the minimum code that makes that test pass, then run the project's test command.
• Refactor: remove duplication and improve names, without adding behaviour and with tests still green.

Install the skill from the ZIP download

Download the skill as a ZIP file from this page and unzip it. The skill is made of two files, SKILL.md and writing-good-tests.md. Put the unzipped folder in one of two places depending on how you want to use it.

For a personal setup available across your projects, place it in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder so it applies only there and can be shared with a team through the repository.

If you use the Claude apps instead of files on disk, you can upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Single project: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills

Trigger the skill with natural requests

You do not need a special command. The skill's description tells the agent to use it when implementing any feature or bugfix, before writing implementation code. So ordinary requests are enough, for example asking the agent to add a feature, fix a reported bug, or refactor a module.

To make the trigger reliable, name the behaviour you want and the test command the project uses. If you are unsure whether the agent is following the workflow, ask it to show the failing test output before the implementation.

• Add a feature: "Add a function that rejects empty email addresses, using test-first."
• Fix a bug: "Users can submit a form with an empty email. Write a reproducing test first, then fix it."
• Refactor: "Refactor the retry logic, keeping the tests green at every step."

Walk through a bug fix example

The skill includes a bug-fix example: empty email accepted. In the RED step the agent writes a test named 'rejects empty email' that submits an empty email and expects the form to reject it. It runs the test and expects a failure that shows the validation is missing.

In the GREEN step the agent adds only the validation needed to make that test pass. In the REFACTOR step it cleans up names and duplication, then re-runs the project's test suite. The skill also asks the agent to report any failing test it sees, including ones it did not cause.

Check what your project needs

The skill itself needs no API keys or accounts. It does need a working project test runner, such as npm test, pytest or cargo test, because the workflow assumes tests can be run. The skill will not set up a test framework for you.

The skill is not suited to every task. It lists throwaway prototypes, generated code and configuration files as exceptions, and says the agent should ask you first before skipping TDD for them. The skill runs no scripts and makes no network requests.

• A project test runner that the agent can call.
• Existing tests are not required, but the workflow will not create a test setup for you.
• Scripts: none. Network use: none.

Tips for getting the most from it

Keep requests small. The skill asks for one behaviour per test, so a large request is split into several red-green cycles, which is easier to review.

Read the failing output. The skill treats a test that passes immediately as a warning that it tests existing behaviour, so ask the agent to fix the test if this happens.

Use the companion guide when you review tests. writing-good-tests.md asks that each test name the production change that would make it fail, and that tests use real behaviour rather than mock behaviour.

• Keep each request to one behaviour.
• If a new test passes right away, ask the agent to fix the test.
• Review tests against writing-good-tests.md.