You wrote a skill. The instructions are clear, the logic is sound, and your AI agent never uses it. This is the most common frustration with AI agent skills, and the cause is almost never the body of the skill. It is the description.
How an agent decides to use a skill
When you make a request, the agent scans the descriptions of your installed skills and compares them to what you asked. If a description matches closely enough, it loads that skill. If nothing matches, it proceeds without one — even a great skill sitting right there.
The description is the entire matching mechanism. Everything else in the skill is the work it does; the description decides whether that work ever happens.
The usual culprit: too narrow
Most skills that never fire have a description that is too specific. "Reviews pull requests" only matches if you literally mention a pull request. Ask the agent to "check this file" or "look over my code" and it misses, because those exact words are not in the description. The skill works fine. You just never trigger it.
The fix: describe how you actually ask
Rewrite the description around the words you would naturally type, and list the synonyms.
Weak:
description: Reviews pull requests.
Strong:
description: Reviews code for bugs, style and security. Use when
the user asks to review, check, audit or look over code, a pull
request, a diff, or a specific file.
The strong version matches almost any natural phrasing. That is the whole technique.
A checklist for every description
Before you consider a skill finished, run its description through five questions:
- Does it name the task in plain language a user would actually use?
- Does it list the synonyms — the different ways you might ask?
- Does it say when to use the skill, not just what it does?
- Would it match a casual request, not only the formal phrasing?
- Is it specific enough not to fire on unrelated requests?
Five comfortable answers means the skill will trigger when you need it.
Test it like a user
After writing a description, test it the way you actually talk on a busy day — not the careful phrasing you would use if you were trying to make it work. Phrase a few natural requests and watch whether the skill fires. If a reasonable request misses, add those words to the description and try again. Two or three rounds and it triggers reliably.
Write the description first
The habit that prevents all of this: write the description before the body. It forces you to think about when the skill should fire before you think about what it should do. Get that right, and the careful instructions you write actually get used.
Free starter: The format, a working template, and the description technique are all on a free cheat sheet: AI Agent Skills Quick-Start Cheat Sheet
Go deeper: The full guide covers the complete specification, five build walkthroughs, ten production-ready templates, security, and a 30-day plan: AI Agent Skills: The Complete SKILL.md Standard Guide
Have you had a skill that quietly never fired? What was the description? Happy to help debug it in the comments.
Top comments (0)