tdd · Skill Details

Mechanism

When It Triggers · How It Works · What It Produces

Breaks down how the skill works and what it produces, so you can quickly judge whether it fits your scenario and value.

Trigger: Automatically loaded when the user wants to build test-first or fix bugs, mentions "red-green-refactor", or wants integration tests. /implement drives /tdd internally. /ask-matt recommends standalone use of /tdd for concrete, well-scoped implementation tasks.
Mechanism: Provides a four-part reference: (1) Good test definition — verifies behaviour through public interfaces, reads like a specification; (2) Seam placement — seams must be agreed and confirmed before each test, never write at unconfirmed seams; (3) Anti-patterns — implementation-coupled (testing private methods), tautological (assertion from same source as code), horizontal slicing (all tests first then all implementation); (4) Loop rules — red before green, minimal code to pass, one vertical slice per cycle, refactoring is not part of the loop.
Output: Code validated through the TDD cycle with each behaviour covered by tests passing through public interfaces, surviving refactors. Tests serve as specifications.

Use Cases

Two Typical Use Cases

Scenario 01

Writing test-first code for a new feature

A developer building "user can cancel subscription" invokes `/tdd`. The skill first asks to agree on testing seams — what's the cancellation business logic interface. After confirmation, writes the first failing test (red), then just enough code to pass (green). Each cycle delivers one vertical slice — verify cancellation, verify refund handling, verify notification sending. Tests verify external behaviour, not internal implementation via mocks. Refactoring is deferred to the /code-review stage.

Scenario 02

Using TDD for bug fixes to prevent regressions

When fixing a bug, the developer invokes `/tdd` instead of fixing the code directly. The skill first writes a failing test that exposes the bug (at the correct seam), confirms it fails (red), then writes the fix to pass it (green). Anti-pattern checks ensure the test verifies the user's exact symptom rather than a vague "didn't crash," and expected values come from an independent source. The regression test stays in the codebase.

Skill Relationships

Which Skills I Use · Which Skills Use Me

Dependency relationships read as "the upper tier points to the lower tier." The current Skill sits in the middle tier — above are Skills that depend on it, below are Skills it depends on.

Tier 1 · These Skills Use Me

Tier 2 · Current Skill

tddStyle Guide

Tier 3 · I Use These Skills

No explicit dependency on other Skills

Full Relationship Graph

Browse this skill's relationships within its skillset. Click a node to switch the side panel; use the search box to jump to any skill.

Skill File

SKILL.md

Open in GitHub ↗

SKILL.mdLoading from GitHub…

Skill Composition

Open in GitHub ↗

SKILL.md25.0%
other75.0%

▸skills/tdd/
▸tdd
- ·SKILL.md
- ▸agents
  - ·openai.yaml
- ·mocking.md
- ·tests.md

Per the Agent Skills spec, SKILL.md is the only required file. The colored bars classify the rest into the three spec-aligned optional directories (scripts / references / assets) and an 'other' bucket. The full directory tree is below.

Related in Skillset

You May Also Need These Skills

ask-matt

A router skill for the entire skillset: when the user can't remember which skill to use or which flow fits their situation, they invoke this to get a recommendation. It describes the main "idea → ship" flow (grill-with-docs → to-spec/to-tickets → implement), plus on-ramps (triage, diagnosing-bugs, wayfinder), codebase health (improve-codebase-architecture), vocabulary layers (domain-modeling, codebase-design), and standalone skills (grill-me, prototype, research, teach). Following its map leads users to the correct workflow entry point.

Workflow

code-review

A two-axis code review skill: reviews a diff (from a fixed point to HEAD) along both Standards (coding standards + Fowler smell baseline) and Spec (faithful implementation of the originating issue/PRD). Both axes run as parallel sub-agents to avoid context pollution. The report aggregates findings without merging conclusions, ensuring "passes standards but implements the wrong thing" and "implements the right thing but breaks conventions" are both surfaced independently.

Workflow

codebase-design

A shared vocabulary skill for deep module design: provides a precise set of design terms (Module, Interface, Depth, Seam, Adapter, Leverage, Locality) guiding agents and developers to design "deep modules" — a lot of behaviour behind a small interface. Includes design principles (the deletion test, the interface is the test surface) and testability guidelines. A reference skill consumed by other skills (e.g., improve-codebase-architecture, tdd) and invoked directly by engineers.

Style Guide

diagnosing-bugs

A disciplined diagnosis loop for hard bugs and performance regressions. The core idea is to first build a tight feedback loop — no hypothesis phase without one. Six phases: build feedback loop → reproduce + minimise → generate 3-5 falsifiable hypotheses → instrument by prediction → fix + regression test → cleanup + post-mortem. If the codebase architecture can't lock down the bug, it recommends handing off to the improve-codebase-architecture skill.

Workflow