Skill Triggers That Fire

You built a skill. It's well-written, it does exactly what you wanted when you tested it — and then Claude just never uses it again. The skill isn't broken. Its description is.

Claude never reads the whole file to decide

Here's the part most people get wrong about how skills work: when Claude is deciding whether a skill is relevant to the current conversation, it doesn't read the full SKILL.md. It reads the name and the short description. Based on that description alone, it decides whether to load and trigger the skill.

That means the description isn't documentation — it's the entire interface Claude uses to route work to your skill. If the description doesn't clearly match the situation you built the skill for, the skill sits there unused no matter how good the instructions inside it are.

Vague descriptions almost never fire

A description like "edits posts" reads fine to a human skimming a list of skills. To the routing decision Claude makes on every turn, it's nearly useless — it doesn't distinguish this skill from ten other things that could loosely be called "editing," and it gives no signal about when to reach for it.

Compare that to a description built around an explicit trigger condition:

"Use when Peter pastes a draft post or newsletter or asks to edit title or punch up a long-form piece."

That version names the exact situations that should activate the skill: pasting a draft, asking to edit a title, asking to punch up long-form writing. There's no ambiguity for Claude to resolve — the description does the matching work directly.

How to rewrite your descriptions

1. Open each skill you've built and read only the description line — pretend you're Claude seeing nothing else.
2. Ask what situation should trigger it, specifically. Not "handles writing tasks" but "user pastes a draft newsletter or asks to punch up a long-form piece."
3. Lead with "use when..." and finish the sentence with the concrete situation, action, or phrase that should set it off. If you can list two or three real scenarios, put all of them in.
4. Re-test in a fresh conversation. Trigger the situation you described and confirm the skill actually loads — don't just trust that the new wording reads better to you.

A skill sitting unused is a triggering problem, not a bad skill

This is the reframe worth internalizing: if a skill you built never fires, the instinct is to assume the skill itself is wrong and start rewriting the instructions. Usually the instructions are fine. The description is the thing that's failing, silently, because there's no error message when Claude decides not to load a skill — it just doesn't happen, and you have no visibility into why.

The manual fallback while you tune wording

You don't have to get the description perfect before you can use the skill. Skills can be triggered manually by name — you can explicitly tell Claude to use a specific skill regardless of what its description says. That gives you a way to keep using and refining a skill's actual behavior while you iterate on the description separately, without the two concerns blocking each other.

Power tricks

• Write the description first, not last. Treat it as the most important sentence in the file, not a summary dashed off after the real work is done.
• Describe trigger, not capability. "Can edit any writing" tells Claude what the skill is capable of, not when to reach for it over anything else.
• Force-trigger by name during tuning. Use manual invocation to keep exercising a skill's real behavior while you iterate purely on the wording of its description.

Resources

• Claude docs — Agent Skills overview
• Anthropic — Introducing Agent Skills