How to Write a Skill Description That Actually Triggers

At startup the agent sees only each skill's name and description. If the description doesn't match how you ask for things, the skill never loads.

Formula

[What it does] + [Use when ... trigger phrases / file types / situations].

Bad

Helps with documents.

Good

Extracts text and tables from PDF files, fills forms and merges documents. Use when working with PDF files or when the user mentions PDFs, forms or document extraction.

(That's the example from Anthropic's skill authoring guide.)

Tips

• Write in the third person.
• Include the words you actually type: "summarise", "tl;dr", "recap".
• Mention file types or tools (".csv", "Excel", "PR").
• Stay well under 1,024 characters; 200–400 is usually enough.
• No angle brackets or XML tags — validators reject them.
• Put the main use case first: some tools shorten long descriptions when you have lots of skills installed (Claude Code caps the listing at 1,536 characters; Codex trims descriptions to fit its budget).

MakeASkill writes a trigger-tuned description from your answers. Generate one.