Use This SkillA good SKILL.md description says what the skill does and when to use it, in third person, using the words people type, with the trigger inside the first 200 characters. Agents read only the name and description until a request matches, so a vague line means a skill that rarely loads. In this directory's crawl of October 26, 2026, 744 of 2,056 skills had an explicit "Use when" clause.
What do real skill descriptions look like?
Use This Skill crawls public skill repositories and keeps every SKILL.md that has a name and a description. The crawl of October 26, 2026 found 2,056 skills in 48 repositories. A script read every description on October 28 and counted the patterns below. One repository, ComposioHQ/awesome-claude-skills, holds 864 of the skills, and 770 of those share one template ("Automate … tasks via Rube MCP (Composio)"), so the table shows the counts with and without it.
| What the description has | All 2,056 skills | The 1,192 outside ComposioHQ/awesome-claude-skills |
|---|---|---|
| An explicit trigger clause ("Use when", "Use for", "when the user", "Triggers on") | 744 (36%) | 735 (62%) |
| That clause starting within the first 200 characters | 656 | 647 |
| A phrase in quotation marks | 56 | 55 |
| A boundary ("not for", "do not use", "use … instead", "belongs to") | 20 | 19 |
| Fewer than 60 characters | 20 | 20 |
| More than 400 characters | 250 | 249 |
| Median length | 172 characters | 238 characters |
Counts from data/skills.json (crawl of October 26, 2026), counted by script on October 28, 2026. The directory stores the first 400 characters of each description, so lengths above that are counted, not measured. The pattern list is in "How we counted" below.
Three more things turned up. Two skills still carry the template placeholder "Replace with description of the skill and when Claude should use it." 23 descriptions appear word for word on 46 skills, mostly copies of the same skill in two repositories; if you install both copies, the agent sees two identical lines and has nothing to choose between them. And not one description began with "I".
How does the agent use the description?
Every major agent treats the description as the matching text. The details differ, and they decide how much room you really have.
| Agent | What the description is for | Limit or budget | Run only on request |
|---|---|---|---|
| Claude Code | "Claude uses this to decide when to apply the skill." Descriptions are always in context; the full skill loads when used. | Description plus when_to_use cut at 1,536 characters; the whole listing is capped at 1% of the model's context window, and some descriptions are dropped when it overflows |
disable-model-invocation: true |
| Codex | It "can choose a skill when your task matches the skill description." | Shortens descriptions first when many skills are installed; skills.max_context_tokens sets the list's budget, up to 10,000 tokens |
allow_implicit_invocation: false in agents/openai.yaml |
| Cursor | "Used by the agent to determine relevance." The description is required. | No limit stated | disable-model-invocation: true |
| Claude API (Agent Skills) | Should say what the skill does and when to use it; Claude uses it "to choose the right Skill from potentially 100+ available Skills" | 1,024 characters, non-empty, no XML tags | Not covered on that page |
Each row checked on the agent's official documentation on October 28, 2026; links in the sources below.
Because both Claude Code and Codex shorten or drop descriptions when many skills are installed, the start of the line carries the most weight. Codex's documentation says to "front-load the key use case and trigger words"; Claude Code's says to "put the key use case first."
What should a description say?
Two sentences are usually enough: one for what the skill does, one for when to use it.
- Start with the job, in third person. Concrete verbs and objects: "Generate descriptive commit messages by analyzing git diffs." Anthropic's guide lists "Helps with documents" and "Does stuff with files" as descriptions to avoid.
- Add the trigger in the words people type. Name the files, tools and phrases a request would contain. The tdd skill does this: "Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests." Quoting a phrase someone would type is one of the rarer patterns in the directory (56 skills).
- Name the boundary when a neighbor overlaps. If you keep two skills that touch the same work, say which one owns what. One skill in the crawl ends: "CI/test-suite optimization belongs to rea-ci-tests-audit." Only 20 descriptions do this.
- Keep the most specific words early. Of the 744 trigger clauses, 656 begin within the first 200 characters. A trigger that starts at character 900 is the first thing to go when a listing is shortened.
A description that opens with the trigger works too. obra/superpowers writes its descriptions that way: "Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes."
How long should a description be?
Long enough to name the job and the trigger, short enough to survive shortening. The hard limit is 1,024 characters on the Claude API and 1,536 for description plus when_to_use in Claude Code, but the median outside the template repository is 238 characters, and the examples in Anthropic's guide are all under 200. Every word also costs context on every turn, for every installed skill, whether or not it is used. Twenty descriptions in the crawl are under 60 characters, which rarely leaves room for a trigger.
How do I stop a skill from triggering too often?
Claude Code's documentation gives two fixes: make the description more specific, or add disable-model-invocation: true so the skill runs only when you type /skill-name. The second is the right choice for anything with side effects, such as deploying or sending a message. Codex uses allow_implicit_invocation: false for the same thing, and $skill-name still works. The skills vs subagents vs slash commands guide covers when a manual-only skill is the better design.
How do I test whether my description works?
- Ask the agent what it has. In Claude Code, ask "What skills are available?" and check that yours is listed.
- Call it by name. If
/skill-nameworks but the skill never loads by itself, the description is the likely cause. If/skill-nameworks and the description seems ignored, Claude Code's documentation says malformed front matter loads the skill with empty metadata; run with--debugto see the parse error, orclaude plugin validate .claude/skills(Claude Code v2.1.233 or later). - Measure across prompts. For a skill in a plugin, Claude Code's
claude plugin evalwith atool_used: Skillgrader counts how often it triggers. Anthropic's skill-creator skill (listed here) generates should-trigger and should-not-trigger prompts and proposes description edits. - Measure the result separately. Claude Code's documentation puts it plainly: seeing a skill trigger tells you Claude found it, not that it did what you intended.
That last point is where this site's proofs fit. A proof gives Claude the skill directly and runs the same brief three times without it and three times with it, so it shows what a skill changes once loaded, not whether its description triggers. The methodology explains the setup. Before you install a skill from anywhere, the free skill check scans its folder for risky commands; it does not grade descriptions.
A description template
---
name: release-notes
description: Write release notes from merged pull requests and the git log, grouped by feature, fix and breaking change. Use when the user asks for release notes, a changelog entry or "what shipped", or mentions tagging a release. Not for commit messages.
---
The name is a placeholder; swap in your own job, the words your team uses, and the closest skill it could be confused with. For where the file goes and how it differs from CLAUDE.md and AGENTS.md, see AGENTS.md vs CLAUDE.md vs SKILL.md and how to use skills.
How we counted
The script read the description field of all 2,056 skills in data/skills.json. A trigger clause is a match, ignoring case, for "use when", "use for", "use if", "use before", "use after", "use whenever" (with or without "this skill" or "it" in between), "when the user", "when a user", "when you", "when someone", "triggers on", "triggers when", "triggers for", "trigger phrase", "invoke when", "invoke for", "activates when" or "apply when". A boundary is "do not use", "don't use", "not for", "instead use", "use … instead" or "belongs to". The crawl skips any SKILL.md without a description, so skills with no description at all are not in these counts.