Contenido detallado
🧩 La fórmula «Haz + Cuándo»
Toda description sólida tiene dos mitades inseparables: lo que hace la skill e cuándo debe usarse. Las descripciones que solo describen la capacidad («genera informes») dejan a Claude sin la señal más importante: el activador. Es como tener un currículum brillante, pero nunca decir a qué puesto te postulas.
✓ Tiene "Haz + Cuándo"
- ✓"Soluciona problemas de diseño del frontend mediante pruebas en vivo en el navegador. Úsala cuando el usuario quiera corregir elementos recortados o ajustar diseños visualmente."
- ✓Claude sabe qué recibe Y con qué solicitud encaja.
✗ Solo el «Haz»
- ✗"Una skill para solucionar problemas de frontend."
- ✗Describe la capacidad, pero no dice cuándo aplicarla: la activación queda al azar.
💡 Consejo práctico
Escribe la description y subraya mentalmente las dos partes. Si no puedes señalar dónde está el "cuándo", todavía no está lista. La expresión "use when" (o "usa cuando") es casi obligatoria.
🔫 Disparadores concretos
Uno disparador concreto es una frase o palabra real que el usuario diría cuando necesita la skill. Cuanto más se acerque al lenguaje del usuario, mejor será el matching. Las skills bien hechas incluyen varios activadores — incluidos comandos de barra y sinónimos — para abarcar las distintas formas de pedir lo mismo.
# Gerador de itinerários
"plan a trip", "create an itinerary", "travel planner", /travel
# Correção de frontend ao vivo
"fix CSS/HTML changes", "fix cut-off elements", "adjust layouts visually"
# Padrão: linguagem do usuário + sinônimos + comando de barra📊 Tres fuentes de activación
- Verbos de acción: "crear", "corregir", "revisar", "generar": lo que el usuario quiere hacer.
- Objetos concretos: "itinerario", "factura", "workflow", "informe": lo que quiere obtener.
- Comandos de barra:
/travel,/review— el atajo explícito.
💡 Consejo práctico
Antes de escribir los activadores, imagina a cinco personas diferentes pidiendo lo mismo, cada una con sus propias palabras. Los puntos en común entre esas cinco frases son tus mejores activadores.
💡 Ejemplos dentro de la description
Para skills de alcance amplio o ambiguo, incorporar ejemplos breves de uso en la propia description le da a Claude anclas semánticas que la prosa abstracta no le da. "Muestra, no solo cuentes" aplica tanto al usuario como al modelo: un caso concreto aporta más información que una definición genérica.
🎯 Abstracto vs. anclado
"Helps with data analysis tasks."
"Analyzes a CSV and returns top trends. Use when the user says 'what's in this data?', 'find outliers', or 'summarize this spreadsheet'."
📐 Cuándo vale la pena
- Alcance amplio: la skill hace muchas cosas; los ejemplos delimitan.
- Término genérico: palabras como "helper" o "analysis" necesitan un ancla.
- Confusión con las skills vecinas: los ejemplos permiten distinguirla de skills parecidas.
🚫 Antipatrones que arruinan el disparo
La forma más rápida de corregir una skill que no se activa es identificar el antipatrón en tu description. Casi todas las descriptions defectuosas caen en uno de estos cuatro errores, y cada uno tiene una corrección directa.
Demasiado vago
"Helps with various tasks."
Corrección: nombra la tarea específica y los activadores. "Various" nunca coincide con nada y con todo al mismo tiempo.
Solo «qué hace», sin «cuándo»
"Generates HTML pages."
Corrección: añade la mitad del «cuándo». Sin un disparador, Claude no tiene forma de saber que la solicitud actual aplica.
Jerga sin contexto
"Runs the v2 pipeline orchestrator."
Corrección: traduce al lenguaje del usuario. Nadie pide «ejecuta el orquestador v2»; pide el resultado que ofrece.
Superpuesta con otra skill
Dos skills con descripciones casi idénticas.
Corrección: diferénciala por su alcance y agrega "no la uses para X" (tema siguiente). Las descriptions que se superponen generan activaciones aleatorias.
🛑 Cuándo NO disparar
Esta es la parte que casi todo el mundo olvida, y es lo que diferencia una buena description de una excelente. Definir el alcance negativo ("no lo uses para X") evita falsos positivos: que la skill se active con solicitudes parecidas, pero equivocadas. Un falso positivo frustra tanto como un falso negativo, porque entrega el resultado incorrecto con seguridad.
🛑 El poder del límite explícito
Compara una skill de "corrección de frontend en vivo". Se ocupa del diseño y del CSS, pero NO de la arquitectura. Dejarlo explícito impide que se active con solicitudes como "agrega una base de datos".
"Úsalo para errores visuales/de diseño. No para cambios en el backend, arquitecturas nuevas ni trabajo con bases de datos; usa un plan estándar para eso."
✓ Activar cuando
- ✓La solicitud encaja claramente con la capacidad central
- ✓Aparece un disparador concreto en la solicitud
- ✓Es exactamente el problema que resuelve la skill
✗ NO activar cuando
- ✗La solicitud solo parece relacionada, pero se trata de otra cosa
- ✗Llega a un caso que la skill enumera como fuera de alcance
- ✗Otra skill es claramente más adecuada
💡 Consejo práctico
Para cada skill, escribe una frase que empiece con "No uses esta skill para...". Si no puedes completarla, probablemente el alcance de la skill sea demasiado impreciso y se activará cuando no corresponda.
🧪 Probando el disparo
Una description es una hipótesis sobre cuándo debe activarse la skill. Solo la prueba lo confirma. El ciclo es simple: ejecuta solicitudes reales y variadas, observa si la skill se activa cuando debe y permanece inactiva cuando no debe, y ajusta la description. Es una iteración, no un único intento.
Arma casos de prueba
Enumera solicitudes que deben activar (positivos) y solicitudes similares que no deben (negativos). Los buenos negativos son solicitudes similares, no absurdas.
Ejecuta en lenguaje natural
Pide cada caso sin mencionar la skill por su nombre. Estás probando la description, no la invocación explícita.
Cuenta los errores y ajusta
¿Falso negativo (no se activó y debería)? Añade disparadores. ¿Falso positivo (se activó y no debería)? Reduce el alcance negativo. Repite.
⚠️ Atención
No optimices la description solo para los positivos. Una description que se activa con todo tiene un 100 % de aciertos entre los positivos y es inútil, porque también se activa con todos los negativos. El equilibrio entre ambos es el objetivo.
💡 Consejo práctico
Guarda tus casos de prueba en un archivo. Cada vez que modifiques la description, vuelve a ejecutar la batería. Es la forma más económica de evitar regresiones: ajustar para un caso suele romper otro.
🧰 Prompts copiables
Usa estos prompts para escribir y probar descriptions contundentes con Claude.
Minha skill faz: <descreva>. Escreva uma description no padrão
"Faz + Quando", com: (1) o que produz, (2) 3 a 5 gatilhos concretos
na linguagem do usuário, e (3) uma frase de escopo negativo
("não use para...").Avalie esta description: "<cole>". Ela cai em algum anti-padrão
(vaga, sem "quando", jargão, sobreposta)? Aponte qual e reescreva
corrigindo o problema.Para esta description: "<cole>", gere 5 pedidos de usuário que
DEVEM disparar a skill e 5 que NÃO devem (mas são parecidos).
Depois diga, para cada um, se a description atual acertaria.📤 Ejemplo de salida
Una description completa, con las cuatro fuerzas de este módulo: qué hace y cuándo, disparadores concretos, ejemplos y alcance negativo.
---
name: meeting-notes
description: Turns a raw meeting transcript into clean notes with
decisions and action items. Use when the user says "summarize
this meeting", "what did we decide?", "pull the action items",
or pastes a transcript and asks for notes. Not for live
transcription or scheduling — only for processing text that
already exists.
---✏️ Ejercicios prácticos
1. Diagnostica y corrige
Toma cinco descriptions vagas (invéntalas o recopílalas) y clasifica cada una según el antipatrón que presenta. Después, reescríbelas todas según el patrón "Hace + Cuándo".
2. Escribe el alcance negativo
Para tres skills tuyas, escribe la frase "No uses esta skill para...". Si te atascas con alguna, anótalo: es una señal de que el alcance está mal definido.
3. Crea un SKILL.md ejecutable y prueba la activación ⭐
Escribe un SKILL.md completo cuya description incluye las cuatro fuerzas: qué hace y cuándo, al menos 3 activadores concretos, un ejemplo integrado y una frase que delimite el alcance negativo. Después, prepara 5 solicitudes positivas y 5 negativas y pídele a Claude que juzgue —basándose solo en la description— cuáles activarían la skill. Ajusta la description hasta acertar todas.
🎯 Resumen del módulo
Siguiente módulo:
Ya entiendes la anatomía, la estructura y el activador. En el Módulo 1.4 reúnes todo con las reglas actuales de Anthropic, una checklist que puedes copiar y un validador para auditar tus skills.