Writing an Effective Skill Description That Claude Will Trigger On
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.
Summary
- Core Idea: A Skill's description is a matching signal, not documentation - Claude compares it against the current task to decide whether to load the Skill at all.
- Why It Matters: A Skill with excellent instructions and a vague description behaves the same as no Skill at all, because it never gets triggered.
- Key Concepts: description field, trigger language, false positive, false negative, "when to use" clause, specificity.
- When to Use: Reach for this whenever a Skill isn't firing when it should, is firing when it shouldn't, or you're drafting a brand-new Skill's frontmatter.
- Limitations / Trade-offs: A description that's too broad over-triggers; one that's too narrow under-triggers. There's no single "correct" wording, only a better or worse fit for the range of real tasks you expect.
- Related Topics: SKILL.md frontmatter, structuring step-by-step instructions, common Skill discovery mistakes, how Claude discovers and loads Skills.
Foundations
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.
Mechanics & Interactions
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.
Advanced Considerations & Applications
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.
Common Misconceptions
- "The Skill's name does most of the discoverability work." - The description carries nearly all of it. A precise name paired with a vague description still won't trigger reliably.
- "A longer description is always a safer description." - Length isn't the variable that matters; specificity is. A long but vague description can still under- or over-trigger.
- "I only need to state what the Skill does - Claude will figure out when to use it." - Without an explicit "when," Claude has to infer trigger conditions from the "what" alone, which is far less reliable than stating them directly.
- "If a Skill isn't triggering, the instructions need work." - A missed trigger is almost always a description problem. The instructions never get read if the description doesn't match first.
- "A broader description means the Skill will be more useful." - Broad language is more likely to cause over-triggering on unrelated tasks than to make the Skill "more available" in a good way.
FAQs
What are the two things a good Skill description needs to state?
- What the Skill actually does, in terms of its concrete output.
- When it should trigger, using language that matches how a real request would be phrased.
Why does the description matter more than the instructions?
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.
What does "under-triggering" mean?
- A Skill fails to activate on a task it was actually meant to handle, usually because the description is too narrow or too abstract to match the real phrasing of the request.
What does "over-triggering" mean?
- A Skill activates on tasks it wasn't meant to handle, usually because the description is broad enough to match unrelated requests.
Is there a reliable pattern for the "when" half of a description?
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.
How do I test whether a description is well-written?
- Collect a few real requests that should trigger the Skill and a few that shouldn't.
- Check the draft description against all of them.
- Tighten it if a shouldn't-trigger example matches; loosen or reword it if a should-trigger example is missed.
Should a description mention specific tools or file names the Skill uses internally?
- No. The description is about the task and the trigger, not implementation detail. Internal specifics belong in the instructions body, not the description.
What happens if two Skills in the same library have overlapping descriptions?
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.
Is it normal to revise a description after the Skill is already in use?
- Yes. Very few descriptions are right on the first draft, and revising one after observing a missed or false trigger is a normal, expected step, not a sign of a design failure.
Can a description be too long?
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.
Does the description need to use the exact words a user would type?
- Not exactly, but it should be close enough in meaning and phrasing that real requests recognizably match it. Overly formal or abstract language, even if technically accurate, can miss how people actually ask.
Related
- Skill Design & Packaging Basics - where the description field first shows up in a working example.
- How a Skill Comes Together: From Idea to Package - the full path this page zooms in on.
- Structuring Step-by-Step Instructions Claude Can Follow Reliably - what happens once the description succeeds.
- Common Mistakes That Make a Skill Hard for Claude to Find or Use - a broader list of trigger failures.
- How Claude Discovers and Loads Skills Automatically - the mechanism this page's advice is written for.
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.