writing-skills

Overview

This skill enforces a Test-Driven Development (TDD) approach to documentation and skill authoring. By defining what a skill must achieve before writing its content, we ensure functional clarity and prevent "hallucinated utility" or generic, ungrounded advice.

Iron Law

NO SKILL WITHOUT A FAILING TEST FIRST Skills written without a prior test case often drift into generic filler that doesn't solve a specific user problem. The test case grounds the skill in reality.

State Machine

digraph writing_skills_flow {
    "Start" [shape=doublecircle];
    "Step 1: Define User Problem" [shape=box];
    "Step 2: Write Failing Test Case" [shape=box];
    "Step 3: Define Acceptance Criteria" [shape=box];
    "Step 4: Author Skill Content" [shape=box];
    "Step 5: Run Test Case" [shape=box];
    "Gate: Pass Test?" [shape=diamond];
    "Done" [shape=doublecircle];

    "Start" -> "Step 1: Define User Problem";
    "Step 1: Define User Problem" -> "Step 2: Write Failing Test Case";
    "Step 2: Write Failing Test Case" -> "Step 3: Define Acceptance Criteria";
    "Step 3: Define Acceptance Criteria" -> "Step 4: Author Skill Content";
    "Step 4: Author Skill Content" -> "Step 5: Run Test Case";
    "Step 5: Run Test Case" -> "Gate: Pass Test?";
    "Gate: Pass Test?" -> "Done" [label="pass"];
    "Gate: Pass Test?" -> "Step 4: Author Skill Content" [label="fail"];
}

When to Use This Skill

• Creating a new agent skill from scratch.
• Refactoring an existing skill to add new capabilities.
• Upgrading a rough draft to a production-ready skill.
• Debugging a skill that is producing poor-quality output.

When NOT to Use This Skill

• Simple task execution that does not require a persistent skill instruction.
• General conversational responses.

Core Process

Step 1: Define User Problem

Identify the specific failure mode or knowledge gap the user is facing. What happens when the user doesn't have this skill? (Source: system design)

Step 2: Write Failing Test Case

Draft a sample prompt or scenario where a generic LLM (or the current skill) would fail. This is the "Red" phase of TDD. (Source: system design)

Step 3: Define Acceptance Criteria

List 3-5 specific, testable behaviors the skill MUST exhibit to be considered successful. (Source: system design)

Step 4: Author Skill Content

Write the skill following the appropriate rigor template (full rigor or standard rigor). Every principle must directly address the failure mode identified in Step 1. (Source: system design)

Step 5: Run Test Case

Execute the failing test case from Step 2 against the newly authored skill. If the output meets the acceptance criteria, the skill passes. (Source: system design)

Cross-Skill Invocations

REQUIRED SUB-SKILL: None RECOMMENDED SUB-SKILL: prompt-optimizer — to refine the test case and skill instructions.

Rationalization Table

Red Flags

These thoughts mean STOP — you are about to shortcut:

• "Let me just start writing and see where it goes" → You are skipping Step 1 and Step 2.
• "The test case passed even without the skill" → Your test case is too weak; it doesn't represent a true failure mode.
• "I'll just assume this works because it looks comprehensive" → You are skipping Step 5.

Diagnostic Checklist

• Is there a documented failing test case (prompt/scenario)?
• Do the acceptance criteria explicitly reference the failing test case?
• Does every principle in the skill map to a required behavior?
• Has the skill been tested against the scenario and passed?
• Is the skill free of generic, non-actionable advice?

Sources

• System design — Pattern Lineage and writing-skills definition.
• System design — Full Rigor format requirements.