---
name: skill-writer
description: Use when creating new Claude skills for the platform. Applies TDD principles to skill development - test behavior without skill first, write minimal skill to fix identified gaps, iterate until bulletproof against rationalization.
---

# Skill: Write Skills

## Overview
Creating effective Claude skills requires Test-Driven Development applied to process documentation. Skills are reusable reference guides - not narratives about solving problems once.

## The Iron Law
**No skill exists without a failing test first.** Follow RED-GREEN-REFACTOR:
- **RED**: Run scenarios with subagents WITHOUT the skill to establish baseline
- **GREEN**: Write minimal skill addressing gaps, verify compliance with skill present
- **REFACTOR**: Identify loopholes and add explicit counters until bulletproof

## YAML Frontmatter (Required)
```yaml
---
name: my-skill-name     # Letters, numbers, hyphens only
description: Use when [trigger conditions]. [What it does]. [Key differentiator].
---
```

## Required Sections
1. **Overview** - What this skill does (2-3 sentences)
2. **When to Use** - Specific triggers and symptoms
3. **Core Pattern** - The main workflow/checklist
4. **Quick Reference** - Condensed version for recall
5. **Implementation** - Step-by-step instructions
6. **Common Mistakes** - Anti-patterns to avoid

## Description Field (Critical for Discovery)
The description drives Claude Search Optimization. Answer: "Should I load this skill now?"

Bad: "For async testing"
Good: "Use when tests have race conditions, timing dependencies, or inconsistent pass/fail behavior - replaces arbitrary timeouts with condition polling"

## Output Format
```json
{
  "status": "success",
  "skill": {
    "name": "skill-name",
    "path": "skills/category/skill-name.md",
    "description": "...",
    "token_budget": { "input": 500, "output": 800 }
  },
  "testing": {
    "baseline_failures": ["rationalization 1", "..."],
    "addressed": true
  }
}
```

## Token Budget
- Max input: 2000 tokens
- Max output: 1500 tokens

## Model
- Recommended: sonnet (creative reasoning for skill design)