The sentence Claude reads first

Here's the lifecycle. When a session starts, Claude reads the descriptions of every available skill. Just the descriptions — not the bodies, not the supporting files, not the scripts. The body of SKILL.md is invisible until your skill is actually invoked.

From that point on, every time you type something, Claude does a quiet matching pass: does any skill's description suggest it's the right tool for what the user just asked? If yes, the skill activates and Claude reads the body. If no, nothing happens.

So the description has two jobs at the same time:

• The trigger. Does this prompt match? Does it cover the phrasings users actually use?
• The pitch. Does this skill look like the right one — clearer in scope than the others Claude has loaded?

Strong descriptions all have the same three parts, often in this order:

• What it does — one short line. "Extract transcripts from YouTube videos." No fluff.
• When to use — the words a user is likely to say. "transcript", "subtitles", "captions". And the situation: "when the user provides a YouTube URL".
• Where the boundaries are — when NOT to use it. "Supports output with or without timestamps" (an implicit boundary — this isn't a video editor). Or explicitly: "SKIP if ...".

Here's the actual youtube-transcript description from ~/.claude/skills/youtube-transcript/SKILL.md, broken into its three parts:

Three pieces, each earning its place. Drop any one and the description gets weaker.

This one rule wins more skill-fires than any other: your description is read by Claude, but it has to MATCH what humans actually type.

So write the words the user is going to type. Not the technical name for what's happening behind the scenes. "Transcript" — not "automatic speech recognition output". "Deploy" — not "static asset distribution". The right word is the one that sits naturally in a person's mouth.

Look at the claude-api skill's description. After the trigger phrases, there's a clause that starts with SKIP: — "file imports openai/other-provider SDK, filename like *-openai.py/*-generic.py, provider-neutral code, general programming/ML".

That clause is doing real work. Without it, the skill would fire any time someone touches an SDK file — including OpenAI's, Cohere's, anybody's. With it, the skill quietly steps aside when it's clearly not the right one.

Here's the right mental model: a description is a classifier. Positive examples (trigger phrases) tell Claude when to fire. Negative examples (skip-conditions) tell Claude when to stop. A classifier with only positive examples will over-fire. Give it boundaries.

Take the youtube-transcript description apart, clause by clause. Every phrase is doing something specific:

• "Extract transcripts from YouTube videos." — the what. Doesn't say HOW (no mention of the API or the script). Doesn't say WHY (no marketing copy). Just the verb and the object.
• "Use when the user asks for a transcript, subtitles, or captions of a YouTube video" — the when, with all three natural-language synonyms. "Transcript" is the technical word; "subtitles" and "captions" are what casual users will actually say. Cover all three.
• "and provides a YouTube URL (youtube.com/watch?v=, youtu.be/, or similar)" — an implicit skip-condition. No URL? No match. The URL examples teach Claude what to look for in the prompt.
• "Supports output with or without timestamps." — a parameter note. Tells Claude (and the user) what the skill can do once it activates.

Three sentences. No wasted words. Every clause is either a phrase Claude can match against, or a constraint that prevents a false match. That's the bar.

Your first description rarely lands perfectly. That's normal. The fix is observation, not cleverness: watch real user phrasings and refine.

Three moves cover almost every fix:

• Add a missing trigger phrase. A user said "captions" but your description only mentions "transcript". Add "captions" to the description. Done.
• Add a skip-condition for a false positive. Your skill fires for prompts that look related but aren't. Identify the pattern, add it to a SKIP clause.
• Tighten an over-broad clause. "Use whenever the user mentions Y" fires for everything tangentially Y-shaped. Replace with "Use when the user asks to do Y-task and provides Z".

Treat your description like a regex you tune. You don't get it right the first time; you get it right by iterating on what you actually see.

There are two ways a skill fires (Chapter 1, briefly): the user types /skill-name, or Claude auto-invokes based on the description match. The description's job changes depending on which one you're after.

• Explicit-first skill. If you mostly invoke it via the slash command, the description matters less for triggering — it doesn't have to win the matching contest. But it still serves as a one-line reminder of what the skill is for, the next time you (or another developer) look at the folder.
• Implicit-first skill. If you want Claude to auto-fire it, double down on trigger phrases. Write every user-facing synonym you can think of. Add the obvious skip-conditions.

Most well-written skills work both ways. If you can't invoke a skill in plain English without using /skill-name, the description has more work to do.

Same skill (kind of). Same job (extract transcripts). Two very different descriptions. Read both — and notice how the weak one would fire for prompts that have nothing to do with what the skill actually does.