Español

Your Best Skill Never Runs

You wrote a skill you're proud of: careful steps, real expertise, exactly the procedure you keep repeating. It never fires. You end up doing the task by hand next to a file that would have done it for you. The skill isn't the problem, and neither is the model.

Only the description is in the room

A skill has two parts that behave completely differently. The frontmatter tells the agent when to use the skill; the body holds the instructions it follows once running. Crucially, the body loads only when the skill is used — which is what makes long reference material cheap.

What sits in context permanently is a listing of skill names and descriptions, so the agent knows what's available. And the description is what decides selection: it's the field the agent uses to work out when to apply the skill. If you omit it, the first paragraph of the body is used instead.

So the description isn't documentation for a human reader. It's the router. It is the only part of your skill that participates in the decision about whether the rest of it ever executes.

Write it for the dispatcher

That reframing changes how you write it. You're not summarizing the skill; you're describing the situation in which it should fire, in the words someone would actually type when they're in that situation.

• Lead with the trigger case. The combined description text is truncated in the listing, so put the situation first and the elaboration after — anything past the cut can't help you.
• Use the words your requests use. Selection is a matching problem. Vocabulary you'd never type is vocabulary that never matches.
• Add trigger phrases explicitly. There's a dedicated frontmatter field for extra context on when to invoke a skill, including example requests.
• Be specific. The documented fix for a skill that doesn't trigger is a more specific description.

Vague descriptions don't degrade gracefully — they simply never match, and the failure is silent. You don't get a warning that a skill was nearly relevant.

The collector's trap

Here's the part most people don't know, and it bites precisely the people who invest most in skills.

The listing has a character budget, scaling at about 1% of the model's context window. When your skills overflow it, descriptions get shortened to fit — which can strip out the very keywords needed to match your request. And the order matters: descriptions are dropped starting with the skills you invoke least, so the ones you use most keep their full text.

Read that carefully, because it's a feedback loop. A rarely-used skill loses its description, which makes it harder to match, which makes it used even less. Your most niche skill — often the one you'd most benefit from being reminded of — is the first to go quiet.

You can see the current state: the Skills row in /context reports the listing's size after the budget is applied, so it reflects what the model actually receives.

Debugging a skill that won't fire

• Check it's even loaded. Malformed frontmatter YAML means the body loads with empty metadata: invoking it by name still works, but there's no description to match against. Running with the debug flag shows the parse error.
• Try rephrasing toward the description — if that makes it fire, you have a description problem, not a skill problem.
• Make the description more specific, and put the trigger case first.
• Check the listing isn't overflowing via /context, and prune skills you don't use — they're crowding out the ones you do.
• Tune it with evidence. The skill-creator tooling can generate should-trigger and should-not-trigger prompts, measure the hit rate, and propose description edits when a skill activates on the wrong requests.

The takeaway

An unfindable skill isn't installed, it's buried. The description is the router, so write it for the dispatcher and lead with the trigger. And if you collect skills, know that overflowing the listing budget silently strips descriptions from your least-used ones first — the exact skills you were relying on the agent to remember for you.