skills-library/skills/meta/skill-writer.md

name, description

name	description
skill-writer	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)

---
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

{
  "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)