Chapter 9 of 14 · Create · 5 min read
Writing skill descriptions that trigger reliably
Of everything in a skill, one or two sentences matter most: the description. At the start of every session the agent sees only each skill’s name and description, and from that alone decides which skill, if any, fits your request. A brilliant set of instructions behind a vague description will sit unused. A sharp description gets the skill loaded at exactly the right moment and, just as importantly, not at the wrong ones. This chapter shows how to write one.
What the agent is doing
When you make a request, the agent compares it with the list of skill descriptions it holds in context. It isn’t doing keyword search, but it is reading closely: it’s looking for a description that clearly says “this is the kind of task I’m for”. If nothing matches clearly, it carries on without a skill. If several sort of match, it may pick the wrong one. Your job is to make the match obvious.
A formula that works
Most reliable descriptions follow the same two-part shape: what the skill does, then when to use it.
Description template
description: <Verb> <specific output> from/for <specific input or context>. Use when <the situations and phrases that should trigger it>.- Start with a concrete verb and output: “Write release notes”, “Audit a web page for SEO”, “Convert Figma frames to React components”.
- Name the inputs or context: “from commits and merged pull requests”, “for a single URL”, “using our component library”.
- Spell out the triggers: the requests, file types and situations where the skill applies, in the words people actually use.
- Add boundaries if needed: “Not for internal changelogs” stops it firing on near misses.
Before and after
| Weak description | Why it fails | Stronger description |
|---|---|---|
| Helps with writing. | Matches everything and nothing | Edit marketing copy into our brand voice: short sentences, active verbs, no jargon. Use when drafting or revising web pages, emails or social posts for the company. |
| PDF tool. | No verb, no trigger | Extract text and tables from PDF files and fill in PDF forms. Use when the user provides a PDF or asks to read, extract from, or fill a PDF. |
| A skill for code reviews that is really thorough and follows best practices. | Adjectives instead of specifics | Review a branch or pull request for correctness, security, tests and readability, and report findings by severity. Use when asked to review code, check a PR or prepare a branch for merge. |
| Database stuff. | Vague scope | Write and review PostgreSQL schema migrations that are safe to run on a live database. Use when creating or changing tables, columns or indexes. |
Write descriptions as a plain statement about the skill (“Extracts text and tables from PDFs…”), not in the first person (“I can help you…”) or addressed to the user (“You can use this to…”). The agent reads it alongside many others, and a plain statement is easiest to compare.
Include the words people actually say
People rarely ask for a task the way its author thinks of it. One person says “changelog”, another “release notes”, another “what’s new”. A skill for spreadsheets should mention “Excel”, “CSV” and “.xlsx” if those are what people bring. List the common phrasings and file types naturally in the “Use when” part. You don’t need every synonym, just the ones that come up.
Balance: too narrow versus too broad
| Problem | Symptom | Fix |
|---|---|---|
| Too narrow | The skill only loads when you name it | Add the situations and phrasings it should cover |
| Too broad | It loads for unrelated tasks or crowds out other skills | Make the output specific and add a “Not for…” boundary |
| Overlapping | Two skills compete and the choice seems random | Merge them, or make each description clearly distinct |
| Buried trigger | It loads late, after the agent has started | Put the “Use when” clause in the description, not only in the body |
Keep it short and self-contained
The description sits in context in every session, alongside every other installed skill’s, so a few lines at most is the right length. Hosts also enforce a maximum length, so long descriptions may be cut off. Don’t put instructions in the description; it should say when to use the skill, and the body should say how. And make it understandable on its own: the agent won’t have read the body when it decides.
Don’t try to make a skill load more often by stuffing its description with keywords or telling the agent to “always use this skill”. It degrades the agent’s choices for everything else, and many reviewers treat it as a red flag when deciding whether to trust a skill.
The name helps too
The name is shorter but also visible to the agent. Make it descriptive: pr-description beats helper, and postgres-migrations beats db. Use lowercase with hyphens and keep it matching the folder name.
Test your description
Descriptions are easy to test because you only need to send requests and see whether the skill loads. Write down a small set of prompts in three groups and try each in a fresh session.
A simple trigger test plan
Should trigger (aim for all of these):
- "Write the release notes for this sprint"
- "Can you draft a changelog entry for v2?"
- "What's new since the last tag? Write it up for users."
Should NOT trigger (aim for none):
- "Write a commit message for this change"
- "Summarise this pull request for me"
- "Update the README"
Edge cases (decide what you want, then check):
- "Write internal notes on what the team shipped this week"- Run each prompt in a new session so earlier context doesn’t influence it.
- Note whether the skill loaded and whether it should have.
- Change one thing in the description at a time, then rerun the set.
- Keep the prompt list with the skill so you can rerun it after future edits.
Some skill-building tools, including Anthropic’s skill-creator skill, can help run this kind of trigger test and suggest description improvements. Even by hand, ten prompts take a few minutes and catch most problems.
Skill CreatorAgent skillHelps draft, test and improve skill descriptions.Agent skill · MIT
Skill Development GuideAgent skillGuidance on structuring skills for Claude Code plugins.Agent skill · Apache-2.0PPrompt Quality CheckerBrowser toolSpot vague wording in a description or prompt.Key takeaways
- The agent picks skills from descriptions alone, so the description decides whether the skill is used.
- Say what it does, with a concrete verb and output, then when to use it.
- Include the words and file types people actually use; add a boundary to prevent near misses.
- Test with should, should-not and edge-case prompts in fresh sessions.
Put it into practice
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Written by the AI Tool Garage editors. Tool details link to their catalogue pages, which are refreshed weekly; spotted something out of date? Tell us.