A skill's body can be flawless and it still won't run. Whether the skill loads at all depends on one field — the YAML description — and that field has to do two contradictory jobs in under 1,024 characters. Be specific enough to ignore irrelevant prompts. Generic enough to catch every paraphrase a user might type. Get this line wrong and the rest of the file is dead text.
This is the part of the skill that costs ten seconds to write and a month of "why didn't my skill load" to debug. Spend the time up front.
What the description actually does
A skill loads in three stages. The frontmatter sits in the system prompt all the time. The body (SKILL.md) loads when the description matches the user's prompt. Anything under references/ loads only when the body tells the agent to navigate there.
The first stage is the only one that matters at decision time. If the description doesn't match, you never get to stage two. The body is conditional content, gated entirely on a few hundred characters of metadata.
A description does three things
| What | Why it matters | Bad | Good |
|---|---|---|---|
| Says what the skill does | The agent's filter for "is this relevant" | "Helps with projects." | "Manages Linear sprint planning workflows." |
| Names the triggers | Maps user phrasing to the skill | (no triggers) | "Use when user says 'sprint', 'Linear tasks', or 'plan a sprint'." |
| Bounds the scope | Stops irrelevant prompts loading it | (no negative) | "Do NOT use for simple spreadsheet exploration (use data-viz skill instead)." |
A good description ships all three. The first two get the skill loaded; the third keeps it from loading when it shouldn't.
The structural recipe
The shape that works is mechanical: [What it does] + [When to use it] + [Key capabilities]. Three clauses, in that order, in one paragraph. Stick to it.
A working example:
---
name: customer-onboarding
description: End-to-end customer onboarding workflow for PayFlow. Handles account creation, payment setup, and subscription management. Use when user says "onboard new customer", "set up subscription", or "create PayFlow account".
---
That description does three things in three sentences. The skill triggers on the obvious phrasing, the paraphrased phrasing, and stays out of the way for everything else.
The four ways a description goes wrong
Too vague. "Helps with projects" matches everything and nothing. The agent doesn't know which projects, which workflows, or when not to use it. The skill either fires constantly or never fires at all.
No trigger phrases. "Creates sophisticated multi-page documentation systems" is descriptive but tells the agent nothing about what a user would type. If your description doesn't echo the words a real user would say, the user has to know your skill exists by name — which defeats the point.
Too technical. "Implements the Project entity model with hierarchical relationships" reads like a class docstring. Users don't ask about entity models. They ask "can you set up a project?" Mirror user language, not implementation language.
No negative bounds. A description with no "do NOT use for X" line will fire on anything tangentially related. Once that happens, users start disabling the skill — which is worse than not having one.
How to know your description is working
Two checks, neither requires running the skill in anger.
- Ask the agent to quote your description back. "When would you use the
customer-onboardingskill?" If the answer reads back the trigger phrases you wrote, you're done. If it improvises, your description was too vague. - Run twenty test prompts you'd expect to trigger it, and twenty you wouldn't. Aim for 90% load on the relevant set, 0 loads on the irrelevant set. If the second number is over zero, add negative triggers. If the first is under 18, add paraphrases.
These two numbers are the quality bar for a description. Everything else — the body, the references, the scripts — is downstream of getting them right.
When the description isn't the problem
Two cases where tuning the description won't help:
- The skill loaded but the agent ignored the instructions. That's an instruction problem, not a description problem. Move critical rules to the top of the body, use
## Importantor## Criticalheaders, repeat the key points. Description tuning won't fix a buried instruction. - The skill matches everything including totally unrelated prompts. Description is too broad. Cut it down before adding more triggers — the floor matters more than the ceiling.
Everything else in a skill is optional or fixable later. The description is what the agent sees on every turn. Spend the ten minutes upfront, or spend the hour debugging.