Why your agent skill never fires
A skill is chosen on its description, not on its contents. Before the assistant reads a single line of your instructions, it sees only the name and the description of every skill you have installed, and picks from that. If the description does not say plainly what the skill does and when to use it, the file sits there unused.
Five reasons, in the order they are usually the cause
1. The description says what the skill produces, not when to use it.
"Generates a client proposal" tells the assistant nothing about the moment it should reach for the file. "Use when the user asks for a proposal, a quote, a scope of work, or pricing for a project" names the moment. Trigger language beats output language every time.
2. The description is one line long.
Three or four words leave nothing to match against. A description that lists the real phrases a person would use, including the sloppy ones, gives the selector something to catch on.
3. Two skills claim the same ground.
If client-report and weekly-summary both describe themselves as summarising the week, one of them wins every time and it may not be the one you wanted. Give each a distinct boundary, and say in each what it is not for.
4. The file is not where the loader looks.
A skill in the wrong directory, or a folder whose name does not match the skill name, is simply absent. It fails silently, which is why this one wastes the most time.
5. Nothing in the request overlaps the words in the description.
You ask for "a writeup for the Henderson job"; the description talks about reports. Read your own last ten requests and check that the words you actually type appear somewhere in the description.
For how to write a description that gets picked, see the guide on writing a SKILL.md description.
A description that fires, next to one that does not
---
name: invoice-chase
description: Invoice helper.
------
name: invoice-chase
description: Draft a follow-up email for an overdue invoice. Use when
the user mentions an unpaid invoice, a late payment, a client who has
not paid, or asks to follow up on billing.
---Same file underneath. The second one names four phrasings a real person would type, so an ordinary sentence reaches it.
Stop guessing and test it
Reading your own description tells you what you meant, not what the selector sees. Run the skill against the prompts you would really use and watch whether it loads. Ten sample prompts will tell you more than an hour of rewriting, and they keep telling you after the next model update. There is a short guide on testing a skill.
Works with Claude Code.
Check your SKILL.md now
Paste a skill file into the free checker. It lints the frontmatter and the description, then runs your file against a set of realistic prompts and reports whether it would actually be picked, in under a minute. No account needed.
Check a skill file