Claude Skills Best Practices: 7 Rules for Skills That Work
The best Claude skills are easy for Claude to find and cheap for it to read. The core of the claude skills best practices behind that fits in 7 rules: a clear name, a description that says when to use the skill, a short main file, reference files one level deep, a contents list on long files, a test written before the instructions, and a test on each model you plan to use.
If skills are new to you, this walks through each rule in order, with the numbers behind each one and what I found when I checked my own 56 skills against them.
Key Takeaways
- Claude picks a skill from its name and description alone, out of potentially 100+ others, so a description that names the job and the moment to use it is what gets the skill picked.
- Keep the main file under 500 lines and move detail into separate files, which Claude reads only when a task needs them.
- Link every extra file straight from the main file. A file reached only through another file may be read only in part.
- Write the test before the instructions: run Claude on the task without the skill, note where it fails, and write only what closes those gaps.
- Check a skill on each model you use, whether Haiku, Sonnet or Opus. What works on Opus can need more detail on Haiku.
Short on time? Jump to the 7 rules in one table.
What Is a Claude Skill?
A Claude skill is a folder of instructions that Claude reads when a task matches it. The folder holds a main file called SKILL.md, and it can also hold reference files and scripts. Anthropic calls them Agent Skills, so you will see both names, and its authoring guide is where the rules below come from. The guide applies wherever skills run, and where something is specific to Claude Code, I say so.
If you are still getting set up, start with Claude Code basics.
In Claude Code, skills also come bundled inside plugins, so installing one is another way to get a skill.
Anthropic's skills documentation covers using them in Claude Code.
Claude has a limited amount of space for your conversation and instructions at once, called its context. It does not read the whole folder up front. It reads in layers, and that loading order is behind the rules below.
| Layer | When Claude reads it | What it costs |
|---|---|---|
| Name and description | At startup, for each skill you have | Always in context |
The main file, SKILL.md |
When the skill looks relevant (in Claude Code, also when you call it by name) | Competes with your conversation for space |
| Reference files and scripts | Only when the work needs them | Nothing until opened, and a script that runs costs only its output |
Each rule below helps Claude find the right skill, or helps it read only what it needs once it has found it.
The 7 Claude Skills Best Practices at a Glance
| Rule | What to do | The number to know |
|---|---|---|
| 1. Name it for the work | Pick one naming pattern, such as a verb ending in ing, and keep it | Up to 64 characters, lowercase letters, numbers and hyphens |
| 2. Write the description for discovery | Say what the skill does and when to use it, in third person | Up to 1,024 characters |
| 3. Keep the main file short | Move detail into separate files | Under 500 lines |
| 4. Keep references one level deep | Link every extra file directly from the main file | 1 level |
| 5. Add a contents list to long files | Put it at the top of any long reference file | Over 100 lines |
| 6. Write the test first | Run Claude without the skill, then build scenarios | At least 3 scenarios |
| 7. Test on each model | Check the skill on every model you plan to use | Haiku, Sonnet, Opus |
How to Write Claude Skills: Names and Descriptions
Claude reads these 2 fields for each skill at startup, so they are the part it uses to decide whether to use a skill.
What makes a good skill name?
A good skill name says what the skill does. Anthropic's guide suggests a verb ending in ing, such as processing-pdfs, analyzing-spreadsheets or writing-documentation. Noun phrases like pdf-processing and action names like process-pdfs are acceptable too. What matters is consistency: pick one pattern and use it across your skills, so they read as one collection.
Vague names such as helper, utils and tools tell Claude nothing, and neither do generic ones like documents, data and files. A name can run to 64 characters, using lowercase letters, numbers and hyphens.
How should a skill description be written?
Write the description in third person, and say 2 things: what the skill does and when to use it. Add the words you would actually say when you ask for it. For example: "Turns rough meeting notes into a one page summary with action items. Use when the user pastes meeting notes or asks for a recap."
Third person matters because the description is added to Claude's system prompt, and mixing viewpoints ("I can help you with...", "You can use this to...") can cause discovery problems. Anthropic's own example of a weak description is "Helps with documents", which gives Claude nothing to match against.
The stakes are real. Claude chooses from potentially 100+ available skills using the description, so a vague one gives Claude little to match a request against. The guide caps a description at 1,024 characters.
How my own descriptions measure up
I ran the guide's checkable rules against the skills folder on my own machine, 56 skills in all. Descriptions drift fastest, because each fix tends to add a sentence, so they come first.
2 of the 56 go past the 1,024 character limit, at 1,299 and 1,141 characters. 9 go past 100 words, which is the line my own warning uses. That warning is a hook, a command Claude Code runs on its own at set points, and it flags a skill when its file passes 500 lines or its description passes 100 words.
On descriptions, the hook turned out to be stricter than the guide. It flags 9 skills where the published limit flags 2. A stricter house rule is fine, and it helps to know which line is the real one when you decide what to trim.