skill-writer

Skill Writer

Generate correctly structured SKILL.md files for the Claude Code skill ecosystem. Every skill follows the same frontmatter convention and directory structure.

When to Use

• Creating a new agent role skill
• Creating a new workflow or meta skill
• Reviewing existing skills for spec compliance
• Adding a role to an orchestrated build

Skill Directory Structure

skill-name/
├── SKILL.md              # Required — frontmatter + instructions
└── references/           # Optional — loaded on demand
    └── detailed-guide.md

Progressive Disclosure

Skills use three-level loading:

1. Metadata (~100 tokens) — name + description, always in context
2. SKILL.md body (≤5,000 words; soft warning at 500 lines) — loaded when skill triggers
3. References (unlimited) — loaded on demand via explicit reads

Keep SKILL.md bodies concise. Move detailed checklists, templates, and reference tables to references/ with clear pointers.

Creating a New Skill

Step 1: Choose the Skill Type

Type	Directory	Purpose
Agent role	roles/{name}/	Implementation agent for orchestrated builds
Meta skill	meta/{name}/	Tools for the skill ecosystem itself
Workflow	workflows/{name}/	Cross-cutting processes
Contract	contracts/{name}/	Integration contract management
Orchestrator	orchestrator/	Lead coordinator (singleton)

Step 2: Write the Frontmatter

Every SKILL.md starts with YAML frontmatter. See references/frontmatter-spec.md for the complete field reference.

Required fields:

• name — kebab-case, max 64 chars. claude-* / anthropic-* prefixes are reserved by Anthropic; use them only as a documented exception when the skill targets the corresponding Anthropic product (e.g., claude-design-brief).
• version — semver (start at 1.0.0), top-level
• description — [What] + [When] + [Capabilities] anatomy (≤200 chars target, 1024 hard ceiling)

The description is the primary trigger mechanism. Write it "pushy" — enumerate contexts where the skill should activate. See references/description-patterns.md for templates and the 3-slot anatomy.