Why Your AI Agent Skill Isn't Triggering (And How to Fix It)

You wrote a perfect skill. The instructions are clear, the logic is sound — and the agent never uses it. This is the single most common frustration with AI agent skills, and the cause is almost never the skill's body. 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, it loads that skill. If nothing matches closely enough, it proceeds without any skill — even a brilliant one sitting right there. The description is the entire matching mechanism.

The Usual Culprit: Too Narrow

Most failed skills have a description that is too specific. "Reviews pull requests" only matches if you literally mention a pull request. Ask it to "check this file" or "look over my code" and it misses, because those words are not in the description. The skill works — you just never trigger it.

The Fix: Describe How You Actually Ask

Rewrite the description around the words you would naturally type. List the synonyms. A strong code-reviewer description says it reviews code for bugs, style and security, and to use it when the user asks to review, check, audit or look over code, a pull request, a diff or a file. Now it matches almost any natural phrasing.

How to Test It

After fixing a description, test it the way a real user would talk. 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 of this and your skill triggers reliably every time.

The Habit That Prevents It

Get into the habit of writing the description first, around real phrasing, before you even write the body. It flips the problem: instead of writing a great skill nobody triggers, you write one that fires exactly when you need it.