← Blog · 2026-10-15

How to Write a SKILL.md Description Claude Code Actually Triggers On

Shortcut: our free SKILL.md builder turns "what it does" and "when to use it" into a correctly quoted description. To score a draft description against the words you'd actually type, use the skill description tester. Both run in your browser.

You wrote a good skill. The steps are clear, the template is solid, and when you type /weekly-client-update it works. But when you just say "can you do Acme's Friday update?" Claude writes something from scratch and ignores the skill completely.

Nine times out of ten the problem is one line: the description in the front matter.

Why the description is the whole game

Claude Code doesn't read every skill file before every reply. It keeps a short listing of each skill's name and description in context, and only loads the full SKILL.md once it decides a skill fits the request. So the description is the only part of your skill Claude sees when it makes that call. The best steps in the world don't help if the description never matches.

Three details from the Claude Code docs matter here:

• The listing is capped. Each skill's description (plus the optional when_to_use field) is cut at 1,536 characters in that listing. The open Agent Skills format used on claude.ai and the API caps description at 1,024. Put the important words first.
• Descriptions can be dropped. If you have many skills, the whole listing has a budget, and Claude Code drops descriptions from the skills you use least so the others fit. A pile of unused skills makes your useful ones harder to find. /skill-doctor (recent versions) shows what each skill costs.
• Broken YAML fails quietly. If the front matter doesn't parse, the skill still loads, but with empty metadata. /skill-name works; automatic triggering doesn't.

The formula: what it does + when to use it

A description that triggers reliably has two parts:

1. What it does, in one plain sentence, starting with a verb.
2. When to use it, written as the words you'd actually type.

The example in the official docs follows this exactly: "Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff."

Here's the same pattern for consulting work.

Before:

description: Client communication helper

That's a category, not a job. It doesn't say what comes out, and "client communication" isn't something anyone types.

After:

description: "Drafts a weekly status email for one client from this week's notes and finished tasks. Use when the user asks for a weekly update, status email, Friday summary, or 'what did we do for <client> this week'."

Now there's a clear output (a status email), a scope (one client, one week), and four phrases that match how a busy person asks for it.

Use your words, not the skill's

The most common miss is describing the skill the way you'd describe it in a product listing instead of the way you'd ask for it on a Tuesday afternoon.

A few ways to find the right words:

• Scroll your history. Look at the last few times you asked Claude for this task and copy the phrasing you used.
• Include the nouns of your business. "Invoice", "retainer", "SOW", "proposal", "discovery call". These are strong signals because they're specific.
• Add the output's file or format if it's distinctive: clients/<client>/proposals/proposal.md, "a CSV of overdue invoices".
• Cover the obvious synonyms, then stop. "Status update, weekly update, client update" is useful. Fifteen variations crowds out the ones that matter.

Narrow beats broad

A skill called client-admin that "helps with proposals, invoices, updates and onboarding" will trigger unpredictably, because it half-matches everything. Split it:

Each one is easy to match, easy to test and easy to fix. The docs give the same advice in reverse: if a skill triggers too often, make the description more specific.

Say what it doesn't do

If two skills sit close together, a short boundary helps Claude pick the right one:

description: "Drafts a polite reminder for an overdue invoice from business/invoices.md. Use when the user asks to chase, nudge or follow up on an unpaid invoice. Not for creating new invoices."

One clause is enough. Don't turn the description into a list of exceptions.

The YAML mistake that silently breaks triggering

Descriptions usually contain colons, quotes and apostrophes. In YAML, an unquoted value with : in the middle can stop the front matter from parsing:

description: Drafts proposals. Use when: the user has discovery notes

Remember what happens next: the skill still loads, so /proposal-draft works and you assume everything is fine, but Claude has no description to match against. Wrap the description in double quotes and you avoid the whole class of problem. Two more checks: the opening --- must be the very first line of the file, and field names must match exactly (description, not Description).

The SKILL.md builder quotes the description for you when it contains characters YAML cares about. Once it is saved, paste the whole file into the free SKILL.md validator to catch misspelled fields and missing "use when" wording.

Side-effect skills: don't make them trigger

Not every skill should trigger automatically. If a skill sends something, deletes something or touches money, you probably want to run it on purpose. Add this to its front matter:

disable-model-invocation: true

Claude can't load it on its own, and you run it with /skill-name when you mean it. For rules that must hold every time, such as "never send email without asking", the docs recommend a hook rather than an instruction, because hooks run on every matching tool call whether or not Claude remembers the skill. Our hooks and settings.json generator builds those guardrails.

A five-minute trigger test

After editing a description:

1. Start a fresh session so the listing is reloaded.
2. Ask "What skills are available?" and check your skill appears with the description you expect. If it's missing or blank, it's a parse or placement problem, not a wording problem.
3. Ask for the task three different ways, in your own words, without naming the skill. Note which ones trigger it.
4. Ask for something nearby that should not trigger it, like "create a new invoice" for the chase skill.
5. For any miss, add the words you used to the "when" half. For any false hit, tighten the "what" half.

Write the test prompts down in the skill's folder (a tests.md is enough) so you can rerun them after future edits.

Checklist

• Starts with a verb and names the output
• Has a "Use when…" part written in words you actually type
• Important words in the first sentence
• One job per skill
• Quoted, valid YAML; --- on line one
• disable-model-invocation: true on anything with side effects
• Tested with three real phrasings and one near-miss

Want ready-made skills?

If you'd rather start from skills that already follow this pattern:

• Free 3-skill sample: client follow-ups, meeting-to-tasks and invoice chase
• Solo Consultant Kit ($29): 8 skills, 12 CLAUDE.md practice templates, safety hooks

Or use the free SKILL.md builder and write your own.

Disclosure: I make Solo Stack Kits. The sample is free; paid kits are optional.

Not affiliated with Anthropic. "Claude" is a trademark of Anthropic.