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 an agent skill: a folder with a SKILL.md instruction file that tells a compatible AI agent how to work. This one makes the agent write a failing test before any production code when it adds a feature, fixes a bug or refactors. This guide explains what it changes, how to install it from our page, how to trigger it, and what your project needs before it is useful.
Test-Driven Development GuidejnMetaCode/superpowers-zh · MIT Download the skill Quick start
- 1Download the ZIP. Download the skill ZIP from this page.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into the project's .claude/skills/ folder for one repository.
- 3Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 4Confirm your test command works. Run the project's test runner, such as npm test, pytest or cargo test, so the agent can execute it.
- 5Make a request. Ask for a feature, bug fix or refactor in plain language.
- 6Review the red and green output. Check that the new test failed for the expected reason and that the full suite passes.
What the skill makes the agent do
The skill enforces a red-green-refactor loop. The agent writes one small test that describes the behaviour it wants, runs it, and checks that it fails for the right reason, such as missing functionality rather than a typo. It then writes the least code needed to pass, reruns the test and the project's full test suite, and only then tidies the code without changing behaviour.
The skill also sets rules for the tests themselves. The agent should name the production change that would make each test fail, assert real behaviour rather than mock behaviour, and keep test-only helpers out of production classes. Before calling work done, it must go through a checklist that includes seeing every test fail first and making sure the output is clean with no errors or warnings.
Install the skill: download, unzip or upload
Download the ZIP file from this page. For a personal install, unzip it into ~/.claude/skills/. To limit it to one repository, unzip it into that project's .claude/skills/ folder instead. The skill's files are SKILL.md and writing-good-tests.md, and they need to sit together in the skill folder.
If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Single project: .claude/skills/ inside the repository
- Claude apps: Settings → Capabilities → Skills
Prepare your project's test command
The workflow depends on running an existing test command. Make sure the agent can execute one in the project, such as npm test, pytest or cargo test, depending on the repository. The skill's examples use npm test with a specific file path, and the instructions say to run the project's whole test command when finishing work.
If the project has no tests, the agent would first need to set up a test runner. The skill does not do that for you.
npm test path/to/test.test.tsTrigger the skill with natural requests
The skill's description says it applies when you implement any feature or fix a bug, before writing implementation code. So you usually do not need to name it. Ask for the work in ordinary terms and make sure the agent has access to the project's shell.
Mention the skill by name if you want to be sure it is used, or if the agent seems to skip the test-first step. The instructions are in Chinese, but you can make requests in English.
- Add a function that rejects empty email addresses, test first.
- Fix the bug where the order total ignores discounts. Add a regression test before the fix.
- Refactor the retry helper, keeping its tests green throughout.
- Use the test-driven-development skill to add pagination to the list endpoint.
What a session looks like
In the skill's bug-fix example, the agent writes a test that expects an empty email to return an 'Email required' error, runs npm test, and confirms the failure. It then adds the minimal check, reruns the tests until they pass, and only then considers refactoring the validation.
Expect the agent to report any failing tests in the full run, including ones it did not cause. The skill says a red test that was scrolled past without mention makes the report dishonest.
Safety notes: scripts and network
This skill does not run scripts and does not use the network, according to its listing. Its effects come from the agent running your project's test command and editing code in the repository. Review changes as you would for any agent edit, and check that the test command you rely on is safe to run.
Tips for getting the best results
Keep requests small so each red-green cycle stays short. The skill's exceptions, which need your approval, are throwaway prototypes, generated code and configuration files. If you want a quick experiment, say so explicitly and expect the strict rules to slow things down.
Ask the agent to name the production change each new test should catch. The bundled writing-good-tests.md file covers this and advises against testing constant values or exact message wording.
- Use it for bug fixes to get a regression test before the fix.
- Tell the agent the exact test command if the project is unusual.
- Expect slower progress on exploratory work.
What people use it for
- Adding a validation rule to a form, with a test that fails before the check exists.
- Fixing a bug by first writing a regression test that reproduces it.
- Refactoring a helper function while keeping the test suite green at every step.
- Adding a new API behaviour with tests that show the expected interface first.
Frequently asked questions
Is the test-driven-development skill free?
The skill is listed under the MIT licence, and its SKILL.md front matter states that licence. Check the licence file in the source repository for the full terms before you redistribute it.
What do I need to use it?
You need a project test runner the agent can execute, such as npm test, pytest or cargo test, and a SKILL.md-compatible agent that can run shell commands in the project. Without an existing test setup, the workflow does not work as described.
Does the skill run scripts or use the internet?
No. Its listing says it runs no scripts and uses no network. It works by having the agent run your test command and edit code.
Can I use it if my instructions must be in English?
The SKILL.md text is in Chinese, so the rules are written in Chinese. You can still make requests in English, but if you need English-language documentation for the skill itself, this skill does not provide it.
How is this different from just asking the agent to write tests?
The skill requires a failing test to be seen before implementation, and it requires the full test suite to pass before work is called done. It also refuses to keep code written before its test, so the order is enforced rather than suggested.
When should I not use it?
Skip it for throwaway prototypes, generated code and configuration work, which the skill exempts unless you approve otherwise. Also skip it for projects with no test setup, since the workflow depends on an existing test command.
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 tests it has seen fail first, especially for bug fixes and features in a project that already has a working test command. Pick something else for quick experiments, projects without tests, or if you need documentation in English.
Download the skill