The test-driven-development skill, reviewed

What it tells the agent to do

1. Write one minimal test for one behavior, using real code and avoiding mocks
2. Run it and confirm it fails because the feature is missing, not because of a typo or error
3. Write the simplest code that passes, with no extra options or features
4. Run the test, then the project's full suite; the output must be clean and every failure reported by name
5. Refactor only while green: remove duplication, improve names, extract helpers
6. Repeat for the next behavior, then tick the verification checklist before calling it done
7. If code was written before its test, delete it and start over

Lines worth reading

Straight from the file, with why each one matters.

1. line 37Write code before the test? Delete it. Start over.

   The Iron Law in one line. It is bracing as a principle, but in a real repo it tells the agent to throw away code.

2. line 192test you watched scroll past and didn't mention is a report falsified

   A sharp honesty rule: run the whole suite, even when the task named one file, and report failures you didn't cause.

3. line 14Violating the letter of the rules is violating the spirit of the rules.

   This shuts down the 'spirit not ritual' loophole before the agent can reach for it.

4. line 160// YAGNI

   The over-engineered example's whole body is a comment that it isn't needed. A small, good joke.

5. line 216read [writing-good-tests.md](writing-good-tests.md) for the rules

   It points to a reference file, but no other files could be listed in the folder, so the link may lead nowhere.

Watch out for

• Medium

  The agent is told to delete code that predates a test, with no step asking the user first. It could discard your work-in-progress.

  line 254**All of these mean: Delete code. Start over with TDD.**

• Low

  The description fires on any feature or bug fix, so the skill loads on nearly every coding task, including ones where TDD doesn't fit.

  line 3Use when implementing any feature or bugfix, before writing implementation code

• Low

  It may widen the scope of a change by adding tests to legacy code the task didn't touch.

  line 236You're improving it. Add tests for existing code.

The scorecard

• TriggerSays when to use it
  6/10

  Says when but not what; only the name reveals it's TDD. Very broad trigger.

• FocusOne clear job
  8/10

  One job, test-first development, held tightly throughout.

• LeanLight to load
  7/10

  About 330 lines; the rationalization tables argue more than they instruct.

• ConcreteSteps you can follow
  8/10

  Real commands, good/bad examples, a worked bug fix and a checklist. The commands assume npm.

• SafeSafe to run
  6/10

  No network or secrets, but it orders code deletion without asking.

How it could be better

1. Ask before deleting code

   Deleting code without permission can destroy the user's work; the rule should apply only to code the agent wrote, or come after a confirmation.

   Add

   If implementation code exists without a failing test, stop. Delete it only if you wrote it in this session; otherwise ask your human partner before deleting or setting it aside.

   Copy

2. Say what the skill does in the description

   The agent sees only the description, and it never mentions tests or the red-green cycle.

   Add

   description: Test-driven development: write a failing test, watch it fail, write minimal code to pass, run the full suite, refactor. Use when implementing a feature, fixing a bug or changing behavior, before writing implementation code.

   Copy

3. Ship or drop writing-good-tests.md

   SKILL.md tells the agent to read this file whenever it touches a test, but no sibling file could be found.

   Add

   When writing or changing any test, read [writing-good-tests.md](writing-good-tests.md) <add this file next to SKILL.md, or inline its four rules here and remove the link>.

   Copy

4. Use the repo's test command, not just npm

   The Verify steps hardcode npm test, which misleads the agent in Python, Rust or Go projects.

   Add

   Run the single test with the project's runner (<e.g. npm test path/to/file, pytest path::test_name, cargo test name>), then run the full suite with <project test command>.

   Copy