Creating Custom Skills
Create a directory in ~/.claude/skills/<name>/, add a SKILL.md with name, description, and instructions. Optionally add scripts, templates, or examples in the same directory. The harness picks it up on next session.
Creating a skill is like writing a job posting — title (name), one-line responsibility (description), full job description (body). Vague postings get wrong applicants; specific ones get the right hire.
Structure of a good SKILL.md: (1) frontmatter with name (must match directory), description (1-2 sentences on when to use, in third person), allowed-tools (optional). (2) Body: clear instructions, examples of correct usage, common mistakes. Use the skill-creator skill to scaffold — it knows the conventions. Test by invoking via /name and observing whether the model behavior matches expectations. Iterate on the description field if the model isn't picking it up reliably.
The model decides when to invoke a skill based on the description matched against the conversation. Vague descriptions ('helps with code') don't fire; specific ones ('use when reviewing a PR for security issues, OWASP top 10') do. Skill scope: keep skills narrow — one workflow per skill. A 'utility-skill' that does five different things is a poor skill because the model can't tell when to invoke it. Skills can include sub-skills via includes, but flat is better than deep. Anthropic ships an official skill-creator skill that benchmarks skill descriptions for trigger accuracy and runs evals.
I create skills by adding a directory under ~/.claude/skills/ with a SKILL.md file. The frontmatter has name, description, and optionally allowed-tools. The description is the most important field — it's what the model uses to decide when to invoke the skill, so I write it specifically: 'use when X' rather than 'helps with Y.' I scope skills narrowly — one workflow per skill — and use the official skill-creator skill to scaffold and benchmark trigger accuracy. Iteration on the description is usually where most of the quality comes from.
Skills with overlapping descriptions trip each other up — the model picks one inconsistently. If two skills could fire for the same trigger, merge them or differentiate descriptions sharply.