diff --git a/skills/meta/skill-writer.md b/skills/meta/skill-writer.md new file mode 100644 index 0000000..a741acb --- /dev/null +++ b/skills/meta/skill-writer.md @@ -0,0 +1,61 @@ +--- +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)