Black Friday: Lock in your founding rate.Compare plans

Every Premium Skill for $19.9/month. Cancel anytime. See plans

Skip to content

Why your Skill isn’t triggering, and how to fix it

An agent chooses a Skill by reading its description, and it often trims that description to save room. Here’s how Claude Code, Codex and Cursor decide, and how to write a description that wins.

For
Skill users and authors
Works with
Claude Code, Codex, Cursor
Time
7 min

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:

AgentLooks at firstIf the list is too long
Claude CodeThe name and description, with when_to_use added if set; each capped at 1,536 charactersThe list may use roughly 1% of the context window; descriptions of the least-used Skills are dropped first
CodexThe name, the description and the path to the fileThe list may use roughly 2% of the context window; descriptions are trimmed first
CursorThe name and descriptionNot 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.

Gets chosen

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.”
Gets overlooked

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.

  1. 1Run it by name. A failure here means the install is broken; go to Troubleshooting.
  2. 2Open a new session, so the earlier call is out of context, then describe the task normally, leaving the name out.
  3. 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?