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:
- 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-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:
- 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.
- 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.
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
1---2name: skill-writer3version: 1.6.04description: |5 Generate new SKILL.md files conforming to the ecosystem's frontmatter spec and structure conventions. Use when creating a new agent role, meta skill, workflow skill, or contract skill — anything that needs a SKILL.md scaffold. Trigger on "create a skill", "new agent", "write a SKILL.md", "scaffold a skill", "add a role to the skill ecosystem".6requires_agent_teams: false7requires_claude_code: false8min_plan: starter9owns:10 directories: []11 patterns: []12 shared_read: []13allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep"]14composes_with: ["project-profiler", "orchestrator", "skill-review", "skill-update"]15spawned_by: []16metadata:17 source: https://skillmd.com/skills/ivy00johns/skill-writer18---1920# Skill Writer2122Generate correctly structured SKILL.md files for the Claude Code skill ecosystem. Every skill follows the same frontmatter convention and directory structure.2324## When to Use2526- Creating a new agent role skill27- Creating a new workflow or meta skill28- Reviewing existing skills for spec compliance29- Adding a role to an orchestrated build3031## Skill Directory Structure3233```text34skill-name/35├── SKILL.md # Required — frontmatter + instructions36└── references/ # Optional — loaded on demand37 └── detailed-guide.md38```3940## Progressive Disclosure4142Skills use three-level loading:43441. **Metadata** (~100 tokens) — name + description, always in context452. **SKILL.md body** (≤5,000 words; soft warning at 500 lines) — loaded when skill triggers463. **References** (unlimited) — loaded on demand via explicit reads4748Keep SKILL.md bodies concise. Move detailed checklists, templates, and reference tables to `references/` with clear pointers.4950## Creating a New Skill5152### Step 1: Choose the Skill Type5354| Type | Directory | Purpose |55|------|-----------|---------|56| Agent role | `roles/{name}/` | Implementation agent for orchestrated builds |57| Meta skill | `meta/{name}/` | Tools for the skill ecosystem itself |58| Workflow | `workflows/{name}/` | Cross-cutting processes |59| Contract | `contracts/{name}/` | Integration contract management |60| Orchestrator | `orchestrator/` | Lead coordinator (singleton) |6162### Step 2: Write the Frontmatter6364Every SKILL.md starts with YAML frontmatter. See `references/frontmatter-spec.md` for the complete field reference.6566Required fields:6768- `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`).69- `version` — semver (start at 1.0.0), top-level70- `description` — `[What] + [When] + [Capabilities]` anatomy (≤200 chars target, 1024 hard ceiling)7172The 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.7374**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"`).7576### Step 3: Write the Body7778Structure the body around:79801. **Role statement** — one paragraph defining what this agent/skill does812. **Inputs** — what parameters it receives823. **Process** — numbered steps, imperative voice834. **Coordination rules** — how it interacts with other agents845. **Guidelines** — principles and common pitfalls8586**Writing craft (the four rules that keep a body short and reliable):**8788- **Anchor on a leading word.** Hang the skill's behavior on one strong89 pretrained concept the model already knows ("adversarial", "triage",90 "postmortem") instead of restating a three-part definition at three91 different sites. If the same idea appears in the description, the intro, and92 a step, collapse it to the one word that carries it.93- **Delete no-op sentences whole.** Any line the model already obeys by94 default ("be helpful", "write clean code", "consider edge cases") is pure95 context cost. Delete the entire sentence — don't trim it to a shorter no-op.96- **State the target behavior, not the bare prohibition.** "Don't X" leaves97 the model to guess the replacement; "do Y (because Z)" names it. Keep a98 prohibition only when the forbidden form itself is the sharpest anchor99 (the *Forbidden:* anti-pattern naming convention).100- **Price every warning you keep.** A warning that names its real rework cost101 ("burns the agent's entire context", "rework surfaces a wave later") gets102 weighed; an unpriced one reads as style advice and gets skipped under103 pressure. See *Cost-Tagged Anti-Patterns* in `references/patterns.md`.104- **Describe capabilities, not tool names.** Write "read the file", "run the105 command", "list the directory" — not "use the Read tool" or "use the Bash106 tool". Capability language keeps the same body working on every host (Claude107 Code, Hermes, DeepSeek, Copilot, Gemini CLI). Reserve tool names for genuinely108 host-specific instructions, and scope them ("on Claude Code, use the Task109 tool").110111For agent role skills, also include:112113- **Step 0: Read Contracts** — every role skill should start by reading contracts and domain rules before any implementation114- **Ownership** — directories/files owned exclusively, with note that orchestrator prompt takes precedence over frontmatter defaults115- **Off-limits** — what this agent must never touch116- **Right-sizing** — guidance on adapting to project complexity117- **Validation** — link to `references/validation-script-pattern.md` for how to wire a validation step into the new skill's body118119### Step 4: Create Reference Files120121Move detailed content to `references/`:122123- Validation checklists with specific commands124- Templates and examples125- Detailed technical guides126- Tables longer than 20 rows127128Reference files from the body with guidance on when to read:129130```markdown131For the complete validation procedure, read `references/quick-checklist.md`132before reporting done.133```134135### Step 5: Add a Triggering Test136137Every 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.138139### Step 6: Validate the Skill140141Work 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.142143- [ ] Frontmatter has all required fields144- [ ] `name` is kebab-case. If it starts with `claude-` or `anthropic-`, that's a documented exception (skill targets the corresponding Anthropic product)145- [ ] No `<` or `>` anywhere in frontmatter146- [ ] Description is ≤200 chars (target) and "pushy"; never exceeds 1024 chars (ceiling)147- [ ] Body is ≤5,000 words (soft warning past 500 lines)148- [ ] File ownership doesn't overlap with existing agents (check v1.1 resolved conflicts)149- [ ] Directory ownership takes precedence over pattern ownership150- [ ] Reference files are linked from the body151- [ ] No duplicate content between body and references152- [ ] A triggering test is recorded (≥1 phrasing that must trigger; ideally one near-miss that must not)153- [ ] `requires_claude_code` is `false` unless the skill genuinely needs Claude-Code machinery (subagents, Artifact, `~/.claude`)154- [ ] Body uses capability language ("read the file"), not tool names ("use the Read tool")155- [ ] No Claude-Code-only references (plugin namespaces, `~/.claude` paths, `ANTHROPIC_BASE_URL`) unless scoped as host-specific156157### Step 7: Earn the Context Cost (optional, recommended for non-trivial skills)158159Optionally 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.160161## Common Mistakes162163- **Vague descriptions** — "Helps with backend stuff" won't trigger. Be specific.164- **Body too long** — Approaching 5,000 words or 500 lines? Move content to references.165- **Missing ownership** — Agent roles must declare owned and off-limits files.166- **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).167- **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/`.168- **Hardcoded project details** — Global skills never change per project. Use profile.yaml.169- **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.170171## Reference Files172173- `references/frontmatter-spec.md` — Complete field reference with types, rules, and examples174- `references/description-patterns.md` — Templates for writing effective trigger descriptions175- `references/body-template.md` — Anthropic's recommended SKILL.md body structure, plus per-skill-type deviations (agent roles, meta, orchestrator, workflow)176- `references/patterns.md` — Five architectural skill patterns (Sequential Workflow, Multi-MCP Coordination, Iterative Refinement, Context-Aware Tool Selection, Domain-Specific Intelligence)177- `references/quick-checklist.md` — Pre-ship checklist: frontmatter, description, body length, triggers, cross-references178- `references/performance-notes.md` — When and how to add a Performance Notes section to combat model laziness179- `references/validation-script-pattern.md` — How to author and wire a deterministic validation script for a skill