How to write a Claude skill description that gets it used
The description is the only part of a skill Claude reads before choosing to use it. A structure that works, the length limit, and a before and after to copy.
When you ask Claude Code for something, it decides which installed skills are relevant by reading their descriptions. Not the body, not the examples: the one field in the frontmatter. So the description is the part worth rewriting three times.
A structure that works
- What it does, in concrete nouns: the artefact, the output, the look.
- When to use it: the requests people actually type, several phrasings.
- What it is about: product or domain words someone might mention.
Before and after
description: A design helper for making nice interfaces.Nothing in that matches a real request. Compare the description on one of our skills:
description: Builds or restyles a dark web UI as a "glass instrument": near-black
aurora field, frosted glass cards with a gradient hairline ring, violet and lime,
mono numbers. Use when the user asks for a dark, premium, fintech, trading or
dashboard look, asks to make a dark page look less generic, or mentions
the traders-zone.in style.It names the output, lists the words people use, and names the reference site. It is less elegant and far more likely to be chosen.
Test it, do not admire it
Write ten prompts that should use the skill and ten near-misses that should not, run them, and change the description only using words from the prompts that failed. The method is in why a skill does not fire, and building the prompt set properly is in a trigger test set.
Questions
How long can a skill description be?
Up to 1024 characters. Most good ones use far less: two or three sentences that say what the skill does and when to use it.
Should the description say when not to use the skill?
It can, briefly, when a near-miss keeps triggering it. The main job is still to name the requests it should handle, in the words people use.
Does the skill's name affect matching?
The name identifies the skill and lets you invoke it directly, but the description does most of the work of deciding relevance. A clear name helps; a vague description is not rescued by one.