Your Claude Code Skill Never Fires — and It's Not the Skill's Fault

I manage a dev team, and we've been running Claude Code daily for months. I built a set of custom skills for us — code review, a debugging protocol, our team conventions — and the biggest lesson I learned surprised me: The body of your skill barely matters if the description is wrong. The failure mode nobody warns you about Here's what happens to most developers who discover skills. They get excited, write a detailed 200-line SKILL.md encoding everything they know about code review... and then it never triggers. Not once. They conclude skills "don't really work" and go back to re-typing the same prompt every session. The skill was probably fine. The description killed it. The description is a routing rule, not documentation A skill's description is the only part Claude sees upfront. The full instructions load only after the description matches your request. So the description isn't marketing copy — it's a routing rule, and it needs to be written like one. Compare: # WEAK — reads nicely, never triggers description : Helps with code quality and best practices. # STRONG — names the situations AND the phrasings description : Security-first code review for Python/FastAPI. Trigger when the user asks to "review", "check", or "look at" code, pastes a function or endpoint, mentions a bug, or asks "what's wrong with this". Also trigger on short requests like "review this". The difference: the strong version contains the actual words you type. Including the lazy ones. Nobody writes "please perform a comprehensive quality assessment" at 11pm — they write "review this". If your description doesn't cover the two-word tired version, your skill sleeps through most of your real requests. Three rules that fixed my skills 1. List your real trigger phrases. Open your chat history and look at how you actually phrase requests. Those exact phrases go in the description — "fix it", "what's wrong here", "check this". Your real vocabulary, not your professional vocabulary. 2. Name the artifa