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:
- Metadata (~100 tokens) — name + description, always in context
- SKILL.md body (≤5,000 words; soft warning at 500 lines) — loaded when skill triggers
- 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-leveldescription—[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.
Step 3: Write the Body
Structure the body around:
- Role statement — one paragraph defining what this agent/skill does
- Inputs — what parameters it receives
- Process — numbered steps, imperative voice
- Coordination rules — how it interacts with other agents
- Guidelines — principles and common pitfalls
Writing craft (the four rules that keep a body short and reliable):
- Anchor on a leading word. Hang the skill's behavior on one strong pretrained concept the model already knows ("adversarial", "triage", "postmortem") instead of restating a three-part definition at three different sites. If the same idea appears in the description, the intro, and a step, collapse it to the one word that carries it.
- Delete no-op sentences whole. Any line the model already obeys by default ("be helpful", "write clean code", "consider edge cases") is pure context cost. Delete the entire sentence — don't trim it to a shorter no-op.
- State the target behavior, not the bare prohibition. "Don't X" leaves the model to guess the replacement; "do Y (because Z)" names it. Keep a prohibition only when the forbidden form itself is the sharpest anchor (the Forbidden: anti-pattern naming convention).
- Price every warning you keep. A warning that names its real rework cost
("burns the agent's entire context", "rework surfaces a wave later") gets
weighed; an unpriced one reads as style advice and gets skipped under
pressure. See Cost-Tagged Anti-Patterns in
references/patterns.md.
For agent role skills, also include:
- Step 0: Read Contracts — every role skill should start by reading contracts and domain rules before any implementation
- Ownership — directories/files owned exclusively, with note that orchestrator prompt takes precedence over frontmatter defaults
- Off-limits — what this agent must never touch
- Right-sizing — guidance on adapting to project complexity
- Validation — link to
references/validation-script-pattern.mdfor how to wire a validation step into the new skill's body
Step 4: Create Reference Files
Move detailed content to references/:
- Validation checklists with specific commands
- Templates and examples
- Detailed technical guides
- Tables longer than 20 rows
Reference files from the body with guidance on when to read:
For the complete validation procedure, read `references/quick-checklist.md`
before reporting done.
Step 5: Add a Triggering Test
Every skill must carry a concrete triggering test — at least one example user phrasing that MUST activate the skill, and ideally one near-miss that must NOT. This is how you verify the description actually triggers (not just that it reads well). Record it in the skill (e.g. a short "Triggering test" note or a row in references/quick-checklist.md) so reviewers can re-run it.
Step 6: Validate the Skill
Work one focused change at a time — make a single edit, re-validate (lint + the triggering test below), then move to the next. Don't sweep many unrelated changes into one pass.
- Frontmatter has all required fields
-
nameis kebab-case. If it starts withclaude-oranthropic-, that's a documented exception (skill targets the corresponding Anthropic product) - No
<or>anywhere in frontmatter - Description is ≤200 chars (target) and "pushy"; never exceeds 1024 chars (ceiling)
- Body is ≤5,000 words (soft warning past 500 lines)
- File ownership doesn't overlap with existing agents (check v1.1 resolved conflicts)
- Directory ownership takes precedence over pattern ownership
- Reference files are linked from the body
- No duplicate content between body and references
- A triggering test is recorded (≥1 phrasing that must trigger; ideally one near-miss that must not)
Step 7: Earn the Context Cost (optional, recommended for non-trivial skills)
Optionally compare behavior with vs without the skill — a quick baseline eval on one or two representative prompts — to confirm the skill measurably improves the output and earns the tokens it adds to every context. Skip for trivial skills; do it for anything substantial.
Common Mistakes
- Vague descriptions — "Helps with backend stuff" won't trigger. Be specific.
- Body too long — Approaching 5,000 words or 500 lines? Move content to references.
- Missing ownership — Agent roles must declare owned and off-limits files.
- Overlapping ownership — Two agents can't own the same directory. Directory ownership takes precedence over pattern ownership (see
references/frontmatter-spec.md§Ownership Resolution Rules). - Ignoring resolved conflicts — Check
references/frontmatter-spec.md§Resolved Conflicts (v1.0 → v1.1) before declaring ownership ofcontracts/,.claude/handoffs/,CLAUDE.md,README.md, ortests/performance/. - Hardcoded project details — Global skills never change per project. Use profile.yaml.
Reference Files
references/frontmatter-spec.md— Complete field reference with types, rules, and examplesreferences/description-patterns.md— Templates for writing effective trigger descriptionsreferences/body-template.md— Anthropic's recommended SKILL.md body structure, plus per-skill-type deviations (agent roles, meta, orchestrator, workflow)references/patterns.md— Five architectural skill patterns (Sequential Workflow, Multi-MCP Coordination, Iterative Refinement, Context-Aware Tool Selection, Domain-Specific Intelligence)references/quick-checklist.md— Pre-ship checklist: frontmatter, description, body length, triggers, cross-referencesreferences/performance-notes.md— When and how to add a Performance Notes section to combat model lazinessreferences/validation-script-pattern.md— How to author and wire a deterministic validation script for a skill