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.js passes
• node tests/validate/skill-format.js passes
• KNOWN_SKILLS in cross-refs.js updated