Writing Great Skill Descriptions

A skill that never triggers is a skill that does not exist. The description: field in SKILL.md is the matching surface — get it wrong and your skill sits silent forever. Here is what works.

The rule

Describe when to trigger, not what the skill does.

Bad: "PDF generator using @react-pdf/renderer" — describes the implementation.

Good: "When the user asks to generate, export, or download a PDF — invoices, receipts, reports — produce a single-page PDF and return a download link." — describes the trigger.

The formula

When the user [verbs] + [nouns], do [outcome].

List synonyms. Pretend the user is sloppy.

Six rewrites

1. Email sender → "When the user asks to send, dispatch, or queue an email — transactional, marketing, or alerts — compose and send via Resend."
2. Auth setup → "When the user asks to add login, sign-up, magic links, OAuth, or protected routes, wire up Supabase Auth end-to-end."
3. i18n → "When the user mentions translations, multilingual, localization, i18n, or different languages, extract strings and add language switcher."
4. Image optimizer → "When the user asks to compress, optimize, or convert images, or mentions slow page load, batch-optimize public/ assets."
5. Form builder → "When the user asks to add a contact form, lead form, signup form, or any form with validation, build it with react-hook-form + zod."
6. Analytics → "When the user asks to track events, add analytics, or measure conversions, wire up PostHog and emit events on key actions."

Need help drafting yours? Generator here.