SKILL.md description checklist
An agent decides whether to use a skill from two fields it reads at the start of every session: name and description. Everything else in SKILL.md is read only after that choice. So the description is the whole interface. This checklist comes from the Agent Skills specification and Claude Code’s skills page (both read on 15 October 2026), plus the failures that are easy to make.
The hard rules
- Name: 1 to 64 characters, lowercase letters, digits and single hyphens, not starting or ending with a hyphen, and equal to the folder the skill lives in.
- Description: required, 1 to 1,024 characters, saying both what the skill does and when to use it.
- Compatibility (optional): at most 500 characters. Metadata (optional): a map of string keys to string values, so write
version: "1.0"in quotes. - Claude Code’s listing joins
descriptionandwhen_to_use(the name is not counted) and cuts the result at 1,536 characters, so put the main use case first.
The quiet YAML failure
An unquoted value that contains a colon and a space is not valid YAML. This line looks fine and breaks strict parsers:
description: Writes a commit message: a subject line and a short body.
Quote it (description: "Writes a commit message: a subject line and a short body.") or use a folded block with >. Skill Ledger reports this with the line number.
Write the description in the words a user would type
A model matches a request against your description. “Helps with PDFs.” gives it nothing to match on; the specification itself calls it a poor example. Compare:
Helps with PDFs. Extracts text and tables from PDF files, fills PDF forms and merges several PDFs. Use when the user mentions PDFs, forms or document extraction.
The second names the actions, the objects and the situation. Add the verbs people use (“fill in”, “merge”), not only your internal term.
Watch what every skill costs
Names and descriptions of installed skills are listed at startup; the full body loads only when a skill runs. The specification suggests about 100 tokens of metadata per skill and under 5,000 tokens for the instructions. In Claude Code the listing has a budget of 1% of the context window (about 2,000 tokens, or 8,000 characters, at 200,000 tokens). Every skill name stays, but once the listing overflows, Claude Code drops descriptions, starting with the skills you use least, and a skill with no description is much harder to trigger. Forty skills with 100-token descriptions come to about 4,000 tokens, double that budget at 200,000 tokens. Raise it with skillListingBudgetFraction or trim descriptions. Claude Code’s own /doctor and /skill-doctor show what it loaded; Skill Ledger adds this up from your files before you install them, at an estimated four characters per token.
Keep two skills from competing
If “meeting-notes” and “meeting-summary” both say “transcript, decisions, action items”, a request for either fits both, and one of them may never run. Either merge them, or make each description say when it applies and when the other one does. The overlap view lists pairs that share most of their distinctive words.
Test the description like code
Write three prompts that should trigger the skill and two that should not, and keep them next to it. When you change a description, run them again. Skill Ledger keeps these prompts and re-checks them against your whole library each time anything changes. It compares words, not model behaviour, so treat a pass as “the description contains the words a user would use” and confirm important skills in your agent.