✍️ Write a description that triggers correctly
The description is the trigger — the agent reads the ~100 words of metadata to decide whether to trigger. A good one has three parts: what it does, when to use and be a little "pushy", because the agent tends to under-trigger.
WHAT it does (result, not activity)
Lead with the result. frontend-design: "Create production-grade frontend interfaces". Not "helps with"— deliverable something.
WHEN to use (concrete triggers)
"Use this skill when..." + task examples. supabase goes further: "Triggers:..." lists the textual cues that should activate it.
Be “pushy” (counter under-triggering)
"Use when doing ANY task involving X." Claude fails by not triggering; a firm description fixes that — without becoming a vacuum that triggers on everything.
anatomy of a strong description (Supabase pattern):
[O QUE] Use when doing ANY task involving Supabase.
[QUANDO] Triggers: criar tabela, RLS policy, query Postgres,
migrations, auth, edge functions, storage.
[PUSHY] "ANY task" + lista de triggers = dispara sempre que
o assunto aparece, raramente fora dele.
💡 The 100-word rule
The description always stays in context (level 1 of progressive disclosure). Every word is costly — cut marketing adjectives, keep the trigger. Dense "what + when" wording beats any pretty prose.
🎯 Atomic scope: one responsibility
A skill should do one thing. It’s what makes vercel-react-best-practices (443k) and test-driven-development (107k) trigger precisely. If yours tries to cover everything, it won’t fit into context well, will trigger incorrectly, and won’t compose.
✗ Bloated scope
- ✗"web-helper": React + CSS + deploy + tests + SEO
- ✗Triggers on any web task — constant noise
- ✗1,500-line body that overflows the context
- ✗Impossible to test: what exactly does it guarantee?
✓ Atomic scope
- ✓Split into 4: react-patterns, css-layout, deploy, tests
- ✓Each one fires only on its own trigger
- ✓Body under 500 lines (disclosure level 2)
- ✓Testable and composable, like the azure-skills suite
Single-sentence test
Describe the skill in one sentence without using "and" or "also." Can you do it? It’s atomic. Does the sentence have three clauses connected by "and"? Those are three skills. Microsoft didn’t make "azure-everything" — it made foundry, ai, deploy, diagnostics, and prepare.
✅ The polishing checklist
Before publishing, run the skill through this checklist. Each item separates a skill that looks like quality than one that é. Inspired by the canonical skill-creator workflow (anthropics).
| # | Check | Why |
|---|---|---|
| 1 | description has WHAT + WHEN + triggers | is the routing |
| 2 | fits in one sentence without "and" | atomic scope |
| 3 | body <500 lines, imperative mood | absorbs into the context |
| 4 | explains WHY, not just MUSTs | the agent generalizes better |
| 5 | ran 2–3 realistic test prompts | proves it triggers and helps |
| 6 | repeated scripts extracted for bundling | level 3 on demand |
| 7 | self-explanatory name | clear discovery |
the loop, in commands:
npx skills add anthropics/skill-creator # use a meta-skill # escreva draft → rode test prompts (com-skill vs baseline) # avalie → generalize do feedback → enxugue → extraia scripts # otimize a description (should-trigger / should-not) → repita
💡 Polish ≠ more text
Polishing a skill almost always means remove: cut redundant instructions, move details to bundled resources, tighten the description. A lean skill triggers more reliably and uses less context.
🔁 Before / After: a weak skill → strong
The classic case. Same intent (“help with SQL”), two executions. On the left, what nobody installs. On the right, the supabase-postgres-best-practices standard (203k).
✗ Before — weak
name: sql-helper description: Helps with SQL and databases and queries and more.
- ✗Without the WHEN—the agent doesn’t know when to trigger
- ✗"and more" = infinite scope
- ✗Generic name, unknown source
✓ Strong afterward
name: postgres-best-practices description: Use when writing or reviewing Postgres SQL. Triggers: schema design, indexes, RLS, query perf, migrations. Enforces idiomatic, safe, performant Postgres.
- ✓"Use when..." + concrete triggers
- ✓Atomic scope: Postgres only
- ✓Stated result, obvious name
What really changed
None of the technical content — only the routing e o focus. A strong version triggers in the right cases, doesn't trigger in the wrong ones, and says exactly what it delivers. It's the difference between look like useful and be used.
📐 Ready-to-use description template
Copy it, fill in the brackets, and cut what’s left over. This template combines the frontend-design patterns (what + examples) and supabase patterns (“pushy” triggers).
template (paste into the frontmatter):
name: [nome-autoexplicativo-em-kebab] description: [VERBO de resultado] [o que entrega]. Use this skill when [situação principal] (examples include [ex1], [ex2], [ex3]). Triggers: [gatilho1], [gatilho2], [gatilho3]. [Diferencial: o que ela garante e outras não].
filled-in example (migration skill):
name: db-migrations-safe description: Generate and review reversible database migrations. Use this skill when the user adds, alters, or drops schema (examples include new column, index, rename table, backfill). Triggers: ALTER TABLE, CREATE INDEX, migration file, schema change. Always produces an up + down pair and warns about locking on large tables.
💡 Calibrate the triggers
List 3–5 triggers that should trigger it and think of 2–3 similar near-misses that no should. If the description doesn't distinguish the two groups, it will trigger incorrectly — the topic of module 2.5.
🚦 The Complete Creation Loop
Bringing it all together: creating a quality skill is iterative, not a guess. Capture the intent, write it, test against a baseline, generalize from feedback, and optimize the description. Repeat until it triggers correctly.
Capture intent + draft
Define the single responsibility. Write the imperative SKILL.md, <500 lines.
2–3 realistic test prompts
Run with-skill vs. baseline. Did the skill improve the result?
Generalize + trim
Pull general rules from the feedback, explain why, and extract repeated scripts into bundled.
Optimize the description + package it
Tune with should-trigger / should-not-trigger queries and near-misses. Then publish.
💡 Where to go deeper
The complete anatomy of SKILL.md is in Trail 3, and the creation loop is covered in detail in Trail 4. Here you already have enough for a first skill that looks like and is quality.
✅ Module Summary
Next:
Module 2.5 — 🚀 Advanced Tips: Signals Only Experts Notice. Triggering precision, token efficiency, reading transcripts, eval pass rates, and why a popular skill can still be bad.