Writing Skills: TDD Process for Skill Development
Good skills are written like good tests: define the trigger scenario first, specify expected behavior, then implement.
Step 1: Define Trigger Scenarios
Before writing any skill content, write 3+ trigger scenarios:
Trigger Scenario Format:
When: [specific user utterance or context]
Context: [what state the system is in]
Expected: [what the skill should do / output]If you cannot write a concrete trigger scenario, the skill is not ready. Stop and clarify.
Step 2: Define Expected Behavior
For each trigger scenario, define:
- Output format: what does the skill output?
- Side effects: what files are modified?
- Failure conditions: when does the skill fail?
- Boundaries: what is explicitly OUT of scope?
Step 3: Implement the Skill
Frontmatter requirements:
---
name: team-shinchan:{skill-name}
description: Use when {trigger condition, max 20 words}
user-invocable: true|false
---Content rules:
- Organize into ## Step N sections
- All Task() calls must specify: subagent_type, model, prompt
- No ambiguous instructions — write the actual logic
- Every claim needs a verification step
Anti-patterns:
// implement the logic here— write actual logic- "Update as needed" — specify exactly what
- "Add error handling" — specify what errors
Step 4: Pressure Scenario Validation
Before publishing, run against these scenarios:
P1: Ambiguous Input
Input: empty args or whitespace. Expected: asks for clarification, does NOT crash.
P2: Invalid Input
Input: path traversal like ../../etc/passwd. Expected: rejects with clear error.
P3: Missing Prerequisites
Input: skill invoked when required state doesn't exist. Expected: actionable error message.
Validation Checklist
- [ ] All 3+ trigger scenarios produce expected behavior
- [ ] Empty input does NOT crash
- [ ] Missing prerequisites produce actionable errors
- [ ]
node tests/validate/skill-schema.jspasses - [ ]
node tests/validate/skill-format.jspasses - [ ] KNOWN_SKILLS in cross-refs.js updated