How to use the Test-Driven Development agent skill

What does the test-driven-development skill make the agent do?

The skill asks the agent to follow a red-green-refactor cycle for code changes. The agent writes one minimal failing test, confirms that it fails for the expected reason, writes the simplest code that makes it pass, and then cleans up the code while keeping the tests green.

The skill is explicit that TDD is a strong default, not a rigid rule. The agent is asked to use it where a failing test pins down behavior that could easily go wrong, such as core logic, contracts and tricky edge cases. For throwaway prototypes, one-line copy tweaks, generated code and configuration files, the skill says proportionate verification is enough.

• RED: write one test for one behavior and confirm it fails correctly
• GREEN: write the minimal code to pass that test
• REFACTOR: remove duplication and improve names, without adding behavior
• A companion file, testing-anti-patterns.md, lists testing mistakes to avoid, such as testing mock behavior instead of real code

How do you install the test-driven-development skill?

Download the ZIP file from this page. The package contains LICENSE.txt, SKILL.md and testing-anti-patterns.md. You can install it in one of two ways.

For a personal install, unzip the package into ~/.claude/skills/ so the skill is available across your projects. For a single project, unzip it into that project's .claude/skills/ folder so it applies only there.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Project only: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload

How do you trigger the skill with natural requests?

The skill's description says it applies when implementing any feature or bugfix, before writing implementation code. You do not need a special command. Describe the change in normal language and say that you want tests first, so the agent knows to follow the cycle.

Naming the behavior you want helps the agent write a useful first test. Mention your test runner if you have one, because the examples in the skill assume commands such as npm test.

• Add a retry to the payment client. Write the failing test first, then implement it.
• Fix the bug where empty email addresses pass validation. Start with a test that reproduces it.
• Refactor the date parser, keeping the existing tests green and adding a test for the timezone edge case first.
• Before changing the cart total logic, write a test that shows the current expected behavior fails for the new rule.

What does a test-first run look like?

Suppose you ask the agent to add retry behavior to an operation. The skill's own example shows a good first test: it has a clear name, tests real behavior, covers one thing, and uses the real function rather than a heavy mock. The skill's example retries an operation until it succeeds on the third attempt and checks the result and the attempt count.

The agent then runs the test and must see it fail because the feature is missing, not because of a typo. Only after that does it write the smallest implementation that passes.

• A test that passes right away is treated as testing existing behavior, so the test needs fixing
• A test that errors rather than fails must be corrected and re-run
• The skill warns against over-engineering, such as adding backoff options before a test requires them

What does the skill need and what are its limits?

The source lists no required dependencies. In practice, the skill depends on your project having a test runner. The examples use npm test, so the agent must adapt them to your toolchain. Without a test runner, the agent cannot verify that a test fails for the right reason.

The skill also grants no authority to delete code or add human review steps. If you need approvals or completion gates, set them up in your own project or workflow. The skill does not enforce them.

• Requires: nothing listed in the skill metadata, but a working test runner is needed for the workflow to work
• Runs scripts: no
• Uses network: no
• Existing or others' code is preserved; the skill says to set aside only your own change when establishing a failing baseline

What should you check before relying on it?

Read the first failing test the agent writes. Check that it names one behavior, does not simply mock the code under test, and fails for the reason you expect. The companion anti-patterns file describes the mock-heavy tests the skill is designed to avoid.

If you are working on existing code that you have already changed, the skill says to demonstrate the failing baseline in an isolated copy or by setting aside only your owned change. It also says that tests written after the code do not count as TDD. If a baseline cannot be shown, the agent should record that limit.

• Confirm the test fails for the missing behavior, not a syntax or import error
• Check that the test uses real code where practical
• Keep an eye on whether the agent skipped test-first work for a case the skill allows it to skip