Guide
How to write a skill description the AI actually uses
The description decides whether the AI ever uses a skill. Before a task, only each skill's name and description are loaded, and Claude picks among possibly a hundred or more skills by matching your request against them. So write it in the third person, say what the skill does, then when to use it, in the words people actually type: "Writes the weekly client report from the account lead's notes. Use when someone asks for a weekly report, client update or status email." Avoid vague lines such as "Helps with documents". Keep it within 200 characters if the skill will be uploaded to claude.ai, the limit the Help Center gives (the specification and Claude Docs allow 1,024), and test it with plain requests in a new chat.
Short answer
- Third person: "Writes…", not "I can help…".
- What, then when: the output, then "Use when…".
- The words people type, two or three of them.
- Test it with plain requests in a new chat.
Before and after
| Before | After | What changed |
|---|---|---|
| "Helps with meetings." | "Writes meeting minutes from a transcript: decisions, actions with owners and dates, open questions. Use when someone asks for minutes, a recap or meeting notes." | The output named; three real phrasings |
| "I can help you write sales emails." | "Writes a first cold email under 90 words from account research, with two subject lines. Use when someone asks for an outreach email, a first email or a cold email." | Third person; what it needs and makes |
| "Finance stuff for the team." | "Checks supplier invoices against the purchase order and contract: amounts, dates, duplicates, VAT. Use when someone asks to check, approve or review an invoice." | One job, not a department |
A worked example: the trigger test
Illustration: a made-up business. An operations lead writes the minutes description above, then opens a new chat and types eight plain requests, five that should load the skill and three that shouldn't. Part of the test:
| Request | Should load | Did |
|---|---|---|
| "Recap of this call" | Yes | Yes |
| "Minutes from the Monday meeting" | Yes | Yes |
| "What did we agree in this transcript?" | Yes | No |
| "Write the agenda for Monday" | No | No |
| "Summarise this article" | No | No |
One miss: people also ask "what did we agree". She adds "or what was agreed in a meeting" to the "Use when" part and runs all eight again; now all five load and the three don't. The description stays under 200 characters.
Write yours
- Start with a verb in the third person and the output: "Writes…", "Checks…".
- Add what it works from: a transcript, notes, an invoice.
- Add "Use when" with two or three phrasings people really type.
- One job per skill; two jobs means two skills.
- Test five should-load and three shouldn't-load requests in a new chat, and fix until all pass.
Next step: one copy for everyone
A description tuned once should reach everyone's AI unchanged. The cheapest way to share AI prompts with a small team compares the ways to keep one copy. For the other fields, see the SKILL.md format explained.
Skills for this
- AI practiceTurn a prompt into a skillTurns a prompt that works into a skill the whole team can reuse, with a valid name, a when-to-use description, steps, an output template, an example, and checks.
- AI practiceEval set for an AI taskBuilds a 20-to-50-case eval set for an AI task: normal, edge, and adversarial cases, expected results or rubrics, pass criteria, and a re-run routine.
- Operations and adminMeeting minutes with action itemsTurns a transcript or rough notes into minutes: decisions, action items with one owner and a due date each, and open questions.
Questions
What makes a good skill description?
It says what the skill does and when to use it, in the third person, with the words people actually type. Claude's docs give the pattern: "Processes Excel files and generates reports", not "I can help you process Excel files". Name the output, then "Use when someone asks for…" with two or three real phrasings.
How long can a skill description be?
The Agent Skills specification and Claude Docs allow 1,024 characters. The Claude Help Center gives 200 for skills uploaded to claude.ai, so a description that has to work there should fit in 200.
Why doesn't Claude use my skill?
Usually the description. Only the name and description are loaded before a task, so a vague one ("Helps with documents") never matches. Rewrite it with the output and the words people type, then test it in a new chat with plain requests.
AI skill
Have your AI turn a prompt that works into a skill your team can reuse
Put this skill in AI Skill Pod and everyone on your team gets it in their Claude, Cursor or ChatGPT (Pro, Business, Enterprise): one invite link, free to start. Turn a prompt into a skill writes the description with the rest of the skill: in the third person, what it does, then "Use when" with the words your team types, inside the limits, and tested on real requests in a new chat.
14 days free · No card needed
Sources
- Claude Docs: Skill authoring best practices — include what the skill does and when to use it; always third person ("Processes Excel files and generates reports"); be specific and include key terms; Claude uses it to choose from potentially 100+ skills; avoid "Helps with documents"; up to 1,024 characters (read 2026-11-05)
- Claude Help Center: How to create custom skills — the description decides when Claude uses the skill; up to 200 characters for skills uploaded to claude.ai (read 2026-11-05)
- Agent Skills specification — description 1 to 1,024 characters; name and description loaded at startup for all skills (read 2026-11-05)
- Gemini Apps Help: About the transition from Gems to skills — best practices: define when to use it, keep it concise, provide examples (read 2026-11-05)