Anatomy of a great SKILL.md

Every skill on the shelf is one file. That constraint is the point: if you can't say how you work in a page, you don't know how you work yet. The great ones share an anatomy.

One file, three jobs

• Name the trigger — when should an agent reach for this skill, and when should it leave it alone.
• Encode the judgment — the checks, the order, the defaults you'd apply yourself.
• Draw the line — what the skill refuses to do, because refusals are taste too.

---
name: tailwind-refactor
description: Flattens divs, dedupes utilities, extracts variants.
---
Never touch markup you can't see rendered.
Prefer deleting a class to adding one.

Opinions are the product

A skill that could have been written by anyone will be replaced by one that couldn't. The strongest files read like their author sounds — specific, a little stubborn, and honest about their edge cases. Generic instructions are already free; your way of doing it is what's scarce.