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
