✍️ Escribir una description que se active correctamente
La description es el activador: el agente lee las ~100 palabras de metadata para decidir si la activa. Una buena tiene tres partes: qué hace, cuándo usar y ser un poco "insistente", porque el agente tiende a subdisparar.
QUÉ hace (resultado, no actividad)
Empieza con el resultado. frontend-design: "Create production-grade frontend interfaces". No "ayuda con" — entrega algo.
CUÁNDO usar (activadores concretos)
"Usa esta skill cuando..." + ejemplos de tareas. supabase va más allá: "Triggers:..." enumera las señales textuales que deben activarla.
Sé "pushy" (contra la activación insuficiente)
"Úsala cuando..." Claude se equivoca al no activarla; una descripción firme lo corrige — sin convertirse en una aspiradora que se activa con todo.
anatomía de una description sólida (patrón de supabase):
[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.
💡 Regla de las 100 palabras
La description siempre permanece en el contexto (nivel 1 de progressive disclosure). Cada palabra cuesta: elimina los adjetivos de marketing y conserva los activadores. Las frases densas de "qué + cuándo" superan cualquier texto bonito.
🎯 Alcance atómico: una responsabilidad
Una skill debe hacer una cosa. Es lo que permite que vercel-react-best-practices (443k) y test-driven-development (107k) se activen con precisión. Si la tuya intenta abarcarlo todo, se asimila mal en el contexto, se activa cuando no corresponde y no se combina con otras.
✗ Alcance inflado
- ✗"web-helper": React + CSS + deploy + pruebas + SEO
- ✗Se activa en cualquier tarea web: ruido constante
- ✗Cuerpo de 1.500 líneas que desborda el contexto
- ✗Imposible de probar: ¿qué garantiza exactamente?
✓ Alcance atómico
- ✓Divídela en 4: react-patterns, css-layout, deploy, testes
- ✓Cada una se activa solo con su propio activador
- ✓Cuerpo <500 líneas (nivel 2 de disclosure)
- ✓Probable y componible, como la suite azure-skills
Prueba de la frase única
Describe la skill en una frase sin usar "y" ni "también". ¿Lo lograste? Es atómica. ¿La frase tiene tres cláusulas unidas por "y"? Son tres skills. Microsoft no hizo "azure-everything": hizo foundry, ai, deploy, diagnostics y prepare.
✅ La lista de verificación para pulir
Antes de publicar, revisa la skill con esta lista. Cada punto distingue una skill que parece de calidad que una é. Inspirado en el flujo canónico de skill-creator (anthropics).
| # | Comprobación | Por qué |
|---|---|---|
| 1 | description tiene QUÉ + CUÁNDO + activadores | es el enrutamiento |
| 2 | cabe en una frase sin «y» | alcance atómico |
| 3 | cuerpo <500 líneas, imperativo | absorbe en el contexto |
| 4 | explica el PORQUÉ, no solo los MUST | el agente generaliza mejor |
| 5 | ejecutó 2–3 prompts de prueba realistas | demuestra que se activa y ayuda |
| 6 | scripts repetidos extraídos para bundled | nivel 3 bajo demanda |
| 7 | nombre autoexplicativo | descubrimiento claro |
el loop, en comandos:
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
💡 Pulir ≠ agregar más texto
Pulir una skill casi siempre consiste en eliminar: eliminar instrucciones redundantes, mover detalles a bundled resources y afinar la description. Una skill concisa se activa mejor y consume menos contexto.
🔁 Antes / Después: de una skill débil a una sólida
El caso clásico. La misma intención («ayudar con SQL»), dos ejecuciones. A la izquierda, lo que nadie instala. A la derecha, el patrón supabase-postgres-best-practices (203k).
✗ Antes — débil
name: sql-helper description: Helps with SQL and databases and queries and more.
- ✗Sin el CUÁNDO, el agente no sabe activarse
- ✗"y más" = alcance infinito
- ✗Nombre genérico, fuente desconocida
✓ Después — sólido
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.
- ✓"Úsala cuando..." + activadores concretos
- ✓Alcance atómico: solo Postgres
- ✓Resultado declarado, nombre obvio
Qué cambió de verdad
Nada del contenido técnico: solo el enrutamiento e o enfoque. La versión sólida se activa en los casos correctos, no se activa en los incorrectos y dice exactamente qué entrega. Esa es la diferencia entre parecer útil y ser usada.
📐 Plantilla de description lista para usar
Cópiala, completa los corchetes y elimina lo que sobre. Esta plantilla combina los patrones de frontend-design (el qué + ejemplos) y supabase (disparadores "insistentes").
template (pega en el 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].
ejemplo completo (skill de migraciones):
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.
💡 Calibra los activadores
Enumera 3–5 activadores que deben activarla y piensa en 2–3 casos límite similares que no deben. Si la descripción no distingue los dos grupos, se activará de forma incorrecta — tema del módulo 2.5.
🚦 El ciclo completo de creación
En conjunto: crear una skill de calidad es un proceso iterativo, no una apuesta a ciegas. Captura la intención, escribe, prueba contra el baseline, generaliza a partir del feedback y optimiza la description. Repite hasta que se active correctamente.
Capturar la intención + borrador
Define una única responsabilidad. Escribe el SKILL.md en modo imperativo, <500 líneas.
2–3 prompts de prueba realistas
Ejecuta con-skill vs baseline. ¿La skill mejoró el resultado?
Generalizar + simplificar
Extrae reglas generales del feedback, explica por qué y pasa los scripts repetidos a bundled.
Optimizar la description + empaquetar
Ajusta con queries should-trigger / should-not-trigger y near-misses. Después, publícala.
💡 Dónde profundizar
La anatomía completa de SKILL.md está en la Trilha 3, y el ciclo de creación detallado en la Trilha 4. Aquí ya tienes lo suficiente para una primera skill que parece y es de calidad.
✅ Resumen del módulo
Próximo:
Módulo 2.5 — 🚀 Consejos avanzados: señales que solo los expertos ven. Precisión del triggering, ahorro de tokens, leer transcripts, pass-rate de evals y por qué una skill popular aún puede ser mala.