The short answer
If calling a Skill by name works, it’s installed. Whether it runs on its own depends on its description, which the agent reads first and may shorten. Test the two separately, because they fail for different reasons.
How each agent picks a Skill
Each agent first reads a list of Skill names and descriptions, and loads a Skill’s full instructions only after it picks one. That list comes from the front matter of each SKILL.md (the file many people search for as skills.md), and it has a size budget:
| Agent | Reads first | When space runs out |
|---|---|---|
| Claude Code | Name and description, plus when_to_use if set; up to 1,536 characters each | The list gets about 1% of the context window; the least-used descriptions drop out first |
| Codex | Name, description and file path | The list gets about 2% of the context window; descriptions get shortened first |
| Cursor | Name and description | Not documented |
With a lot of Skills installed, a long or vague description can be trimmed or dropped before the agent ever weighs it. That’s why the first sentence matters most.
Write a Skill description that gets picked
Write the description the way a teammate would ask for the work, and put the main use in the first sentence.
The agent matches your request against these words, so use the ones people actually type, like “landing page”, “launch page” or “pitch deck”. Name the output first, then say when to use it.
What it makes and when
- “Build a product launch page with a hero, feature grid, and pricing toggle. Use when asked for a landing or launch page.”
Generic
- “Helps with websites.”
- It competes with every other web Skill and says almost nothing once shortened.
How to test whether it triggers
Test in this order. The first step rules out an install problem, so anything that fails after it points to the description.
- 1Call it by name. If that fails, it’s an install problem; see Troubleshooting.
- 2Start a fresh session, so the earlier call isn’t in context, and ask in plain words without the name.
- 3Ask the agent which Skill it used, then check for one instruction only this Skill would follow.
When the wrong Skill runs
This usually means two descriptions overlap, or the same Skill is installed twice.
- Call the one you want by name. A name call always wins.
- Narrow overlapping descriptions by input, audience or output, so each Skill has a clear job.
- Same name in two places: Claude Code prefers Enterprise, then personal, then project. Codex may list both. Keep one copy.
Common questions
Why isn’t my Claude Skill triggering?
Call it by name first. If that fails, the Skill isn’t installed where the agent looks; if only plain requests fail, rewrite the description using the words you actually type.
How does Claude decide which Skill to use?
It reads every Skill’s name and description, then loads the one that best matches your request. Typing /skill-name skips that matching and runs the Skill you named.
What should a Skill description say?
What the Skill makes and when to use it, with the main use in the first sentence. Use the words people actually type, like “landing page” or “pitch deck”, because the description may get shortened.
Is the file called SKILL.md or skills.md?
It’s SKILL.md, one in each Skill folder. Its front matter holds the name and description that agents read when they choose a Skill.
Sources
Did this guide help?