What this covers
Skills look like a checkbox you turn on, but they are really a small program with instructions, tools, and trigger rules. The walkthrough here shows what actually happens when you type a message — when Claude auto-fires a Skill, when it sits idle and waits, and how to write the Skill description so it does not get skipped for the wrong reason.
Who this is for
Anyone who has shipped one Skill and watched it never fire, or anyone tempted to build five Skills before understanding why the first one fails silently. PMs and builders who want their team to actually adopt internal Skills. Beginners can skim and come back after one hands-on attempt.
When to reach for it
When you have a recurring task — chart generation, ticket triage, PR summaries, doc-cleanup — that you already know how to prompt for, and you want it to fire without re-pasting context. Skills are wrong for one-off tasks; they pay off the third time you do the same thing in one week.
Before you start
- Have one task you can run by hand in a normal Claude chat first. If you cannot prompt it manually, you cannot package it as a Skill.
- Pick a Skill name that describes the action, not the topic. “Generate weekly status table” beats “weekly stuff”.
- Decide on the trigger surface: explicit invoke via name, or auto-fire from natural language. The description text is what controls this.
- Have a 2-3 line success example ready — you will paste it into the Skill description so the matcher knows what to look for.
Step by step
- Open the Skills panel in Claude and create a new Skill. The single most important field is the description — Claude reads it on every message to decide whether to fire. Write it as “Use this Skill when the user asks to do X with Y inputs.”
- Write the Skill instructions like a system prompt with sections: role, inputs expected, steps, output format, refusal rules. Keep it under roughly 600 words; longer reads slower and is no more reliable.
- Attach the tools the Skill needs — file analysis, web search, code execution — and remove the ones it does not. Extra tools widen the failure surface and slow first-token time.
- Save and test with the exact phrasing in your description. If the Skill does not fire, the description is mismatched, not the model. Tighten phrasing before changing instructions.
- Then test with a paraphrase you would actually say. If the paraphrase misses, broaden the description with one or two synonyms; do not rewrite the instructions yet.
- Pin the Skill to a Project so your team picks it up automatically inside that workspace. See Claude Projects for the surrounding setup.
First-run exercise
- Build one Skill for the smallest task you do weekly — “summarize this Zoom transcript into 5 bullets and 3 action items”.
- Fire it 5 times across the week with different transcripts. Log whether it auto-fired or you had to call it by name.
- After 5 runs, edit only the description — not the instructions. Auto-fire rate usually doubles after one description rewrite.
- Share the Skill with one teammate and ask them to fire it without coaching. If they cannot, your description is too internal.
Quality check
- Did the Skill fire on the natural phrasing you wrote in the description? If not, the description is the bug.
- Is the output format stable across runs? A Skill that produces five different shapes is not yet a Skill, it is a prompt.
- Did the Skill avoid firing on adjacent-but-different requests? Over-firing is as bad as under-firing.
How to reuse this workflow
- Keep a
skills-registry.mdfile listing each Skill, its trigger phrase, and the last time you verified it. Skills decay quietly when models update. - Clone a working Skill before forking it for a new task. The description format is the hard part — copy it.
- For team Skills, run a monthly fire-rate review: how often did it auto-fire vs miss vs misfire. Tune description, not instructions, first.
- Pair Skills with Claude Code skills guide if your team also runs Claude Code.
Recommended workflow
Pick one repeating task → run it manually until prompt is stable → write Skill description in “Use this when…” form → paste prompt as instructions → test 5 paraphrases → ship to one Project → review fire rate weekly.
Common mistakes
- Writing the description as a topic (“about meetings”) instead of a trigger (“Use this when the user pastes a meeting transcript and asks for a summary”).
- Building five Skills before any one of them has been fired ten times by a real user.
- Cramming instructions with edge cases. The Skill becomes brittle; broad cases should be in the prompt the user types.
- Treating Skills as silent — users cannot tell which Skill fired. Have the Skill print a one-line “fired Skill X” banner during rollout.
- Stuffing tools “just in case”. Each tool widens the latency and ambiguity of when to fire.
- Never reviewing fire rate. A Skill that misses 60% of the time is worse than no Skill, because users stop trusting Skills overall.
FAQ
- How does Claude decide to fire a Skill?: It reads the description on every message and matches against the user’s text. Description quality is the dominant factor.
- Can I force a Skill to fire by name?: Yes, mention the Skill name in the message. Useful for testing and for Skills you want users to invoke deliberately.
- Do Skills share state across chats?: No. Pair with a Project if you need persistent context.
- Can two Skills fire on the same message?: Usually one wins. Make descriptions disjoint to avoid the coin flip.