Create a skill

A skill is a folder with a SKILL.md. Its name and description are always in context; its body loads when the task matches; references/, scripts/ and templates/ load only when the body points to them.

This skill covers skills only. For subagents use create-agent; for rules, hooks and slash commands use create-rule, create-hook and create-command; to convert a rule, command, agent, conversation, PDF or docs folder, or to merge existing skills, use convert-as-skill.

Principles

1. The description is the router. The model loads a skill from its description alone. Say what it does, then Use when ... with the words a user would say.
2. Assume the model is smart. Add only what it lacks: your conventions, your commands, the traps. Cut explanations of common knowledge.
3. One job per skill. If the name needs "and", split it. If two skills overlap, merge them (convert-as-skill merge-skills).
4. Match freedom to risk. Judgment calls get principles and criteria. Fragile steps (migrations, deploys) get exact commands or a script.
5. Progressive disclosure. Aim for SKILL.md under 200 lines, never over 500. Depth goes in references/, one level deep.
6. Test by using it. An untested description is a guess.

Is a skill the right tool?

What do you want to do?

New skill

1. Gather requirements. Infer from the conversation first; ask only for what is missing:
   • the task and 2 or 3 real requests it must handle (these become the trigger words and the first tests);
   • where it lives (see Where it goes);
   • the knowledge the model would not already have;
   • an output format, if quality depends on one. If the user supplied exact wording for the skill, use it verbatim. Do not paraphrase or add headings around it.
2. Check for overlap. List the skills in the target tree. Extend or merge before creating.
3. Name it. Lowercase letters, digits and single hyphens, at most 64 characters, equal to the folder name. Prefer a verb phrase or a noun that says the job (review-diff, pdf-processing). Avoid helper, utils, tools.
4. Pick the shape. One task under about 150 lines: templates/skill.md. Three or more distinct tasks: the router in templates/skill-router.md, with SKILL.md holding principles and routing.
5. Write the description. Third person, at most 1024 characters, one quoted line. What it does, then Use when .... Front-load the keywords. Add "Not for ..." when a neighbor could be confused with it.
6. Write the body in the order the agent acts: imperative steps, each with an observable result; one term per concept; one default approach plus at most one escape hatch; a template or an input/output pair when format matters; a verification step. Patterns are in patterns.md.
7. Set invocation. disable-model-invocation: true for side effects or anything you only want on /name. user-invocable: false (Claude Code) for background knowledge. Leave the default otherwise.
8. Lint. node <create-agent>/scripts/lint.mjs <skill-dir>, where <create-agent> is the sibling create-agent skill folder. If it is not installed, walk audit.md by hand.
9. Test. Run the real requests from step 1 plus one that should not trigger it. Fix by symptom and re-run. See format.md.
10. Eval fixtures. Add evals/evals.json with skill_name, at least two scenarios (happy path and boundary), and assertions. Visual skills may use evals/cases.json instead. Point to them from SKILL.md when you change behavior. node scripts/bootstrap-skill-evals.mjs seeds missing files.
11. Catalog metadata. Add or update the skill entry in skills/catalog-metadata.json (related_skills, invokes, optional tags and capabilities). Run npm run sync:skill-metadata to merge the metadata: block into SKILL.md like product/infographic.

Pointers and the two loads

Everything you add to a skill spends one of two budgets. Know which one before you add it.

• Context load: text that sits in the agent's window every turn, whether or not it is used. A skill description and a line in AGENTS.md are context load. Keep them short.
• Reader load: the effort a person spends remembering which documents exist and when to open each. Spend it where human judgment matters. Cut it where it does not.

Also count the text loaded when the agent opens a reference. It is absent from the always-loaded description, but it still costs context on that run. Split references by task so the agent reads only the part it needs.

A pointer is a short line in always-loaded text that names material kept elsewhere and says when to open it. A skill description is a pointer. A good pointer says what the material is, then lists the distinct cases that should trigger it. Put the strongest trigger word first. If two phrases name the same case, keep one.

Material behind a pointer costs only the pointer's line until it is needed. Material with no pointer costs the reader's memory. So:

• Keep SKILL.md to the steps that every run needs. Move detail that only some cases need into a references/ file, and point to it from the step that uses it.
• Keep each fact in one place. If the environment already holds it (a script in package.json, a --help text), point to that instead of copying it.
• Remove a sentence when the model already does it by default. It costs load and changes nothing.
• End each step with a clear way to tell it is done. A vague finish ("understood") invites stopping early.

Where it goes

Never write into a tool's built-in folder (for example Cursor's skills-cursor). Check which of the paths above the current project already uses and follow it. In a catalog repo, follow that repo's maintenance instructions (CLAUDE.md or AGENTS.md) for sync and validation.

Audit

1. Run the lint step above on the skill folder or the whole tree.
2. Walk audit.md for what a linter cannot judge: specific description, principles over platitudes, actionable steps, tested triggers.
3. Report a score and findings by priority, each with a concrete fix: Broken (will not load or trigger), Weak (misroutes or wastes context), Polish.
4. Apply only the fixes the user asked for. Keep the author's structure and voice.

Do not

• Write a first-person description ("I can help you ...") or one with no trigger.
• Put the core rule only in a reference file the agent may skip.
• Chain references (SKILL.md to a file to another file), or use Windows-style paths.
• Add time-sensitive facts without a date, or restate what the model already knows.
• Leave dynamic shell injection (a backticked command prefixed with !) in a published skill without guarding it.

Related skills

• create-agent: the job is a delegate with its own context and tools.
• create-command: the job is a saved prompt you type as /name.
• create-rule: the guidance must apply on every task.
• create-hook: the job must run on an event.
• convert-as-skill: the source material already exists.
• find-skills: check whether a skill for this already exists before you write one.

Done when

• name equals the folder; the description says what and when; the linter reports no errors.
• SKILL.md is under 500 lines (ideally 200) and every linked file exists, one level deep.
• It ran on at least one real request and triggered correctly, and did not trigger on the unrelated one.
• No overlap with an existing skill, or the overlap was merged.