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

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.

Declare portability explicitly. Set requires_claude_code: false unless the skill genuinely needs Claude-Code machinery (Agent-Teams subagents, the Artifact tool, ~/.claude config). Default to portable — a host-agnostic skill costs nothing extra, while one marked true is skipped entirely when converting for other tools. If the skill is host-specific, say which host in compatibility (e.g. "Claude Code or any host with Bash").

Step 3: Write the Body

Structure the body around:

1. Role statement — one paragraph defining what this agent/skill does
2. Inputs — what parameters it receives
3. Process — numbered steps, imperative voice
4. Coordination rules — how it interacts with other agents
5. 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.
• Describe capabilities, not tool names. Write "read the file", "run the command", "list the directory" — not "use the Read tool" or "use the Bash tool". Capability language keeps the same body working on every host (Claude Code, Hermes, DeepSeek, Copilot, Gemini CLI). Reserve tool names for genuinely host-specific instructions, and scope them ("on Claude Code, use the Task tool").

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.md for 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
• name is kebab-case. If it starts with claude- or anthropic-, 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)
• requires_claude_code is false unless the skill genuinely needs Claude-Code machinery (subagents, Artifact, ~/.claude)
• Body uses capability language ("read the file"), not tool names ("use the Read tool")
• No Claude-Code-only references (plugin namespaces, ~/.claude paths, ANTHROPIC_BASE_URL) unless scoped as host-specific

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 of contracts/, .claude/handoffs/, CLAUDE.md, README.md, or tests/performance/.
• Hardcoded project details — Global skills never change per project. Use profile.yaml.
• Claude-Code-only assumptions — Writing "use the Bash tool", hardcoding ~/.claude paths, or assuming Agent Teams / the Artifact tool exist makes the skill bail on non-Claude hosts. Write capability language, default requires_claude_code to false, and scope any genuinely host-specific step.

Reference Files

• references/frontmatter-spec.md — Complete field reference with types, rules, and examples
• references/description-patterns.md — Templates for writing effective trigger descriptions
• references/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-references
• references/performance-notes.md — When and how to add a Performance Notes section to combat model laziness
• references/validation-script-pattern.md — How to author and wire a deterministic validation script for a skill