Mapa de la ruta
Contenido detallado
🧬 Anatomía de una Skill
Qué es un SKILL.md, el frontmatter name/description, el cuerpo de instrucciones y cómo Claude descubre y activa la skill por sí solo.
Un archivo Markdown con frontmatter YAML que enseña a Claude a ejecutar una tarea específica cuando se le solicita.
Es la unidad mínima de todo. Quien entiende el archivo entiende el sistema entero.
Texto, no código. Se puede versionar, leer y trasladar entre máquinas.
El identificador único de la skill, en kebab-case, que Claude usa internamente.
Un nombre ambiguo equivale a una skill que nadie encuentra. Es el primer campo que importa.
Breve, descriptivo y estable. Cambiar el name rompe referencias.
La frase que le dice a Claude qué hace la skill Y cuándo usarla. Es lo que lee para decidir si debe activarla.
El 90% del éxito de una skill está aquí. Una descripción débil = una skill muerta.
Hace + Cuándo. Verbos de acción, disparadores concretos.
Todo lo que está debajo del frontmatter: el paso a paso, las reglas, los ejemplos y el formato de salida esperado.
Es donde se define la calidad de la ejecución. Las instrucciones vagas generan resultados vagos.
Workflow, reglas estrictas, formato de salida, principios.
Al principio, Claude solo ve name + description de cada skill: nunca el contenido completo de todas.
Entender esto explica por qué la description lo es todo y por qué demasiadas skills confunden.
Índice ligero, matching semántico, carga bajo demanda.
Cuando la solicitud coincide con una description, Claude carga ese SKILL.md y empieza a seguir sus instrucciones.
Es la diferencia entre una skill que se activa sola y una que tienes que invocar manualmente.
Activación automática, invocación explícita, contexto de la conversación.
📂 Divulgación progresiva y estructura
Las carpetas references/, scripts/ e assets/, la carga bajo demanda y la regla de oro: mantener el SKILL.md conciso.
Estrategia de mostrar primero solo lo esencial y revelar los detalles únicamente cuando sea necesario.
Es el principio que mantiene el contexto ligero y la skill rápida y económica de cargar.
Capas, bajo demanda, ahorro de contexto.
Archivos de apoyo (templates, design systems, tablas) que el SKILL.md indica leer cuando sea necesario.
Es donde está el detalle que haría que el SKILL.md fuera enorme si estuviera inline.
Documentos de apoyo, lectura condicional, modularidad.
Scripts (Python, shell, etc.) que la skill ejecuta en vez de pedirle a Claude que reescriba la lógica cada vez.
El código determinista es más confiable y barato que regenerar la lógica en cada llamada.
Determinismo, reutilización, separar la lógica de la prosa.
Archivos estáticos — fuentes, imágenes, templates HTML, ejemplos — que la salida usa o referencia.
Mantén la skill autocontenida: todo lo que necesita viaja con ella.
Autocontenido, recursos versionados, ejemplos de salida.
El SKILL.md debe contener el flujo y las decisiones; los detalles más complejos van en los archivos de apoyo.
Un SKILL.md inflado consume contexto cada vez que se activa, incluso cuando no se usa el detalle.
Enrutador, no enciclopedia. Señala, no vuelca información.
El patrón de indicarle a Claude que abra un archivo de apoyo solo en condiciones específicas.
Es lo que transforma un conjunto de archivos en una skill que se navega por sí sola.
Condiciones de lectura, tabla de enrutamiento, activación por tarea.
🎯 Descriptions que se activan
La anatomía de una description que se activa en el momento adecuado: activadores, ejemplos, antipatrones y —tan importante como— cuándo NO activar.
Toda buena description tiene dos partes: lo que produce la skill y en qué situaciones debe usarse.
Las descripciones que solo dicen "qué hacen" no le dan a Claude la señal de cuándo activarlas.
Capacidad + condición, acción + contexto.
Palabras y pedidos reales ("crea un itinerario", "/travel") que indican que la skill aplica.
Los disparadores concretos aumentan drásticamente la tasa de activación correcta.
Lenguaje del usuario, sinónimos, comandos de barra.
Incluir casos de uso breves dentro de la propia description para orientar el matching.
Los ejemplos le dan a Claude referencias semánticas que las descripciones abstractas no ofrecen.
Casos de uso, anclas, «úsalo cuando...».
Descripciones vagas, demasiado genéricas o puramente técnicas que no dicen cuándo usar la skill.
Reconocer el antipatrón es la forma más rápida de corregir una skill que no se activa.
Vago, redundante, sin disparador, jerga sin contexto.
Deja claros en la description (y en el cuerpo) los casos en que NO debe usarse la skill.
Los falsos positivos dificultan tanto como los falsos negativos. Los límites evitan ambos.
Alcance negativo, "no lo uses para...", desambiguación.
Ejecutar solicitudes reales y variadas para ver si la skill se activa cuando debe y permanece inactiva cuando no debe.
La description es una hipótesis; solo la prueba confirma. Es un ciclo, no un único intento.
Casos de prueba, falsos positivos/negativos, iteración.
📐 Reglas 2026
Las reglas actuales de la guía de buenas prácticas de skills de Anthropic y de la documentación de Claude Code, los ajustes para los modelos 5.5, una checklist que puedes copiar y el validador para auditar tus skills.
SKILL.md con menos de 500 líneas, referencias enlazadas directamente desde él y un índice al inicio de las referencias con más de 100 líneas.
Una referencia anidada solo se previsualiza: las reglas del final del archivo desaparecen sin aviso.
500 líneas, un nivel de profundidad, sumario.
Cuánto control merece cada paso: instrucción en texto, modelo con margen para variar o script exacto.
Un error costoso requiere un script exacto; una tarea abierta requiere solo la orientación.
Riesgo, fragilidad, "¿y si el agente lo hace de otra manera?".
Qué hace la skill y cuándo usarla, en tercera persona, con hasta 1.024 caracteres; la descripción + when_to_use se recortan a 1.536 en el listado.
El modelo no ve lo que queda fuera del recorte y la skill deja de activarse.
Tercera persona, «cuándo usar», límites de tamaño.
Una lista que el agente copia en la respuesta y va marcando, con una línea para volver, y un ciclo de ejecutar, corregir y repetir.
Una tarea larga sin checklist omite pasos; una salida sin ciclo termina en el primer error.
Checklist, criterio que se cumple o falla, verificador.
Ejecutar la skill con los modelos que la usarán y comprobar si orienta lo suficiente sin explicar de más.
Cada modelo reacciona de manera diferente a la misma instrucción.
¿Haiku orienta? ¿Sonnet es conciso? ¿Opus evita los excesos?
Una línea de instalación para cada paquete, hooks en el frontmatter de la skill y reglas críticas al principio, porque la compactación conserva solo los primeros 5.000 tokens.
Es lo que hace que la skill funcione en la máquina de un colega y en una sesión larga.
Instalación, hook, compactación, modelos 5.5.