How to Write Claude Skills That Claude Actually Uses
TL;DR
Anthropic updated its official guide to writing Claude Skills. Claude only sees each skill's name and description at first, so the description decides if the skill gets used. Keep each skill file under 500 lines, move long details into separate files, and build three tests before you write anything.
👉 https://www.skool.com/claudecodeclub
What Anthropic's Skill guide says
Anthropic publishes an official page called Skill authoring best practices. It teaches you how to write Skills that Claude can find and use. A Skill is a folder with one file called SKILL.md, which holds a name, a description and your instructions.
Why the description decides if Claude uses your skill
Claude can pick from 100 or more skills. At startup it only loads the name and description of each one. It reads the full skill file only when a skill looks relevant. So a weak description means Claude never opens your skill.
Anthropic gives three rules for a description. Say what the skill does. Say when to use it. Write it in third person, because the description goes into Claude's system prompt. The limit is 1,024 characters.
- Good: Processes Excel files and generates reports.
- Avoid: I can help you process Excel files.
- Avoid: You can use this to process Excel files.
promptRead my skill at [path to your skill folder]. Rewrite its description in third person. Say what the skill does and when to use it, in under 1,024 characters. Show me the old and new description side by side.Keep each skill file under 500 lines
Anthropic says to keep the SKILL.md body under 500 lines. A skill shares Claude's working memory with your chat, so every extra line costs space. When a skill grows past 500 lines, split it.
Move long details into separate files, like a forms file or an examples file. Claude opens those files only when the job needs them. Keep each of those files one step away from SKILL.md, and add a table of contents to any file longer than 100 lines.
promptCheck how long my skill file is at [path to your skill folder]. If SKILL.md is over 500 lines, split the long details into separate files, link each one from SKILL.md, and add a table of contents to any file over 100 lines.Build three tests before you write the skill
Anthropic says to build your tests first. Run Claude on real tasks without the skill and write down where it fails. Build three scenarios that test those gaps. Then write just enough instructions to fix what broke and pass the tests.
promptI want a skill for [the job you want Claude to do]. Do not write the skill yet. First, do this job once with no skill and list where you got it wrong or lacked context. Then write three test scenarios that check those gaps.Best practices for writing Claude Skills
- Write the description first. Claude sees it before anything else, so it needs the what and the when.
- Stay under 500 lines. Split long details into separate files that Claude opens when needed.
- Test before you write. Run Claude without the skill, then write only enough to fix what broke.
- Skip the code. A basic skill is one plain text file with a name, a description and instructions.
Which step to start with
- You already have skills: rewrite each description in third person with a what and a when.
- One of your skills is long: check its length and split it past 500 lines.
- You are about to write a new skill: run the three tests first.
👉 https://www.skool.com/claudecodeclub
Common questions
How long can a Claude Skill file be?
Anthropic's guide says to keep the SKILL.md body under 500 lines for best performance. If a skill needs more, split the extra details into separate files that Claude opens only when needed.
Why does Claude ignore my skill?
Claude only sees each skill's name and description at first, and it uses the description to choose from 100 or more skills. A vague description gives Claude no reason to pick yours. Say what the skill does and when to use it.
How do I write a good Skill description?
Write in third person, say what the skill does, and say when to use it. Anthropic's example of a good one is: Processes Excel files and generates reports. The description can be up to 1,024 characters.
Do Claude Skills need code?
No. A basic skill is one SKILL.md file with a name, a description and instructions in plain text. Code files are optional.
Keep going
Want the skills that make Claude Code worth every token?
Get 650+ plug-and-play skills, MCPs & prompts, plus 8,000+ members - $9/mo, cancel anytime.
Join the Club