Writing an Effective Skill Description That Claude Will Trigger On
A Skill can have flawless instructions and still never get used.
//
Search across all documentation pages
A Skill can have flawless instructions and still never get used.
That happens when its description field doesn't do its job: telling Claude, in advance, what the Skill does and when it applies.
Of everything in a SKILL.md file, the description carries the most weight, because it's the one part Claude evaluates before deciding to read anything else.
This page focuses entirely on that one field: what makes it work, what makes it fail, and how to tell the difference.
A Skill's description field does one job: it lets Claude decide, without reading the rest of the file, whether this Skill is relevant to the task at hand.
That decision happens against a backdrop of every other Skill available in the same context. A vague description doesn't just risk missing its own task - it risks losing to a more precise description on an unrelated Skill, or worse, matching tasks it was never meant for.
A strong description reliably has two parts.
description: >-
Summarizes a customer support transcript into a structured ticket with
issue, steps taken, and resolution status. Use when the user pastes a
support conversation or asks to turn a conversation into a ticket.The first sentence states what the Skill does, in terms of its concrete output - "a structured ticket with issue, steps taken, and resolution status," not "helps with support."
The second sentence states when it should trigger, naming the actual signals a real task would show - a pasted transcript, a specific phrase like "turn this into a ticket."
Both halves matter. A description with only the "what" half tells Claude what the Skill produces but not when a task calls for it. A description with only the "when" half can trigger correctly but leave Claude guessing at what to actually do once inside the Skill.
Claude evaluates descriptions the way you'd evaluate a short job posting: does this task match what's being described, closely enough to be worth a closer look?
That means the words you choose matter more than they might in ordinary prose. Two failure directions show up repeatedly.
Under-triggering happens when the description is too narrow or too abstract to match the actual phrasing of a real request. A description that says "helps with support" rarely matches a request phrased as "can you turn this call into a ticket."
Over-triggering happens when the description is broad enough to match tasks it was never meant to handle. "Summarizes text" as a description will happily fire on a news article, a legal document, and a meeting transcript alike, even if the Skill's instructions were written narrowly for one of those.
Too narrow: "Formats support tickets."
Too broad: "Helps organize information from conversations."
Balanced: "Summarizes a customer support transcript into a structured
ticket. Use when the user pastes a support conversation or
asks to turn a conversation into a ticket."The balanced version anchors on a specific input shape (a support transcript), a specific output shape (a structured ticket), and specific trigger phrases a real user would actually type or paste.
A useful check while drafting: read the description as if you were a different Skill's author, competing for the same task. Would your wording clearly win against a nearby, similarly-named Skill? If two descriptions in the same library could plausibly both claim a given task, that ambiguity needs to be resolved before either Skill ships.
The "Use when..." clause deserves particular attention. It works best when it names something detectable in the actual input or request - a file type, a phrase pattern, a described situation - rather than an internal judgment call only the Skill's author would recognize.
As a Skill library grows, descriptions stop being evaluated in isolation and start competing with each other. A description that was perfectly fine as the only Skill in a folder can become a source of confusion once five related Skills sit next to it.
This is where specificity earns its cost. A slightly longer, more concrete description that clearly rules out neighboring Skills is worth the extra words.
| Approach | Strength | Weakness | Best Fit |
|---|---|---|---|
| Short, general description | Easy to write, low maintenance | Prone to both over- and under-triggering as the library grows | A solo Skill with no close neighbors |
| Two-part "what + when" description | Balances precision with brevity | Requires real examples of trigger phrasing to write well | Most production Skills |
| Long, exhaustive description with many trigger examples | Very hard to miss the intended trigger | Reads as bloated; can still fail if examples don't cover real phrasing | High-stakes Skills with a history of missed triggers |
A practical way to write the "when" half is to collect two or three real requests that should trigger the Skill, and one or two that deliberately shouldn't. Draft the description, then check it against all of them. If it lets in the shouldn't-trigger examples, tighten it. If it misses one of the should-trigger examples, loosen or reword it.
This process is iterative by nature. Very few descriptions are right on the first draft, and revising a description after watching it miss or over-fire on a real task is a normal, expected part of building a Skill - not a sign something went wrong earlier.
Descriptions also age. A Skill originally scoped to one team's workflow can, over time, get asked to handle adjacent cases its description never anticipated. Revisiting the description periodically, the same way you'd revisit any piece of documentation, keeps triggering accurate as real usage patterns shift.
Because Claude compares the description against a new task before ever reading the instructions. If the description doesn't match, the instructions are never evaluated at all.
The "Use when..." pattern works well because it explicitly names trigger conditions instead of leaving them implied. Naming a concrete signal - a phrase, a file type, a described situation - works better than an abstract category.
Claude may pick either one inconsistently, or the more specific description may consistently win, leaving the other Skill effectively unused. Overlapping descriptions should be resolved by narrowing one or both.
Length itself isn't the problem, but a description padded with detail that doesn't sharpen the "what" or the "when" adds noise without adding precision. Every sentence should earn its place.
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.
Reviewed by Chris St. John·Last updated Jul 16, 2026