📄 El interior de SKILL.md
La estructura completa del archivo: frontmatter YAML, los campos name y description, el cuerpo en Markdown y la organización de carpetas que hace que una skill sea profesional.
Todo SKILL.md tiene dos partes: un bloque de frontmatter YAML delimitado por --- en la parte superior, seguido del cuerpo en Markdown con las instrucciones.
Es el esqueleto de toda skill. Si la estructura es incorrecta, el agente ni siquiera reconoce el archivo.
delimitadores --- · YAML · cuerpo Markdown · campos obligatorios
El identificador de la skill — siempre en kebab-case minúsculo (p. ej.: frontend-design), único dentro del agente.
Es la forma en que se hace referencia a la skill y se instala. Un nombre ambiguo o con mayúsculas o espacios impide la activación.
kebab-case · lowercase · unicidad · igual al nombre de la carpeta
La frase que el agente lee para decidir si activa la skill. Debe decir qué hace y exactamente cuándo usarla.
Es el campo que más influye en la activación. Una description vaga = una skill que nunca se activa.
activador · QUÉ + CUÁNDO · ejemplos de uso · pushy
Las instrucciones de verdad. Escritas en modo imperativo, explican el PORQUÉ y muestran patrones de salida y ejemplos.
Es donde se define el comportamiento real. Un texto extenso y sin enfoque diluye la skill.
imperativo · explicar por qué · ejemplos · sin MUSTs gritados
Carpetas junto al SKILL.md: scripts/ para código determinista, references/ para documentación bajo demanda y assets/ para plantillas.
Organizar los recursos mantiene el SKILL.md conciso y permite cargar solo lo necesario.
scripts/ · references/ · assets/ · recursos bundled
Comparar un SKILL.md de 5 líneas con el frontmatter real de la skill frontend-design de Anthropic.
Ver un ejemplo de producción muestra el nivel de detalle que incluye una description ganadora.
ejemplo mínimo · frontmatter real · frontend-design · 488k instalaciones
🎚️ Divulgación progresiva y una description que activa
Los 3 niveles de carga de una skill, cómo escribir la description que se activa en el momento adecuado y cómo organizar el contenido por dominio.
La skill se carga por capas: metadata siempre presente, cuerpo cuando se activa, recursos bajo demanda.
Entender las capas es lo que permite escribir skills grandes sin inflar el contexto.
nivel 1 metadata · nivel 2 cuerpo · nivel 3 recursos · contexto
Solo name + description (~100 palabras) permanecen cargados todo el tiempo en el contexto del agente.
Es el único nivel que siempre está presente; por eso la description debe soportar todo el peso de la activación.
~100 palabras · siempre cargadas · costo de contexto
El cuerpo en Markdown (se recomienda que tenga menos de 500 líneas) solo entra en el contexto cuando se activa la skill.
Mantener el cuerpo conciso mejora la adherencia del agente a las instrucciones.
<500 líneas · se carga al activarse · enfoque
Archivos en scripts/, references/ y assets/ — tamaño ilimitado, que se leen o ejecutan solo cuando es necesario.
Los scripts se ejecutan sin cargar el código en el contexto: así es como las skills se vuelven potentes y económicas.
ilimitado · bajo demanda · ejecución determinista
El arte de escribir la description: qué hace, cuándo usarla y activadores explícitos, siendo un poco insistente.
Claude tiende a activar menos skills de las necesarias; una description más directa corrige esto.
insistente · activación insuficiente · qué + cuándo + activadores
Divide las referencias por dominio (aws.md, gcp.md, azure.md) y agrega un índice en los archivos con más de 300 líneas.
El agente lee solo el archivo relevante, ahorra contexto y mantiene la precisión.
división por dominio · lectura selectiva · tabla de contenido
⭐ Las mejores anatomías para imitar
Analiza el SKILL.md de las skills con más instalaciones —frontend-design, skill-creator, supabase, microsoft-foundry y azure-ai— y descubre exactamente qué copiar de cada frontmatter y estructura.
Aprender a escribir SKILL.md analizando en detalle las más instaladas del ecosistema y extrayendo sus patrones.
Cada skill campeona resuelve una disyuntiva diferente; juntas forman un catálogo de moldes listos para usar.
copia honesta · forma vs. contenido · trade-offs · catálogo de patrones
La skill más instalada de Anthropic; description que dice qué hace, cuándo usarla (con ejemplos) y cuál es su diferencial, sin carpetas.
Es el arquetipo más común: una sola competencia, cuerpo único, fácil de mantener.
verbo de acción · ejemplos como activadores · diferenciador final · cero carpetas
El ejemplo canónico de una skill grande organizada en carpetas (~33KB), con referencias desde el cuerpo hacia los recursos.
Es el molde para cuando hay código reutilizable, documentación extensa y plantillas de salida.
scripts/ · references/ · assets/ · enlaces en el cuerpo
Description agresiva que empieza con "Use when doing ANY task" y enumera Triggers por categoría.
Es el patrón cuando la skill es la puerta de entrada a toda una plataforma y debe activarse desde cualquier punto.
Triggers: categorizados · ANY asertivo · metadata · Core Principles
Skills enormes que usan USE FOR / DO NOT USE FOR en la description y una tabla de sub-skills en el cuerpo.
Es la forma de escalar una skill operativa sin activaciones incorrectas ni pérdida de control.
USE FOR / DO NOT USE FOR · tabla de sub-skills · pre-execution
Un decisor rápido: cada anatomía responde a una pregunta sobre tu skill.
Saber elegir la plantilla adecuada evita rehacer la estructura después.
competencia única · varios archivos · guardián · gran capacidad operativa
🛠️ Cómo crear: armar un SKILL.md desde cero
De la carpeta vacía al archivo listo: frontmatter con name y description como disparador, cuerpo imperativo con When to Use y Steps, cuándo crear cada carpeta y una plantilla completa para copiar.
El recorrido de seis paradas para crearla: intent, frontmatter, cuerpo, carpetas, empaquetar, iterar.
Tener el mapa evita empezar demasiado grande; un SKILL.md válido nace solo con frontmatter + cuerpo.
seis etapas · empezar en pequeño · carpetas opcionales
El identificador de la skill en kebab-case minúsculo, sin espacios ni mayúsculas, igual al nombre de la carpeta.
La discrepancia entre name y la carpeta impide cargar la skill.
kebab-case · lowercase · name = carpeta · sin sufijos
La fórmula de la description: qué hace, cuándo usarla y activadores concretos, en unas ~100 palabras persuasivas.
Es el único texto que siempre se carga y el que hace que la skill se active; Claude tiende a activarla menos de lo debido por defecto.
fórmula · ~100 palabras · pushy · palabras clave reales
El cuerpo en Markdown en modo imperativo, con título, When to Use, pasos numerados y Output Format.
Es donde se define el comportamiento real; explicar el porqué funciona mejor que gritar MUST en mayúsculas.
imperativo · When to Use · Steps · Output Format
El criterio para crear cada directorio: determinístico → scripts/, documentación extensa → references/, salida → assets/.
Las carpetas surgen de la necesidad, no de la estética; cada archivo necesita un enlace en el cuerpo.
scripts/ determinista · references/ bajo demanda · assets/ salida
Un SKILL.md completo y listo: frontmatter, When to Use, Steps, Output Format y referencias a las carpetas.
Copiarla, cambiar los nombres e instalarla es el camino más rápido para crear tu primera skill.
template listo · instalable · base para iterar
🚀 Consejos avanzados: múltiples archivos y enrutamiento
Progressive disclosure de verdad: references/ por dominio leído selectivamente, scripts/ que se ejecutan sin contexto, índices en archivos largos, SKILL.md con menos de 500 líneas y assets/ bien usados.
Poner en práctica los 3 niveles: el SKILL.md se convierte en un menú y cada archivo se carga solo cuando se elige esa ruta.
Es lo que permite que las skills cubran decenas de servicios sin saturar el contexto.
menú · rutas · carga selectiva · ahorro de contexto
Organiza las referencias por variante y deja que el cuerpo indique cuál usar; el agente lee solo el archivo pertinente.
Tres archivos de 300 líneas ahorran un 66% de contexto frente a uno de 900 y facilitan el mantenimiento.
organización por dominio · tabla de enrutamiento · lectura selectiva
Las tareas deterministas se convierten en scripts que se ejecutan y devuelven solo el resultado; el código nunca entra en el contexto.
Más confiable y económico que instruir al agente para que razone paso a paso.
determinista · ejecución sin contexto · extracción de helper repetido
Agregar una tabla de contenido al inicio de cada archivo de referencia de más de 300 líneas.
El agente va directamente a la sección correcta sin releer todo el archivo; si sigue siendo grande, divídelo.
índice al inicio · anclas · división por subtema
Mantén el cuerpo por debajo de 500 líneas trasladando los detalles a references/ y dejando indicaciones claras.
El cuerpo entra completo en el contexto cada vez que se activa la skill; la jerarquía hace que el costo se pague solo cuando hace falta.
límite de 500 líneas · mover detalles · pointers de "cuándo leer"
assets/ contiene plantillas, fuentes e íconos completos en el output, distinto de references/ (que se lee).
Cierra la checklist de lo que distingue una skill de juguete de una como azure-ai o supabase.
assets completos · scripts vs references vs assets · checklist final
Mapa de la ruta
Dos delimitadores y todo cambia. Analiza el frontmatter línea por línea.
3 niveles, contexto de bajo costo y la description que se activa en el momento justo.
Analiza las skills con más instalaciones y toma lo que funciona de cada frontmatter.
De la carpeta vacía a la plantilla lista para copiar e instalar.
Progressive disclosure de verdad, scripts sin contexto y pointers.