| name | skill-creator |
| description | How to write a skill for this project. Use when the user asks to write, add, or create a new skill. Also use when deciding how a skill should be structured, what sections it needs, or how to write its description field. Trigger on: 'write a skill', 'create a skill', 'add a skill', 'new skill', 'make a skill for X', 'how should I structure this skill'. |
Writing a Skill
A skill is a file Claude loads while performing a task. When it loads, Claude is already doing the task — so the body contains exactly what Claude needs to do it well: the reference material, workflow steps, templates, or frameworks. Write it the way a capable expert would document their own domain knowledge.
Function determines form
Before writing, answer: what does Claude need from this skill to perform the task?
Library or API skill — Claude needs to use the library correctly. Open with a one-sentence description of what it does. Then installation, a minimal runnable quick-start example, and the reference material organized by what you need to do: each usage pattern with a working code block, a decision table if there are multiple variants with different tradeoffs, and a performance or tradeoff comparison if relevant. Code examples should run as written.
Pipeline or workflow skill — Claude needs to follow a sequence of steps. For each step: what it does, how to execute it, and what it produces. Name the specific action — not "process the input" but "run the Literature Scout on idea_v{n}.md; output goes to scout_report_{n}.md." Include decision points (branching conditions) inside the workflow where they apply, not in a separate section. A checklist is useful when steps need to be tracked.
Framework skill — Claude needs to apply a set of heuristics or analytical lenses. For each framework: what it is, when it's the right tool to reach for, and how to apply it with a worked example. A selection guide at the end — which framework for which situation — reduces guesswork when multiple frameworks could apply.
Template skill — Claude needs to fill in a structured document. Include the complete template with inline annotation on each field: what it captures, how to fill it in, and what a good entry looks like. If the template is short, embed it directly. If long, put it in references/ and link to it with a pointer that names when to open it.
Anatomy
skill-name/
├── SKILL.md
└── references/ optional
└── topic.md
Use references/ for material too large to embed inline — detailed checklists, extended configuration tables, templates with many variants. When linking, say what's there and when to open it, not just the path.
Length
Include what the task requires. A library skill covering five index types needs five code blocks. A workflow with eight steps needs eight well-specified steps. The measure is whether each section earns its place: it should give Claude something it couldn't do correctly without it. Remove sections that restate what's already covered elsewhere, provide background that isn't needed to act, or describe Claude's behavior rather than supplying Claude with material.
Description field
The description is what Claude reads before deciding whether to load the skill. Name the specific situations in which it applies — what the user is trying to do, what they might say, the context. A generic topic description triggers unreliably. Include "even if they don't explicitly ask for X" when users are likely to describe the situation without naming the skill.
❌ Too vague:
description: Guides researchers through structured ideation to find research ideas.
✅ Specific:
description: Ten structured frameworks for finding research ideas — tension hunting,
abstraction laddering, cross-pollination, failure analysis, and others. Use when a
researcher is stuck on what to work on, says their ideas feel incremental, wants to
explore a new area, or is evaluating a half-formed idea — even if they don't
explicitly ask for "brainstorming."
