Write a description that makes a skill trigger

How an agent picks a skill

At the start of a session an agent loads only each skill’s name and description. When your request matches one, it reads the rest of that skill’s SKILL.md. So the description carries the whole job of getting the skill chosen. The steps below it never get a say.

One more thing to know: agents mostly reach for a skill when the task needs something beyond what they do alone. A one-step request such as “read this PDF” may not trigger a PDF skill, even with a perfect description.

What to put in it

Write it as an instruction to the agent, and describe what the person wants, not how the skill works inside. Here is the description of Kinetic Title Drop, a Lookbook skill:

description: Make a 6-second 1080p kinetic-type title video (MP4) from three short lines, a chip, a footer and three colours. Use for launch openers, release announcements, social posts and reel intros when someone asks for an animated title, title drop, kinetic typography or a short type-only video.

1. 1

   Step 1: What it makes

   The format, length and file type: “a 6-second 1080p kinetic-type title video (MP4)”.

2. 2

   Step 2: What it needs

   The inputs the person supplies: “three short lines, a chip, a footer and three colours”.

3. 3

   Step 3: When to use it

   The situations and the words people use: “when someone asks for an animated title, title drop, kinetic typography…”. Add requests that don’t name the topic outright, so the skill can still match.

<What it makes, with format and length>. <What it needs from the person>. Use when someone asks for <request>, <request> or <request>.

Test it

1. 1

   Step 1: Write about twenty requests

   Eight to ten that should trigger the skill and eight to ten that should not. Vary the phrasing, and include casual ones with a typo or a file path. The best “should not” requests are near misses that share words with your skill.

2. 2

   Step 2: Run each one a few times

   Agents don’t answer the same way every time. Run each request three times and count how often the skill loaded. A request passes when the rate is above one half for “should trigger” and below it for “should not”.

3. 3

   Step 3: Fix the description, then check with fresh requests

   Change it using about 60% of your requests, and keep the other 40% back to see whether the fix works on requests it never saw. If a “should not” request triggers the skill, make the description more specific. If a “should” request misses, widen it.

In Claude Code, claude plugin validate ~/.claude/skills finds SKILL.md files whose header doesn’t parse. When the header is broken, the skill still loads with no description, so you can run it by name but the agent can’t match it. Run claude --debug to see the parse error.

If you change a Lookbook skill’s description

Every Lookbook description ends with a “Use when” or “Use for” sentence. You can edit it in your copy of SKILL.md, but running the installer again replaces the whole folder, so keep a copy of your edit. Update, roll back and remove skills shows how.