SKILL.md explicado: todos los campos del frontmatter y la progressive disclosure
La referencia técnica completa de SKILL.md: todos los campos del frontmatter, la convención de directorios y el modelo de progressive disclosure en tres niveles que mantiene las skills de Claude Code rápidas y eficientes en contexto.
SKILL.md es el contrato completo. Todo lo que el agente sabe sobre cuándo dispararse, qué cargar y qué herramientas puede tocar sale de un solo archivo. Si te equivocas en la estructura, la skill o nunca se dispara o se dispara con todo.
Si nunca has creado una skill, empieza por la guía para crear skills de Claude Code. Ahí se cubre la decisión de crearla o no, el proceso de destilación y cómo se compara la arquitectura con un prompt común. Este artículo es la referencia técnica que está debajo: cada campo del frontmatter, qué hace, cuándo importa, y el modelo de progressive disclosure en tres niveles que mantiene el costo de contexto proporcional a la complejidad de la tarea.
El archivo vive en .agents/skills/<your-skill-name>/SKILL.md. Esa ruta es obligatoria. Agrega references/, scripts/ o assets/ al lado cuando la skill necesite material de apoyo. Todo el comportamiento de la skill está anclado a SKILL.md.
Qué es SKILL.md
SKILL.md es el archivo de entrada de toda skill de Claude Code. Tiene dos partes: un bloque de frontmatter en YAML que controla cómo se descubre, se dispara y se restringe la skill, y un cuerpo en Markdown que es el prompt en sí (la persona, el formato de salida, el mapa de carga, las restricciones). El frontmatter es configuración legible por máquina; el cuerpo es instrucción ejecutable.
La división importa porque las dos partes se cargan en momentos distintos. Los campos name y description están en la capa de listado de skills que Claude lee en cada sesión, antes de que se active cualquier skill. Siempre cuestan contexto. El cuerpo solo se carga cuando la skill se dispara. Los archivos de referencia solo se cargan cuando el cuerpo le indica explícitamente al agente que los lea. Tres niveles, y cada uno cuesta contexto solo cuando se lo gana.
La tabla de frontmatter de abajo cubre todos los campos. El FileTree muestra la convención de directorios. El LayerStack mapea los tres niveles de disclosure. Lee primero el frontmatter: determina qué se carga, cuándo y con qué nivel de capacidad.
Todos los campos del frontmatter
El campo description es el principal mecanismo de disparo — no el nombre, no el slash command. Claude lee las descriptions para decidir qué skill corresponde a lo que pide el usuario. Todo lo demás en el frontmatter configura el entorno de ejecución o acota qué invocaciones califican: permisos, modelo, nivel de esfuerzo, aislamiento de contexto. El mismo interruptor de modelo y esfuerzo por skill, portado al agente Pi, es lo que agrega pi-skill-model-handoff. La tabla de abajo cubre todos los campos que documenta Anthropic.
Referencia del frontmatter de SKILL.md
| Campo | Obligatorio | Valores / Tipo | Notas |
|---|---|---|---|
| name | sí | string | Se convierte en el slash command /name. Minúsculas, guiones. También es la coordenada de activación: cuanto más específico el nombre, más denso el clúster del modelo. |
| description | sí | string | Principal mecanismo de disparo. Junto con when_to_use, tiene un tope de ~1536 caracteres en el listado. Escríbela para que coincida con la intención del usuario, no para resumir la skill. Mejor que peque de insistente. |
| when_to_use | no | string | Complementa la description con escenarios de activación explícitos. Comparte el presupuesto de ~1536 caracteres. Úsalo para edge cases y condiciones específicas que la description no deja ver. |
| argument-hint | no | string | Se muestra en el autocompletado del slash command. Ej.: 'offer to evaluate' o 'PR to review'. Mantiene la interfaz autodocumentada. |
| arguments | no | object | Definiciones tipadas de parámetros para invocación estructurada. Útil cuando los argumentos controlan bifurcaciones dentro del cuerpo, ej.: un switch mode: quick | deep. |
| user-invocable | no | boolean | Por defecto true. Ponlo en false para que la skill sea solo del modelo: el agente puede invocarla como subpaso, pero no aparece en el menú de slash commands del usuario. |
| disable-model-invocation | no | boolean | Impide que el modelo invoque la skill por su cuenta. Combínalo con user-invocable: false para control totalmente manual. La skill solo se dispara cuando el usuario la llama explícitamente. |
| allowed-tools | no | list | Allowlist de las herramientas que puede usar esta skill. Sobrescribe el valor por defecto de la sesión. Si lo omites, hereda todas las herramientas de la sesión, lo que suele ser demasiado permisivo para una skill especializada. |
| disallowed-tools | no | list | Blocklist de herramientas específicas. Úsalo para bloquear Bash, Edit o Write en una skill que solo debería leer. Convierte un disparo accidental en un límite duro. |
| model | no | string | Sobrescribe el modelo para esta skill. Corre las skills de consulta rápida en un modelo más chico y rápido. Corre las de análisis profundo en el más capaz. El control de costos va en la config. |
| effort | no | low | medium | high | xhigh | max | Define el nivel de razonamiento. high o xhigh para auditorías de seguridad y análisis complejos; low para formateadores y consultas rápidas. max solo cuando de verdad necesitas el razonamiento más profundo. |
| context | no | fork | Corre la skill en un fork de contexto aislado, separado de la conversación principal. Úsalo para skills que hacen bastante trabajo antes de devolver una respuesta. Evita que las sesiones largas consuman el context window de la conversación. |
| agent | no | string | Delega la invocación a un subagent con nombre. Habilita arquitecturas multiagente desde un único SKILL.md como punto de entrada. |
| hooks | no | object | Hooks antes y después de la invocación. Corre scripts de setup, validación del entorno o limpieza alrededor de la ejecución de la skill sin meter esa lógica en el cuerpo. |
| paths | no | list | Restringe el acceso a archivos a directorios específicos. Una skill de code review para un servicio no necesita acceso a todo el monorepo. Acótalo tanto como la tarea lo permita. |
| shell | no | boolean | Habilita o deshabilita explícitamente el acceso a comandos de shell para esta skill. Deja el permiso visible en el archivo en lugar de heredarlo del contexto de la sesión. |
Aquí tienes un bloque de frontmatter funcional para una skill de revisión de seguridad. Fíjate en la lista disallowed-tools: una skill de review que no puede escribir archivos no puede aplicar un fix por accidente, lo que vuelve explícito el contrato en lugar de depender del criterio del modelo:
---
name: security-reviewer
description: >
Reviews code for security vulnerabilities, injection risks, authentication
gaps, and secrets exposure. Applies OWASP Top 10 as the base checklist.
INVOKE for any PR touching auth, database queries, file I/O, API endpoints,
or environment variable handling. Do not invoke for unrelated refactors.
REQUIRED: read references/00-checklist.md before responding.
when_to_use: >
Invoke for PRs touching authentication, authorization, input sanitization,
secrets handling, or third-party dependency additions. Also useful before
any deployment that changes the attack surface.
effort: high
allowed-tools: [Read, Grep, Glob]
disallowed-tools: [Bash, Edit, Write]
context: fork
---La description pone el patrón de disparo al principio (“auth, database queries, file I/O, API endpoints”), así el modelo ve la señal de coincidencia de inmediato, antes de que la description se trunque.
Estructura de directorios
Un directorio de skill tiene un archivo obligatorio y tres subdirectorios opcionales. Todas las skills siguen la misma estructura, lo que significa que las herramientas, los scripts de CI y otras skills pueden razonar sobre la organización sin inspeccionar cada archivo uno por uno.
Estructura de directorios de una skill
- security-reviewer/raíz de la skill
- SKILL.mdobligatorio// frontmatter + cuerpo del prompt + mapa de carga
- references/// se carga bajo demanda según las instrucciones del cuerpo de SKILL.md
- 00-checklist.md// siempre se carga: checklist de decisión
- 01-owasp-top10.md// referencia del framework
- 02-examples.md// ejemplos resueltos y antipatrones
- scripts/// código ejecutable que la skill puede correr
- validate.sh// verificación previa del entorno
- assets/// archivos que se usan en la salida: templates, íconos, datos
- report-template.md// esqueleto de la salida
El directorio references/ es donde está la mayor parte del apalancamiento. Una skill sin referencias responde solo con los pesos del modelo. Es lo mismo que no tener skill. El cuerpo de SKILL.md le dice al agente qué archivos leer y cuándo. Nada en references/ se carga automáticamente. Esa restricción es la arquitectura, no una limitación.
Progressive disclosure: tres niveles
La progressive disclosure mantiene las skills rápidas. El modelo carga solo lo que exige la tarea actual. Cada nivel agrega contexto solo cuando se activa.
Progressive disclosure: tres niveles
- L1
Metadatos: siempre en contexto
name y description (y when_to_use) están en el listado de skills que el modelo lee en cada sesión, antes de que se active cualquier skill. Esta es la capa de disparo: unas 100 palabras por skill, siempre en contexto. Cada palabra cuesta. Pon la señal al frente: la coincidencia más fuerte con la intención del usuario va en la primera oración, no en la tercera.
name: alex-hormozi-offer-design description: > Evaluates offers, pricing, guarantees, and value stacks using Hormozi's frameworks (Value Equation, Grand Slam Offer, RAISE). INVOKE for any question about pricing strategy, risk reversal, guarantee design, or offer testing. Do not use for brand/content work.
- L2
Cuerpo de la skill: se carga al dispararse
El cuerpo en Markdown de SKILL.md se carga cuando la skill se activa. Es el prompt principal: persona, formato de salida, restricciones y el mapa de carga que dirige al agente hacia las referencias. Mantén el cuerpo por debajo de ~500 líneas. Si crece más, el cuerpo se convirtió en una referencia. Mueve el excedente a references/ y agrega una instrucción de carga.
- L3
Archivos de referencia: se cargan según haga falta
Los archivos en references/ solo se cargan cuando el cuerpo de SKILL.md le indica explícitamente al agente que los lea. El modelo decide. Nada se carga solo. Este es el punto crítico: sin un mapa de carga explícito en el cuerpo, el agente se salta las referencias por completo y responde con los pesos del entrenamiento. Tu conocimiento destilado se queda sin leer.
El mapa de carga conecta el cuerpo de la skill con los archivos de referencia y elimina la ambigüedad que deja al modelo tomar atajos:
Mapa de carga de SKILL.md
| Tipo de pregunta | Cargar este archivo |
|---|---|
| Cualquier evaluación de oferta | references/00-canon.md (siempre) |
| Precio o reversión de riesgo | references/04-pricing.md |
| Construcción de la oferta | references/02-grand-slam-offer.md |
| Objeciones o tasa de cierre | references/07-closing-and-sales.md |
| Veredicto final | references/11-decision-checklist.md |
Lo explícito le gana a lo cortés. “Consulta las referencias” es una sugerencia. Una tabla que dice “pregunta de precio carga pricing.md” es una instrucción. El modelo sigue la segunda con mucha más consistencia que la primera.
Cómo escribir descriptions que se disparen
Las descriptions son el principal mecanismo de disparo — no el nombre, no el slash command. Claude lee las descriptions para decidir qué skill corresponde a lo que pide el usuario. Una description que suena a resumen de marketing está rota en la práctica. Describe la skill con precisión y no coincide con ninguna intención real del usuario.
Las descriptions que se disparan poco suenan a elevator pitch: “Una skill para revisar la seguridad del código.” Las que se disparan se parecen al patrón que deben atrapar: “Revisa pull requests en busca de vulnerabilidades de inyección, fallas de autenticación, exposición de secrets y control de acceso roto. Invócala para cualquier PR que toque auth, queries a la base de datos, variables de entorno o nuevas dependencias de terceros.”
La diferencia está en la especificidad de la intención, no en el largo. La segunda description coincide con lo que un dev escribiría o diría cuando necesita la skill (el vocabulario del problema, no el de la solución).
La propia guía de Anthropic dice que las descriptions sean “un poco insistentes”, porque en la práctica las skills tienden a dispararse menos de lo que deberían. El costo de un falso positivo (la skill se dispara cuando no debía) es menor que el de quedarse corto de forma sistemática, cuando la skill nunca se dispara. Inclínate por especificar de más, no por resumir.
Los archivos de referencia de más de 300 líneas necesitan índice
Cualquier archivo de referencia de más de 300 líneas necesita un índice al principio. Es estructural, no estético.
Cuando el agente carga un archivo de referencia, lo lee desde arriba. Un archivo largo sin índice obliga al modelo a recorrer la estructura antes de encontrar la sección relevante: tokens desperdiciados y menos precisión. Un índice al principio le permite al agente saltar directo al ancla que necesita la tarea, lo que importa sobre todo en referencias multidominio que atienden varios tipos de pregunta.
La regla también delata un problema de diseño: si un solo archivo de referencia pasa de 300 líneas y no tiene capítulos obvios, probablemente cubre demasiados dominios de decisión. Divídelo. Mi skill de evaluación de ofertas tiene 13 archivos de referencia, la mayoría de menos de 100 líneas, divididos por decisión: precio, garantías, value equation, cierre, retención. El archivo canon (que se carga en cada invocación) tiene índice. Todo lo demás es lo bastante corto para leerse completo sin uno.
Diseña juntos el mapa de carga en SKILL.md y la estructura de references/. Si el cuerpo dice “para preguntas de precio, carga references/04-pricing.md”, ese archivo debe estar lo bastante enfocado para que el agente lo lea completo de una sola pasada. La brevedad en las referencias es una ventaja: mantiene barato el L3.
Para verificar que tu skill se dispara bien y usa las referencias que escribiste, mira la guía para probar skills de Claude Code. Para estudiar estructuras reales de skills (incluida la skill alex-hormozi-offer-design, con 13 referencias divididas por decisión), mira los ejemplos de skills de Claude. Si todavía estás decidiendo si vale la pena crear una skill, empieza por la guía para crear skills de Claude Code.
¿Cuál es el SKILL.md mínimo viable?
name y description son los únicos campos obligatorios. Una skill con solo esos dos se dispara y se ejecuta. Sin allowed-tools ni disallowed-tools, hereda todo el conjunto de permisos de la sesión, lo que suele ser demasiado permisivo para una skill especializada.
El mínimo práctico para producción: name, description, effort y al menos uno entre allowed-tools y disallowed-tools, para que los permisos sean explícitos en lugar de heredados.
¿Qué dispara la skill: description o when_to_use?
Los dos aportan. El modelo lee ambos al recorrer el listado de skills para encontrar la que corresponde al pedido actual. Comparten un presupuesto combinado de unos 1536 caracteres.
Usa description para el patrón de intención principal (el vocabulario del problema que resuelve la skill). Usa when_to_use para escenarios específicos y edge cases que la description no deja ver.
¿Los archivos de referencia se cargan automáticamente cuando se activa la skill?
No. Nada en references/ se carga automáticamente.
El cuerpo de SKILL.md se carga al activarse. Los archivos de referencia solo se cargan cuando las instrucciones del cuerpo le dicen al agente que lea un archivo específico. Sin un mapa de carga explícito en el cuerpo, el agente se salta las referencias y responde con los pesos del entrenamiento. Tu conocimiento destilado queda fuera de alcance.
¿Qué hace context: fork?
Corre la skill en un contexto aislado, separado de la conversación principal. Así las sesiones largas de la skill (análisis profundo, investigación en varios pasos, carga extensa de referencias) no consumen el context window de la conversación que la invocó.
Úsalo para skills que hacen bastante trabajo antes de devolver una respuesta. Para consultas rápidas y formateadores, el overhead no vale la pena.
¿effort: max debería ser el valor por defecto?
No. El effort escala el tiempo de razonamiento y el costo. Ponlo en lo que la tarea realmente pide: low para consultas rápidas y formateadores, high para auditorías de seguridad y análisis complejos, max solo cuando de verdad necesitas el razonamiento más profundo.
effort: max en una skill simple de formateo desperdicia cómputo. effort: low en una auditoría de seguridad va a dejar pasar cosas. Ajusta el effort al peso de la decisión, no a las ganas de ir a lo seguro.
¿Una skill puede invocar a otra skill?
Sí: mediante el campo agent o incluyendo instrucciones de invocación en el cuerpo. Una skill enrutadora puede delegar en sub-skills especializadas según el tipo de entrada.
La composición ocurre en la capa de orquestación: una skill le pasa el turno a otra, devuelve su salida y la siguiente skill la toma. Dos skills no corren al mismo tiempo dentro de un único cuerpo de SKILL.md.
¿Qué tan largo debería ser el cuerpo de SKILL.md?
Menos de 500 líneas. Si el cuerpo pasa de eso, se convirtió en una referencia. Mueve el excedente a references/ y agrega una instrucción de carga que apunte ahí.
El cuerpo es el enrutador y el prompt. Las referencias son el conocimiento. Mantenerlos separados mantiene rápida la activación: el cuerpo completo se carga en cada invocación, así que cada línea ahí cuesta contexto en cada llamada.
¿Dónde vive el directorio de la skill?
En .agents/skills/<your-skill-name>/. El archivo SKILL.md es el punto de entrada obligatorio en esa ruta. Los subdirectorios (references/, scripts/, assets/) son opcionales y siguen la convención documentada en este artículo.
La ruta consistente permite que otras herramientas, pipelines de CI y skills descubran y entiendan tu biblioteca de skills sin leer cada archivo.
La newsletter
Don’t Code, Specify. Cada semana, agentes de IA en producción de verdad. Sin hype: lo que funcionó y lo que se rompió.
Suscríbete en Substack (se abre en una pestaña nueva)