Guide
How to write a Claude skill
A skill is a folder with a SKILL.md in it. Writing a good one is mostly about the description and about what you leave out. Here are seven steps, with a weak and a strong skill scored side by side.
The seven steps
- Pick one job. Write down the task in one sentence and three phrasings a user would actually type. If a one-line prompt already gets a good result, you do not need a skill.
- Write the description first. Start with 'Use when', name the real phrases, and say what the skill produces. The agent decides to load the skill from this text alone.
- Write a numbered workflow. Number the steps in the order the agent should do them. Put thresholds and decisions in tables, not prose.
- Add one worked example. Show one concrete input and the output you want. One example does more for consistency than five extra rules.
- Define the output. Add an Output section that says what the result looks like: format, length, what to leave out.
- Move detail into files. Keep SKILL.md short. Put long tables and catalogues in a reference file and say in SKILL.md when to open it.
- Test it and scan it. Start a fresh session, ask in your own words, and check the skill loads. Then run the scanner and fix what it finds.
A weak description and a strong one
Both skills below do the same job. The first says almost nothing, so the agent has little reason to load it and nothing to follow when it does. The second is the same idea written out. Both are made up for this page, and the scores come from the scanner.
description: Helps with changelogs.
One vague line, no workflow, no example, no output.
Spec 25 · Efficiency 3 · Clarity 16 · Security 25 (each out of 25)
Always loaded 10 tokens · on trigger 27 · on demand 0
eff/body-thinwarnThe body is very thin. A skill should carry knowledge the agent doesn't already have.eff/description-thinwarndescription is too short to trigger reliably. Say what it does and when to use it.eff/description-triggerwarndescription doesn't say *when* to use the skill ("Use when …"). Agents decide from this line alone.clarity/exampleswarnNo examples or code blocks. One concrete input → output example improves consistency more than extra rules.clarity/outputwarnDoesn't say what the result should look like. Add an Output section.
description: Use when the user asks for release notes or a changelog, says 'write the changelog', 'what changed since the last tag' or 'summarise these commits for users'. Turns git history into a dated, user-facing changelog grouped by Added, Changed, Fixed and Removed. Reads profile.md for product name and audience.
Trigger phrases, a numbered workflow, a worked example, a defined output and a reference file.
Spec 25 · Efficiency 25 · Clarity 25 · Security 25 (each out of 25)
Always loaded 81 tokens · on trigger 549 · on demand 112
No findings.
The middle: a good description, a thin body
A good description alone is not enough. This sample has one, plus four steps and nothing else. It scores in between because it has no example and no output section.
Spec 25 · Efficiency 15 · Clarity 16 · Security 25 (each out of 25)
Always loaded 29 tokens · on trigger 58 · on demand 0
eff/body-thinwarnThe body is very thin. A skill should carry knowledge the agent doesn't already have.clarity/exampleswarnNo examples or code blocks. One concrete input → output example improves consistency more than extra rules.clarity/outputwarnDoesn't say what the result should look like. Add an Output section.
Progressive disclosure, in one paragraph
An agent loads a skill in three stages: name and description at the start of every session, the body when the skill triggers, and reference files only when the body points to them. So the description must be short and exact, the body must be lean, and the long material goes in files. The progressive disclosure guide shows a real split, and the format reference lists every field and limit.
Test it, then scan it
Put the folder in your skills directory, open a new session and ask in your own words. If it does not load, work through why a skill is not triggering. Then paste it here. The scan runs in your browser and nothing is uploaded.
Want it done for you
Skill Author is a ProSkills skill ($12) that walks an agent through these steps and delivers a folder aimed at a 90+ scan. It has 5 rules, loads when the user creates or improves an Agent Skill, and is scored like any other skill: 100/100.
Sources
Only name and description are required in the frontmatter.
Questions
- How long should a skill be?
- Keep the SKILL.md body under 500 lines and about 5,000 tokens. Most good skills are far shorter. Anything long and reference-like belongs in a separate file that the body points to.
- What goes in the description?
- What the skill does and when to use it, in third person, with the phrases a user would type. It is the only text the agent sees before deciding to load the skill, so a vague one means the skill rarely runs.
- Do I need scripts?
- No. Prefer plain instructions. Add a script only for a deterministic, repeatable step, and explain in SKILL.md what it does and when it runs, so a reviewer is never surprised.
- How do I know the skill works?
- Open a new session, ask for the task in your own words, and watch whether the skill loads. If it does not, see the triggering guide. Then scan the folder: a score of 80 or more with no critical finding is a sensible bar.
Keep reading
- Skill ScannerScore any skill in your browser. Nothing is uploaded.
- SKILL.md format referenceEvery field, its limit, the folder layout and the errors people hit.
- SKILL.md examplesReal skills, annotated, each with its scan score.
- Skill quality leaderboardScores for every free skill, three synthetic samples, and what 90+ looks like.
- All guidesEvery guide, grouped by what you are trying to do.
Paste a SKILL.md or drop a folder. It is scored in your browser and nothing is uploaded.
Want a skill that already passes? Start with a free one.
AGENTS.md ArchitectFreeScan 100/100A short instructions file from your real repo. From the Agent Ops collection.