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

assaf baruch — Sat, 08 Aug 2026 20:39:09 +0000

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 artifacts, not just the verbs. "When the user pastes Python code", "when a stack trace appears", "when a diff is shared". Half my requests don't contain a verb at all — I just paste code. The description has to catch that.

3. Draw the boundary. Say what the skill is not for: "not for writing new features — that's handled by the builder skill". Without boundaries, overlapping skills shadow each other and you get the wrong specialist answering.

Test it like code

My rule now: after writing a skill, open a fresh session and make five requests the way I'd naturally type them — tired, abbreviated, mid-task. If the skill fires on four out of five, it ships. If not, the description needs more of my real phrasing, not more adjectives.

Treat every miss as a bug. The fix is almost always adding one more real-world phrasing to the description.

I packaged everything I learned building skills for my team — the anatomy, five battle-tested patterns, a complete production-ready security-review skill, and the seven mistakes I made — into a short field guide: Stop Prompting. Start Building Claude Code Skills. Happy to answer skill-building questions in the comments either way.

DEV Community: assaf baruch

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

The failure mode nobody warns you about

The description is a routing rule, not documentation

Three rules that fixed my skills

Test it like code