🎯 La description como único disparador
El campo description en el frontmatter de SKILL.md es el único señal que el agente usa para decidir si debe activar una skill. Es tu "anuncio" para el agente: escríbelo como si tuvieras que convencer a alguien en 5 segundos.
Qué hace eficaz una description
⚡ Escribir frases desencadenantes contundentes
Las frases de activación son las cláusulas TRIGGER when en la description. Enumeran explícitamente los contextos de activación y abarcan múltiples formas en que el usuario puede expresar la misma solicitud.
description: |-
Build, debug, and optimize Claude API / Anthropic SDK apps.
Apps built with this skill should include prompt caching.
Also handles migrating existing Claude API code between
Claude model versions.
TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`;
user asks for the Claude API, Anthropic SDK, or Managed
Agents; user adds/modifies/tunes a Claude feature (caching,
thinking, tool use, batch) or model (Opus/Sonnet/Haiku).
SKIP: file imports `openai`/other-provider SDK, filename
like `*-openai.py`, provider-neutral code, general
programming/ML.✓ Triggers sólidos
- ✓Prefijo explícito "TRIGGER when:" o "Usa cuando:"
- ✓Cubre múltiples formulaciones de la misma solicitud
- ✓Incluye sinónimos y variaciones del dominio
- ✓Menciona artefactos concretos (imports, archivos)
- ✓Probable: "si dice X, ¿debe activarse?"
✗ Triggers débiles
- ✗Sin prefijo, no hay una separación clara del resumen
- ✗Cubre solo 1 formulación ("crea un curso")
- ✗Palabras clave genéricas ("código", "web")
- ✗Demasiado técnico para el usuario ("procesa tokens")
- ✗Sin SKIP: se activa en contextos incorrectos
💡 Técnica: 5 preguntas de prueba
Antes de publicar la skill, prueba la description con 5 preguntas reales que haría el usuario. Para cada una, verifica:
- 1. ¿La skill debería activarse? (sí/no)
- 2. ¿Solo leyendo la description, queda claro que sí/no?
- 3. ¿Alguna otra skill competiría por este trigger?
- 4. ¿SKIP elimina los falsos positivos?
- 5. ¿Alguien sin contexto entendería la description?
🚫 Cláusulas SKIP: evitar activaciones incorrectas
SKIP define los anticasos: situaciones en las que la skill NO debe activarse, aunque haya una superposición temática con el trigger. Es la frontera que separa la skill de sus vecinas.
📊 Por qué importa SKIP
Imagina que tienes claude-api y una skill genérica de "código Python". Sin SKIP, cualquier script de Python que mencione una API podría activar la skill equivocada. SKIP crea límites claros:
- • import anthropic
- • Claude API / SDK
- • Opus, Sonnet, Haiku
- • import openai
- • código independiente del proveedor
- • ML genérico sin SDK
Cómo perfeccionar SKIP en la práctica
Identify false positives
Usa la skill durante 1 semana. Anota cada vez que se active cuando no debería — esos son tus falsos positivos.
Encuentra el patrón
¿Qué tienen en común los falsos positivos? ¿Es una biblioteca? ¿Un tipo de archivo? ¿Un contexto específico?
Agrega a SKIP
Agrega el patrón a la cláusula SKIP de la description. Vuelve a probar con los falsos positivos originales.
✓ SKIP bien redactado
- ✓Prefijo "SKIP:" explícito y en mayúsculas
- ✓Lista los casos en los que no se debe usar, con ejemplos concretos
- ✓Complementa TRIGGER sin contradecirlo
- ✓Refinado con falsos positivos reales
✗ Trampas de SKIP
- ✗SKIP tan amplio que bloquea casos válidos
- ✗Contradice el TRIGGER ("Usar cuando X... SKIP: X")
- ✗Ausencia de SKIP en una skill de alcance amplio
- ✗SKIP demasiado genérico ("SKIP: código general")
🔤 Nombre en kebab-case
El nombre de la carpeta y del campo name en el frontmatter siguen una única convención: kebab-case.
💡 Por qué kebab-case funciona
funciona como slug sin encoding
sin necesidad de comillas en el shell
fácil de escanear al instante
✅ Ejemplos reales de descripciones eficaces
Análisis de descriptions de skills reales en producción. Qué las hace eficaces y por qué.
description: |-
Template e padrões de design para criar páginas HTML de cursos
no formato INEMA.CLUB.
Use esta skill SEMPRE que o usuário pedir para criar, editar ou
revisar páginas HTML de curso — incluindo index de trilhas,
páginas de módulos, componentes como navegação, cards, tópicos
expansíveis, modais e slides.
Acione também quando o usuário mencionar trilhas, módulos,
tópicos, INEMA.CLUB, ou quando pedir para seguir o
"formato de curso" ou "template de curso".
Nao deixe de usar esta skill se o usuário mencionar qualquer
coisa relacionada a páginas HTML de cursos ou ao projeto skillx.Por qué funciona esta description
❌ Antipatrones de description
Las descriptions malas son invisibles (la skill nunca se activa), promiscuas (se activa para todo) o confusas (se activa cuando no debería). Estos son los 4 antipatrones más comunes:
✗ Anti-pattern 1: Demasiado vago
Problema: "código" lo abarca todo. Todas las skills de desarrollo competirán. Ninguna ganará de forma predecible.
✗ Anti-pattern 2: Circular
Problema: todas las skills "usan IA". La descripción debe diferenciarlas, no generalizar.
✗ Anti-pattern 3: Demasiado técnico
Problema: el usuario no piensa en "tokens" y "ventana de contexto"; piensa "necesito una respuesta".
✗ Anti-pattern 4: Sin anclas
Problema: ¿qué API? ¿REST? ¿GraphQL? ¿Anthropic? ¿OpenAI? Sin un punto de referencia específico, la coincidencia será incorrecta.
💡 La prueba de 1 frase
Muéstrale la descripción a alguien que nunca haya visto la skill. Hazle una pregunta: "¿En qué situación usarías esto?" Si la respuesta es vaga o incorrecta, la descripción falló. La prueba toma 30 segundos y ahorra horas de depuración.
🎯 Resumen del módulo
Siguiente módulo:
3.3 — Scripts y referencias auxiliares: cómo estructurar scripts/, references/, .env.example y aplicar progressive disclosure