SKILL.md: estructura y frontmatter explicados
El archivo que define una Agent Skill, campo por campo: qué lleva el frontmatter, por qué la description decide si tu skill llega a usarse, y cómo estructurar el cuerpo para que el agente lo siga.
Qué es exactamente un SKILL.md
Un SKILL.md es un archivo de texto plano con dos partes: un frontmatter en YAML, delimitado por tres guiones arriba y abajo, y un cuerpo en Markdown. Nada más. No hay código que compilar, ni formato propietario, ni herramienta que instalar para escribirlo: se edita con cualquier editor de texto.
Esa simplicidad es deliberada. El frontmatter le dice al agente qué es la skill y cuándo usarla; el cuerpo son las instrucciones que seguirá cuando decida usarla. El agente lee lo primero siempre y lo segundo solo cuando hace falta, que es lo que permite tener muchas skills instaladas sin saturar el contexto.
El frontmatter: name y description
El frontmatter lleva dos campos obligatorios. "name" es el identificador de la skill: en minúsculas, con guiones y sin espacios, y conviene que coincida con el nombre de la carpeta que la contiene.
"description" es una frase que explica qué hace la skill y, sobre todo, cuándo debe usarse. No es la descripción comercial que lee el comprador: es la instrucción que lee el agente para decidir si esta skill aplica a lo que le acaban de pedir.
Esa distinción es la que más skills arruina. Una description escrita para lucir ("La mejor herramienta para tus contratos") no le dice al agente nada sobre cuándo activarse. Una escrita para el agente ("Úsala cuando el usuario pida revisar, analizar o buscar cláusulas abusivas en un contrato de alquiler de vivienda en España") sí.
Por qué la description decide si tu skill sirve para algo
El agente no lee el cuerpo de todas tus skills antes de responder: eso no cabría en el contexto. Lo que lee es el nombre y la description de cada una, y con eso decide cuál cargar. Si la description no encaja con cómo la gente formula la petición, la skill nunca se activa — y una skill que no se activa es exactamente igual de útil que no tenerla.
La regla práctica: escribe la description con las palabras que aparecerían en la petición real, no con las que usarías en un catálogo. Si tu skill calcula el modelo 130, la description tiene que contener "modelo 130", "trimestral", "autónomo" y "IRPF", porque eso es lo que el usuario va a escribir.
Incluye también el límite: para qué NO es. Una description que dice explícitamente que sirve para contratos de alquiler de vivienda y no para locales comerciales evita que el agente la active en el caso equivocado y devuelva un análisis con la checklist errónea.
El cuerpo: proceso, criterios y formato de salida
El cuerpo es Markdown normal, y las skills que funcionan comparten estructura: el proceso paso a paso, los criterios para decidir en casos dudosos, y el formato exacto que debe tener el resultado. Esos tres bloques son los que convierten conocimiento en algo repetible.
Lo que sobra son las instrucciones genéricas. "Sé profesional", "revisa bien", "usa un tono adecuado": eso el modelo ya lo intenta por su cuenta y ocupa espacio sin aportar. El valor está en lo que el modelo no puede deducir solo — tu checklist, tus umbrales, el orden en que tú haces las cosas, los errores que has visto cometer.
Escríbelo en imperativo y dirigido al agente, no al lector. "Identifica las partes y la duración" funciona mejor que "esta skill identifica las partes y la duración", que es descripción y no instrucción.
Ejemplo comentado
Tres cosas de este ejemplo merecen atención. La description nombra las cuatro formas en que alguien pediría esto y además dice para qué no sirve. El proceso está numerado, así que el resultado es reproducible. Y la última línea del formato de salida obliga al agente a declarar sus suposiciones, que en un cálculo fiscal es la diferencia entre una ayuda y un problema.
SKILL.md
--- name: modelo-130-autonomos description: Calcula y revisa el modelo 130 de IRPF trimestral para autónomos en España. Úsala cuando el usuario mencione modelo 130, pago fraccionado, IRPF trimestral o declaración trimestral de autónomo. No sirve para sociedades ni para el modelo 303 de IVA. --- # Modelo 130 — pago fraccionado de IRPF ## Datos que necesitas antes de calcular Pregunta por lo que falte, no lo supongas: - Ingresos del trimestre y acumulados del año - Gastos deducibles, separando los de difícil justificación - Retenciones ya soportadas en facturas - Resultado de los trimestres anteriores ## Proceso 1. Calcula el rendimiento neto: ingresos menos gastos deducibles. 2. Aplica el porcentaje de gastos de difícil justificación con su límite. 3. Calcula el 20% sobre el rendimiento neto acumulado. 4. Resta lo pagado en trimestres anteriores y las retenciones. 5. Si el resultado es negativo, indícalo como cuota cero a compensar. ## Criterios - Ante una duda de deducibilidad, márcala como "revisar con asesor" en vez de decidir por el usuario. - Nunca redondees al alza sin avisar. ## Formato de salida Tabla con el desglose de cada paso, la cuota resultante en negrita, y una lista de los datos que has tenido que asumir por falta de información.
Cuándo añadir archivos auxiliares
Una skill puede acompañarse de archivos adicionales a los que el cuerpo hace referencia: plantillas, tablas de datos, ejemplos largos o scripts. El agente los consulta cuando el SKILL.md se lo indica, lo que permite mantener el archivo principal corto y cargar el resto solo si hace falta.
Dicho esto, la mayoría de skills útiles caben en un único SKILL.md bien escrito. Añade archivos auxiliares cuando tengas material que consultar de verdad — un baremo, un convenio, una plantilla de documento — y no para trocear instrucciones que cabían juntas.
Preguntas frecuentes sobre SKILL.md
¿El SKILL.md es Markdown normal?
Sí, el cuerpo es Markdown estándar: encabezados, listas, tablas y bloques de código funcionan como esperas. Lo único que no es Markdown es el frontmatter YAML del principio, delimitado por tres guiones arriba y abajo.
¿Qué campos son obligatorios en el frontmatter?
Name y description. El resto de campos que puedas ver en skills de terceros son opcionales y dependen de la herramienta. Si te falta alguno de los dos obligatorios, la skill no se cargará.
¿Escribo la skill en español o en inglés?
En español si va a usarse en español, y muy especialmente la description: tiene que contener las palabras con las que el usuario formulará la petición. Si tus usuarios escriben "revisa este contrato", la description debe decir "revisar contrato" y no "contract review".
¿Cuánto debe ocupar un SKILL.md?
Lo que haga falta para que el proceso sea completo, pero sin relleno. Una skill de una página bien escrita rinde más que cinco páginas de recomendaciones genéricas, porque cada línea que no aporta criterio compite por la atención del agente con las que sí.