Guide · Agent skill
How to use the Test-Driven Development agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The test-driven-development skill is a set of instructions, written in a SKILL.md file, that tells an AI coding agent to work in a test-first way. Instead of writing code and hoping it works, the agent writes a failing test, makes it pass with minimal code, and then cleans up. This guide explains what the skill changes in the agent's behavior, how to install it, how to trigger it with plain requests, and what to watch for. By the end you will be able to add the skill to Claude and ask for changes that come with tests.
Test-Driven Developmentaddyosmani/agent-skills · MIT Download the skill Quick start
- 1Download the ZIP. Download the test-driven-development skill ZIP from this page.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project.
- 3Or upload in the Claude apps. Alternatively, upload the skill under Settings → Capabilities → Skills.
- 4Ask for a change in plain language. Describe the logic you want added, the bug to fix, or the behavior to change.
- 5Let the agent write the failing test. Expect the agent to write and run a test that fails before it writes any implementation.
- 6Check the green run and full suite. Confirm the test passes after the fix and that the full test suite still passes.
What the skill makes the agent do
The skill drives development with the red-green-refactor loop. The agent writes a test that fails (RED), writes the minimum code to make it pass (GREEN), then improves the implementation while keeping tests green (REFACTOR). It runs tests after every refactor step.
For bug reports, the skill uses what it calls the Prove-It Pattern. The agent first writes a test that reproduces the bug and confirms it fails, then implements the fix, then confirms the test passes and runs the full test suite to check for regressions.
Before writing the first test, the skill tells the agent to discover how the repository tests itself: the language and build files, checked-in wrappers, the test framework, existing test conventions, and documented commands in the README, CONTRIBUTING or CI workflows. It says not to assume a default such as npm test.
- Write a failing test before the code that makes it pass
- Reproduce a bug with a test before attempting a fix
- Use the repository's own focused-test and full-suite commands
- Run tests after every refactor step
Install the test-driven-development skill
Download the ZIP for this skill from this page. Then choose one of the two install locations below.
For a personal install that applies across your projects, unzip the download into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. The skill's files, including SKILL.md, should end up inside a test-driven-development folder within the skills directory.
In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills
How to trigger the skill with natural requests
You do not need a special command. The skill's description lists the situations where it applies, so you can ask in ordinary language. It applies when implementing logic, fixing a bug, or changing behavior, and the description notes it can apply even when the code is pasted inline and the request does not mention tests.
Be specific about the behavior you want. The more clearly you describe the expected result, the clearer the first failing test will be.
- Add logic: "Add a function that calculates shipping cost by weight and zone, test first."
- Fix a bug: "Users report that completing a task leaves completedAt empty. Fix it."
- Change behavior: "Change the sort order of listTasks to newest first."
Examples of what the agent produces
The skill's examples use TypeScript, but the workflow is the same in any language once the project's own tooling is found. In a bug case, the agent writes a test such as one that checks completedAt is a Date after completeTask runs, sees it fail, then adds the missing field to the update and sees the test pass.
The skill also covers test size. Small tests (pure logic, no I/O) should make up most of the suite. Medium tests may use a localhost database or API, and large tests cover end-to-end flows. The skill recommends keeping large tests to critical paths.
What it needs and safety notes
The skill lists no requirements. It does not run scripts and does not use the network, according to its listing. Its files consist of SKILL.md only.
The skill does not install test frameworks for you. If the project has no test setup, the agent will first need to set one up, which may be more than a quick change. Because the agent runs the project's own test commands, those commands run in your environment.
- Requires: nothing listed
- Runs scripts: no
- Uses network: no
- Files: SKILL.md
Tips for better results
Point the agent at the right code and tell it the bug or behavior in one or two sentences. If you know the repository's test command, mention it so the agent does not have to search for it.
Skip the skill for pure configuration, documentation, or static content changes, which the skill itself says do not need it. For browser-based changes, the skill points to combining TDD with runtime verification using Chrome DevTools MCP.
- Name the test command if you know it
- Describe the expected result, not just the symptom
- Expect extra setup work in projects without tests
What people use it for
- Adding a new function to a service with tests written first
- Fixing a reported bug and keeping a regression test with the fix
- Changing existing behavior in a codebase that already has a test suite
- Adding edge case handling with tests that prove the new behavior
Frequently asked questions
How do I install the test-driven-development skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.
Does the test-driven-development skill cost anything or what is its licence?
The skill is listed under the MIT licence. The listing does not mention a price.
What does the test-driven-development skill require?
The listing lists no requirements. It does not run scripts and does not use the network. The project you work on needs a test setup, or the agent will first have to set one up.
Does the skill work if my project has no tests?
The skill is built around existing tests. If the project has no test setup, the agent will first need to set up a framework, which may take more than a quick change.
Does the skill need a special command to start?
No. You ask in plain language to add logic, fix a bug, or change behavior, and the skill's description lets the agent apply it, even when code is pasted inline and tests are not mentioned.
When should I not use this skill?
Skip it for pure configuration, documentation, or static content changes, which the skill itself says do not need it.
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 this skill if you want an agent to write code backed by automated tests, or if your team wants a regression test added with every bug fix in a project that already has a test suite. Pick something else if your change is only configuration or documentation, or if your project has no test setup and you do not want the agent to build one first.
Download the skill