Skip to content
Get packs

Guide · Agent skill

How to use the TDD Workflow agent skill (tdd-workflow)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The tdd-workflow skill is an agent skill from the ECC repository that makes an AI coding agent follow test-driven development (TDD) whenever it adds features, fixes bugs or refactors code. This guide explains what the skill changes in the agent's behaviour, how to install it, how to ask for it in plain language, and what it needs to run. By the end you will know how to set it up in your project and what to expect from it.

Test-Driven Development Workflowaffaan-m/ECC · MIT

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it so you have a tdd-workflow folder containing SKILL.md.
  2. 2Place it in the skills folder. Move the folder into ~/.claude/skills/ for personal use, or into your project's .claude/skills/ folder. Alternatively, upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
  3. 3Confirm your test setup. Make sure Node.js, your package manager and a test runner such as Jest, Vitest or Bun test are installed in the project.
  4. 4Ask for a feature or fix in plain language. Describe the feature, bug or refactor you need. The skill activates when the request matches its description.
  5. 5Let the agent detect the runner. The agent runs scripts/setup-package-manager.js --detect and checks package.json to choose the correct test command.
  6. 6Review the failing tests. Check that the agent writes tests and runs them to see them fail before any implementation is added.
  7. 7Verify coverage. Run the coverage command the agent uses and confirm it reports 80% or more.

What is an agent skill and what does tdd-workflow make the agent do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a task matches the skill's description. This skill's description says it should be used when writing new features, fixing bugs, or refactoring code, and it enforces test-driven development with 80%+ coverage across unit, integration and end-to-end tests.

In practice the agent follows a test-first routine: it writes user journeys and test cases, runs them to confirm they fail, writes the minimal code to make them pass, then refactors while keeping tests green and checks coverage.

  • Writes tests before implementation code
  • Runs the suite to confirm the new tests fail first
  • Targets a minimum of 80% coverage (unit, integration and E2E combined)
  • Covers edge cases, error scenarios and boundary conditions
  • Detects the project's test runner (npm, pnpm, yarn or Bun) before running anything

How do you install the tdd-workflow skill?

Download the ZIP file from this page and unzip it. Then place the resulting folder in one of two locations: your user skills folder at ~/.claude/skills/ so it is available in every project, or a project's .claude/skills/ folder so it applies only to that project.

You can also upload the skill in the Claude apps by going to Settings → Capabilities → Skills and uploading the ZIP there.

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

How do you trigger the skill with natural requests?

You do not need a special command. The skill activates when your request matches its description, so describe the work you want done. Asking for a feature, a bug fix or a refactor is usually enough. You can also say explicitly that you want tests written first.

The skill's own activation list includes writing new features, fixing bugs, refactoring existing code, adding API endpoints and creating new components, so requests in those areas are the best fit.

  • "Add a search endpoint for markets, test-first."
  • "Fix the bug where empty cart totals show NaN, and write a regression test first."
  • "Refactor the date helper and keep coverage at 80% or above."
  • "Create a Button component using the TDD workflow."

What does the agent do step by step?

The skill sets out a fixed sequence. Before starting, the agent resolves the commands for your project's test runner. It then writes user journeys in the form 'As a [role], I want to [action], so that [benefit]', generates test cases for each journey, runs the tests expecting failure, implements the minimal code, runs the tests again, refactors, and verifies coverage.

Test commands in the skill are placeholders such as <test>, <test-watch> and <coverage>. The agent replaces them with the command that matches your project, for example npm test, pnpm test, yarn test or bun test.

  • Step 0: detect the test runner
  • Step 1: write user journeys
  • Step 2: generate test cases
  • Step 3: run tests and confirm they fail
  • Step 4: implement the minimal code
  • Step 5: run tests again
  • Step 6: refactor with tests green
  • Step 7: verify coverage
node scripts/setup-package-manager.js --detect

Which test runner does it use?

The skill separates the package manager from the test runner. A project can install dependencies with Bun yet still run Jest or Vitest. The agent checks the package.json scripts.test entry and the test files to decide which runner applies.

If scripts.test runs jest or vitest, the agent uses your package manager to run it. If scripts.test is bun test, or test files import from bun:test, the agent uses Bun's native runner with bun test. The skill warns that bun test and bun run test are different commands and that picking the wrong one is a common failure.

  • Jest or Vitest via scripts.test: npm test, pnpm test, yarn test or bun run test
  • Bun native runner: bun test, bun test --watch, bun test --coverage
  • Playwright is used for end-to-end browser tests

What do you need before you start?

You need Node.js and a package manager (npm, pnpm, yarn or Bun), plus a project test runner such as Jest, Vitest or Bun test. End-to-end tests use Playwright. The package-manager detection step uses the scripts/setup-package-manager.js script from the ECC repository.

The skill runs scripts, so review them before use. It does not use the network.

  • Node.js and npm, pnpm, yarn or Bun
  • A test runner: Jest, Vitest or Bun test
  • Playwright for end-to-end tests
  • The ECC repository's scripts/setup-package-manager.js for package-manager detection

What are the safety notes for scripts and network use?

The skill runs scripts: the detection step executes scripts/setup-package-manager.js, and the test and coverage commands run your project's own scripts. The skill's listing states that it does not use the network. Still, the test commands you run may themselves run code from your project, so keep the usual care with code you have not reviewed.

Check the scripts folder from the ECC repository before running the skill, and run it in a version-controlled project so you can review every change the agent makes.

  • The skill executes a local Node script for detection
  • Test and coverage commands run your project's code
  • The listing says the skill does not use the network
  • Review changes in version control before accepting them

What tips help the workflow work well?

Give the agent a clear journey or bug description, because the tests are only as good as the requirements behind them. If the agent's first run passes straight away, ask it to confirm the tests actually exercised the new behaviour, since the workflow depends on tests failing first.

Keep the RED step visible: the agent should show failing output before it writes implementation code. For bug fixes, ask for a regression test first.

  • Describe the behaviour you expect, not just the code change
  • Check that new tests fail before implementation
  • For bugs, request a regression test first
  • Use the coverage command to confirm the 80% target

What people use it for

  • Adding a new API endpoint with unit and integration tests written first
  • Fixing a bug by writing a regression test that fails before the fix
  • Refactoring a helper while keeping the existing test suite green
  • Building a new UI component with tests for rendering and click behaviour
  • Adding a critical user flow covered by a Playwright end-to-end test

Frequently asked questions

How do I install the tdd-workflow skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

What do I need to run the tdd-workflow skill?

You need Node.js and a package manager (npm, pnpm, yarn or Bun), a test runner such as Jest, Vitest or Bun test, and Playwright for end-to-end tests. The detection step also uses the scripts/setup-package-manager.js script from the ECC repository.

Is the tdd-workflow skill free and what is its licence?

The skill is licensed under MIT, as stated in its SKILL.md file. The source material does not list any price, so check the listing on this page for current availability terms.

Does the tdd-workflow skill work with Python or other non-JavaScript projects?

The skill is aimed at JavaScript and TypeScript projects. Its examples and runner matrix focus on Node and Bun, so it is a poor fit for non-JavaScript codebases.

Does the tdd-workflow skill use the internet?

The listing says the skill does not use the network. It does run scripts, including scripts/setup-package-manager.js, so review those scripts before use.

Why does the agent use bun test instead of bun run test?

bun test runs Bun's built-in test runner directly, while bun run test runs the package.json test script. The skill chooses based on whether the project uses Bun's native runner or a script that calls Jest or Vitest.

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 tdd-workflow if you work on JavaScript or TypeScript projects and want AI-written code backed by tests from the start, especially for bug fixes that need a regression test first. Pick something else for quick throwaway scripts, non-JavaScript projects, or if you are not comfortable reading test runner output and coverage reports.

Download the skill