A brilliant skill that lives in a menu you never open is worse than a mediocre one that auto-triggers. The difference is the description. Here's how to write one that works.
Every skill has a description line. It's not decoration — it's the trigger. Claude reads descriptions to decide which skill, if any, matches your request. A vague description ("helps with reports") never gets picked because it matches nothing in particular.
The lesson, learned the hard way by people who've built skill libraries: design for invocation, not capability. A skill that never fires is wasted, no matter how good its instructions are.
Start every description with "Use when" and finish the sentence with the exact situation the skill covers. Then add one short line on what it does. This structure forces you to name a concrete trigger instead of a vague theme.
description: Use when the user asks for their weekly status report or says "write up my week". Gathers the week's work into a clean summary.
List the real phrases you'd type when you want this skill. If you'd say "write up my week," put that in the description. If you'd say "weekly report," add that too. The more natural trigger phrases you include, the more reliably the skill fires.
Avoid jargon you'd never actually use. The description should sound like you on a normal day, because that's what Claude is matching against.
Make your request plainly, without naming the skill, and see what Claude picks. Glance at the first lines of the reply to confirm the right skill fired. If it missed, add the phrase you just used to the description and try again.
A few rounds of this turns a skill that needs babysitting into one that just works.
Formulas, good vs bad examples, and a test routine for writing descriptions that auto-fire.