Write a SKILL.md That Claude Actually Follows
The description is the trigger, not documentation. How to write both halves so the skill fires when it should and gives specific guidance when it does.
The description is the trigger
Everything depends on the description, because it is what gets matched against the work at hand. Write it as the situation rather than the capability: not "helps with pricing" but "use when a pricing page is not converting and you need to know whether the price, the packaging, or the wording is the problem".
Name the trigger conditions concretely. The phrases a person would actually use when they have this problem are the phrases that should appear. A description written in your own internal vocabulary matches your vocabulary and nobody else's.
Say when not to use it, if there is a neighbouring skill it could be confused with. Two skills whose descriptions overlap will fire unpredictably, and the fix is almost always to sharpen the boundary in words rather than to rewrite either set of instructions.
Structure that holds up
A shape that consistently works: a one-line statement of what the skill does, then when to use it, then the principles, then the steps, then the output format. Each part answers a different question, and skipping any of them shows up as vagueness in the result.
The principles section is the one people leave out and the one that does the most work. Steps tell Claude what to do; principles tell it how to decide when a step is ambiguous. Without them you get the procedure followed mechanically and the judgement missing.
Keep the whole thing shorter than feels thorough. A skill is read in full every time it fires, so every paragraph competes with the actual work for attention. If a section is not changing the output, it is costing you.
5 more sections in this article
- How long, in words
- Write instructions, not essays
- Specify the output
- The two failure modes
- Iterate against real use
This is Pro content
Get Agent Factory Pro - a one-time payment for lifetime access to full articles, complete build prompts, and everything new.
Use it
The parts of the library that put this article to work.
Published 14 August 2026. Last reviewed 17 August 2026. We re-read this library on a schedule and date every article, so you can see for yourself how current it is.