エージェントが本当に読む SKILL.md の書き方

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

1. Pick a slug of lowercase letters, digits, and hyphens. Keep it under 64 characters.
2. Write a description that starts with the trigger: "Use when…". Mention the nouns the user will actually type.
3. State what the skill does not cover, so it does not steal unrelated tasks.
4. Put the procedure in short numbered steps. One action per step.
5. Move long examples into references/. Keep SKILL.md loadable in one screen.
6. 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.