A Skill is only useful if it triggers at the right moment and gives Claude exactly enough to act on. That means writing a sharp description, keeping the body lean, and treating the file as instructions for a competent reader, not documentation for a human.
The description field does the triggering.
Claude decides whether to load a Skill based on its name and description, before it has read the body. A description that just restates the skill's name ("helps with reports") gives the model nothing to match against. A description that lists concrete trigger phrases, file types, or task shapes the user is likely to mention gets picked up far more reliably.
Write the description the way you'd write a search query you expect to match the user's actual words, not a category label.
Keep the body procedural, not informational.
SKILL.md isn't a wiki page. It's a set of instructions a capable reader executes once, right now, on a real task. Background, history, and rationale belong in a comment or a linked reference file — not the main body, where every paragraph competes for the model's attention.
Lead with what to do. State constraints and conventions as rules, not prose. If a step has a fixed sequence, number it.
Push detail into referenced files, not inline.
Skills can ship supporting scripts, templates, and reference docs alongside SKILL.md. Anything that's only needed in an edge case — a full schema, a long example, a rarely used flag — belongs in a separate file that gets read on demand, not loaded by default with every invocation.
This keeps the default load small and fast while still making deep detail available when the task actually calls for it.
Test the trigger, not just the output.
It's easy to validate that a Skill produces the right output once you've manually invoked it. The harder, more important test is whether it fires on its own from a natural request — the phrasing a real user would actually type, not the phrasing you used while building it.
If a Skill never triggers under its intended phrasing, the body quality doesn't matter. Fix the description first.
Write the description for the matcher and the body for the executor. If you only optimize one of the two, the Skill will either never fire or fire and underdeliver.