The short answer
If a Skill runs when called by name, it’s installed. Whether it also starts by itself comes down to its description, the first thing the agent sees, and one it may cut short. Test those two things one at a time, since they break for different reasons.
How each agent chooses a Skill
First, an agent scans a short index of every Skill’s name and description, and it opens a Skill’s full instructions only after choosing it. The list is built from the front matter at the top of every SKILL.md (often searched for as skills.md), and its room is limited:
| Agent | Looks at first | If the list is too long |
|---|---|---|
| Claude Code | The name and description, with when_to_use added if set; each capped at 1,536 characters | The list may use roughly 1% of the context window; descriptions of the least-used Skills are dropped first |
| Codex | The name, the description and the path to the file | The list may use roughly 2% of the context window; descriptions are trimmed first |
| Cursor | The name and description | Not stated in the docs |
With many Skills installed, a long or fuzzy description may be cut or skipped before the agent considers it. That is why the opening sentence carries the most weight.
Write a description the agent will pick
Describe the job the way a colleague would request it, and lead with the main use.
The agent compares your request with these words, so reuse the phrases people really type, such as “landing page”, “product site” or “pitch deck”. Say what it produces first, then when it applies.
Output plus trigger
- “Builds a one-page product site with a hero, a feature grid and a pricing switch. Use when someone asks for a landing page or a product site.”
Too general
- “Helps with web stuff.”
- It competes with every other site Skill and says almost nothing once trimmed.
How to check that it triggers
Go in this order. Step one rules out a broken install, so any failure after it points at the description.
- 1Run it by name. A failure here means the install is broken; go to Troubleshooting.
- 2Open a new session, so the earlier call is out of context, then describe the task normally, leaving the name out.
- 3Ask the agent which Skill it loaded, then look for one instruction that only this Skill would follow.
When a different Skill runs
Usually two descriptions overlap, or one Skill sits in two folders at once.
- Call the one you want by its name. Naming it always takes priority.
- Make overlapping descriptions narrower by input, audience or output, so every Skill has one clear job.
- Same name in two folders: Claude Code ranks Enterprise above personal, and personal above project. Codex may show both. Keep a single copy.
Common questions
Why won’t my Claude Skill trigger?
Run it by name first. If even that fails, the Skill sits outside the folders the agent reads. If only unnamed requests miss, reword the description with the phrases you type.
How does Claude choose which Skill to run?
It reads the name and description of every Skill, then loads the one that fits your request best. Typing /skill-name bypasses the matching and loads exactly the one you named.
What belongs in a Skill description?
What the Skill produces and when it applies, with the main use up front. Use everyday words like “landing page” or “pitch deck”, since the description can be cut short.
Is it SKILL.md or skills.md?
SKILL.md, one in every Skill folder. The front matter at its top holds the name and description the agent weighs when choosing.
Sources
Did this guide help?
