How to write a SKILL.md that an agent will actually load

Name, description, and when-to-use are the whole discovery surface. Write those three first, then the procedure.

Write the name, the description, and the when-to-use line first. Those three fields are the only discovery surface most agents read before they open the body. A beautiful procedure that never loads is dead weight.

Authoring checklist

Pick a slug of lowercase letters, digits, and hyphens. Keep it under 64 characters.
Write a description that starts with the trigger: "Use when…". Mention the nouns the user will actually type.
State what the skill does not cover, so it does not steal unrelated tasks.
Put the procedure in short numbered steps. One action per step.
Move long examples into references/. Keep SKILL.md loadable in one screen.
Run the validator before you commit.

Description patterns that load

Good: "Use when the user wants to merge, split, or fill PDF files, including scanned documents."
Weak: "A powerful PDF toolkit for modern teams." It never says when.

Generate a starter file with the SKILL.md generator, then edit the trigger line until a stranger would know when to call it.