The description is the most important line in a skill. It is the short piece of metadata an agent sees before the full instructions load, so it has to route the skill without relying on the body. A good description answers two questions: what does this skill do, and when should it be used?
A practical formula
Use this shape for most descriptions:
[Action verb] [artifact or workflow] for [domain or system], including [distinctive checks or resources]. Use when [user wording, trigger situation, or timing]. Not for [nearby task that should not activate this skill].The last sentence is optional for narrow skills, but valuable for broad names. A "release" skill, "review" skill, or "writing" skill needs boundaries more than a narrowly named "salesforce-invoice-export" skill.
Good and weak examples
| Weak | Better | Why it triggers better |
|---|---|---|
| Helps with PDFs. | Extracts PDF text and tables, fills PDF forms, and merges multiple PDFs. Use when working with PDFs, forms, document extraction, or PDF assembly. | It names actions, artifacts, and user terms. |
| Website stuff. | Reviews static website release readiness, including build output, sitemap, robots.txt, source citations, Cloudflare Pages deployment, and final report requirements. Use before publishing or auditing a static site. | It names the release gate and concrete checks. |
| Do code review. | Reviews pull requests in this repository for regressions, API contract drift, missing tests, generated-file churn, and unresolved review threads. Use when asked to review or merge-gate a PR. | It explains the local review surface and expected task phrasing. |
What to include
- Action verbs: review, generate, extract, validate, deploy, analyze, scaffold, debug.
- Artifacts: files, reports, PRs, PDFs, MCP servers, dashboards, transcripts, schemas.
- Trigger phrases: "Use when...", "Use before...", "when the user asks...", "when working with...".
- Domain nouns: product names, protocols, repositories, systems, templates, file types.
- Boundaries: "Not for...", "Only when...", or "Use instead..." for adjacent workflows.
What to avoid
Avoid descriptions that only describe a domain, such as "marketing skill" or "database helper." Avoid generic adjectives such as "helpful," "general," or "various." Avoid putting the whole workflow into the description; that belongs in the body after the skill activates.
Also avoid stale facts. If a skill depends on current rules, prices, model names, or deployment behavior, write the skill so the agent checks the live source instead of trusting an old description.
Test the description
- Write five realistic user prompts that should activate the skill.
- Write three nearby prompts that should not activate it.
- Run the prompts in the target agent client.
- If activation is wrong, revise the description before changing the body.
- If activation is right but execution is weak, revise the body, references, or scripts.
For a fast check, paste the description into the Skill Description Linter. To turn a strong description into a full file, use the Skill Scaffold Generator. For the broader architecture decision, use the Skill vs MCP Decider.