How to use the TDD workflow agent skill: steps, install and tips

What an agent skill is and what this one makes the agent do

An agent skill is a folder with a SKILL.md file that gives an AI agent extra instructions for a specific kind of task. This skill is triggered when you write new features, fix bugs or refactor code, and it asks the agent to apply TDD with at least 80% coverage across unit, integration and end-to-end tests.

In practice the agent first writes tests that describe the expected behaviour, runs them and checks that they fail, then writes the minimum code needed to make them pass, and finally refactors while keeping the tests green.

• Writes tests before production code
• Requires unit, integration and E2E (Playwright) tests
• Targets at least 80% coverage (unit + integration + E2E)
• If the project is a Git repository, creates checkpoint commits after each TDD stage

How to install the tdd-workflow skill

Download the ZIP file for this skill from this page and unzip it. The skill is delivered as a folder containing SKILL.md.

Put the folder in one of these locations: ~/.claude/skills/ to make it available to your user account, or a .claude/skills/ folder inside a specific project to make it available only there.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

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

How to trigger the skill with natural requests

You do not need a special command. The skill describes when it applies, so ask for the kind of work it covers in plain language. Mention the feature, bug or refactor you want, and the agent can match the request to the skill.

Good requests name the behaviour you want, for example a search function, an API endpoint or a fixed bug. Adding the test tools you use (Jest, Vitest or Playwright) helps the agent follow the workflow in your project.

• "Add a search endpoint for markets using TDD, with 80% coverage."
• "Fix the bug where the cart total ignores discounts. Write a failing test first."
• "Refactor the date helpers and keep the tests green."

What the skill needs before you start

The examples in the skill use npm commands, so the project should have Node.js and npm, and a test setup. The skill names Jest or Vitest for unit tests, Playwright for end-to-end tests and Testing Library for React component tests. A Git repository is optional and only needed for checkpoint commits.

Without a configured test setup, the skill is a poor fit, because it assumes commands such as npm test and npm run test:coverage already work.

• Node.js and npm
• Jest or Vitest for unit tests
• Playwright for E2E tests
• Testing Library for React component tests
• A Git repository (optional, for checkpoint commits)

Example: running the TDD cycle on a bug fix

Suppose you ask the agent to fix a bug. Following the skill, it first writes a test that reproduces the bug and runs npm test. The test must fail for the bug's reason, not because of a syntax error or broken configuration. Only then does the agent change production code.

Once the minimal fix makes the test pass, the agent runs the same test target again, refactors, and checks coverage with npm run test:coverage.

• Red: add a reproducer test and confirm it fails for the expected reason (commit message pattern: test: add reproducer for <feature or bug>)
• Green: apply the minimal fix and re-run the test (commit: fix: <feature or bug>)
• Refactor: clean up while tests stay green (commit: refactor: clean up after <feature or bug> implementation)
• Check coverage: npm run test:coverage, aiming for 80% or more

Safety notes: scripts and network

According to the listing, this skill runs scripts and does not use the network. Its instructions are about running your project's own test commands, so the scripts that actually execute are the ones in your project (for example npm test). Review your project's package.json scripts before letting an agent run them.

If your repository is under Git, the skill asks the agent to create commits. Check that commits land on the branch you expect and that you do not want squashing done until the workflow is finished, as the skill itself instructs.

• Runs scripts: yes (your project's test commands)
• Uses network: no
• Review package.json scripts before running agent-driven tests
• Checkpoint commits are only counted on the current active branch

Tips for getting good results

Give the agent the test tools your project uses, so it does not guess. Keep the requests small, one feature or bug at a time, because each one goes through the full red-green-refactor cycle.

Expect the skill to be slow for small changes. The skill itself is aimed at code work, and the test cycle adds time to quick edits.

• Name your test framework (Jest, Vitest or Playwright) in the request
• Use one feature or bug per request
• Check coverage output yourself rather than trusting the summary
• Skip the skill for throwaway scripts where the test cycle adds time without benefit