Authoring a Skill the TDD Way

Introduction

Most operators author skills by describing what they want to happen. They write the happy path, add a verification gate, and ship it. Then they find the skill misses in exactly the cases that matter — the edge cases the author didn't think about when imagining success.

The /writing-skills approach inverts this. Start with what went wrong. Build the skill to handle that specific failure. Then harden it against the next failure mode.

The Three-Phase Approach

Phase 1: RED — Write the Failure Scenario

Before opening a text editor, answer this: what situation motivated you to build this skill? What were you trying to do, what did Claude do instead, and what went wrong?

The failure scenario for Knox's /retro skill: "I ran a coding session, didn't save a retro, and lost all the lessons learned. The next session started from scratch. Three weeks later, I made the same mistake again because there was no record of what went wrong."

That paragraph is the test. The skill must prevent it. If it doesn't — if you can still finish a session without a retro being filed — the skill hasn't solved the problem.

The failure scenario belongs in the skill file as a comment, or as context for the WHEN TO USE section. Future maintainers need to understand what the skill was built for.

Phase 2: GREEN — Write the Minimal Skill

With the failure scenario clear, write the minimum skill that handles it. Not the full-featured version — the version that prevents the specific failure.

For /retro, the minimal skill is:

1. Collect what was built (ask Claude for session summary)
2. Write the session report HTML
3. Call memory_remember with the session summary
4. Notify Knox via the bridge
5. Verification gate: HTML exists on disk AND memory_remember was called

Everything else — the fancy formatting, the PR summary, the diagram generation — came later. The GREEN phase adds only enough to handle the failure scenario.

Phase 3: REFACTOR — Add Rationalization Counters

Once the skill handles the motivating failure, ask: how will Claude misuse this? What adjacent situations look like this skill but aren't?

For /retro, rationalization counters look like:

• WHEN NOT TO USE: short Q&A sessions that produced no code changes
• WHEN NOT TO USE: when Knox explicitly says "no retro needed"
• Guard: if no tool calls were made in the session, skip the full retro and just call memory_remember with a brief note

The REFACTOR phase also tightens the verification gate. The GREEN phase verification gate is usually too loose — "retro filed" is weaker than "HTML exists at the correct path AND memory_remember was called AND Knox received a notification."

Walk the order yourself before reading the worked example. Write the Pass-1-RED failure scenario first — the paragraph that is the test — then the smallest SKILL.md (name, trigger-bearing description, GREEN steps, one gate) that prevents exactly that failure.

Real Example: The /learn Skill

Knox needed a skill that extracts lessons from the current session and stores them in both lessons.md and Semantic Memory Layer. The failure scenario: "I made a correction to the agent, explained why it was wrong, and the lesson was never recorded. Two months later, the same mistake happened again."

RED scenario: Agent makes a mistake. Knox corrects it. The correction is never stored. The compound learning loop breaks.

GREEN skill:

1. Identify corrections from the current session (ask Claude what it got wrong)
2. Categorize: pattern / anti-pattern / convention
3. Append to lessons.md in project root
4. Call memory_remember with each lesson
5. Verification gate: lessons.md updated, memory_remember called

REFACTOR additions:

• WHEN NOT TO USE: sessions with no corrections or no novel patterns
• Guard: skip trivial one-time fixes ("I forgot to import X") — only lessons with reuse value
• Tightened gate: at least one lesson filed in Semantic Memory Layer AND lessons.md — not just one or the other

The difference between the GREEN and REFACTOR versions is the difference between "this ran" and "this actually compounds learning."

Why This Matters for the /writing-skills Skill Itself

Knox has a skill called /writing-skills that implements this exact TDD approach. When invoked, it guides the skill author through the three phases in sequence: failure scenario first, minimal skill second, hardening third.

The meta-lesson: the /writing-skills skill was itself built with this approach. The failure scenario was "operators write happy-path skills that break on the first edge case." The GREEN version enforced the three phases. The REFACTOR version added the Pass-1-RED format requirement that parallel skill-author agents use when working on the same library.

Every skill you author with this approach produces better skills than you'd write by imagining success. The discipline compounds: after ten skills built this way, writing a good verification gate becomes automatic.

What's Next

The next lesson introduces hooks — the deterministic enforcement layer that fires at specific points in the agent loop. Hooks are what happens when skills aren't enough and you need a rule that physically cannot be overridden.