Validador de SKILL.md para el formato Agent Skills

Un archivo SKILL.md es el corazón de una habilidad para agentes de inteligencia artificial como Claude Code. Imagina que es una ficha técnica que le dice al agente: "Soy una herramienta que hace X, úsame cuando necesites Y". El formato es sencillo: una carpeta con un archivo llamado SKILL.md, que combina un bloque YAML en la parte superior (llamado frontmatter) y instrucciones en Markdown debajo.

El agente lee primero el frontmatter para decidir si la habilidad es relevante para la tarea. Si el nombre y la descripción coinciden con lo que busca, carga el cuerpo del archivo para ejecutar las instrucciones. Por ejemplo, una habilidad para resumir contratos legales en español podría tener un nombre como resumir-contrato-es y una descripción como "Resume contratos en español, ideal para cláusulas de arrendamiento o compraventa".

Este formato no es exclusivo de Claude Code: el estándar [Agent Skills](https://agentskills.io) permite que la misma habilidad funcione en diferentes plataformas. Sin embargo, hay un detalle importante: algunos campos como model o hooks solo los interpreta Claude Code, mientras que otros agentes los ignoran. Por eso, si quieres que tu habilidad sea portátil, es clave seguir las reglas del estándar y validar el archivo con el Validador de SKILL.md antes de publicarlo.

Un error común es pensar que el cuerpo del archivo es lo más importante. En realidad, si la descripción no es clara o el nombre no sigue las reglas (máximo 64 caracteres, solo minúsculas y guiones simples), el agente ni siquiera intentará cargar la habilidad. Por eso, dedicar unos minutos a revisar el frontmatter puede ahorrarte horas de depuración.

El frontmatter de un archivo SKILL.md es como el DNI de la habilidad: si no está bien estructurado, el agente no la reconocerá. Estos son los campos que el Validador de SKILL.md revisa, con sus reglas y límites:

El campo name es especialmente crítico: debe coincidir exactamente con el nombre de la carpeta que contiene el archivo (si la carpeta se llama generar-factura-es, el name debe ser generar-factura-es). Un error frecuente es usar guiones bajos (_) o mayúsculas, lo que invalida la habilidad.

La description es el campo más subestimado. No es solo una explicación técnica, sino el "gancho" que hace que el agente elija tu habilidad. Por ejemplo, una descripción débil como "Genera facturas" no dice cuándo usarla. Una versión mejorada sería: "Genera facturas electrónicas en formato PDF para autónomos en España, compatible con la normativa de la AEAT". El validador te avisará si la descripción es demasiado corta (menos de 60 caracteres) o si falta la parte de cuándo usar.

Los campos opcionales como compatibility son útiles para habilidades que dependen de características específicas de un agente. Por ejemplo, si tu habilidad usa funciones avanzadas de Claude Code, puedes especificar "Claude 3.5 Sonnet o superior". Eso evita que otros agentes intenten ejecutarla y fallen.

La descripción de tu habilidad en SKILL.md es como el título de un anuncio en Google: si no capta la atención del agente en los primeros segundos, la ignorará. El Validador de SKILL.md te avisará si tu descripción es demasiado corta (menos de 60 caracteres) o si no incluye la frase clave "cuándo usar". Pero más allá de cumplir con las reglas, hay patrones que funcionan mejor que otros.

Ejemplos de descripciones débiles (y cómo mejorarlas): - ❌ "Traductor de textos" → ✅ "Traduce textos del español al inglés o francés, ideal para correos formales o documentos técnicos con terminología especializada". - ❌ "Generador de contratos" → ✅ "Crea contratos de arrendamiento para viviendas en España, con cláusulas adaptadas a la LAU y opciones para incluir garantías adicionales". - ❌ "Resumidor de noticias" → ✅ "Resume noticias en español de fuentes como El País o El Mundo, destacando los puntos clave en menos de 200 palabras".

Observa que las descripciones mejoradas incluyen: 1. Qué hace la habilidad (traduce, genera, resume). 2. Para qué contexto (correos formales, contratos de arrendamiento, noticias). 3. Detalles específicos (idiomas, normativas como la LAU, fuentes de noticias).

Un error común es asumir que el agente entenderá el contexto. Por ejemplo, una descripción como "Calcula el IVA" es ambigua: ¿para qué país? ¿Qué tipo de IVA (general, reducido, superreducido)? Una versión más clara sería: "Calcula el IVA en España para facturas de autónomos, con opciones para tipos del 21 %, 10 % y 4 %".

Si tu descripción supera los 1024 caracteres, el validador marcará un error. En ese caso, puedes: - Mover detalles técnicos al cuerpo del archivo (en la sección de instrucciones). - Usar la carpeta references/ para incluir ejemplos largos o plantillas. - Simplificar el lenguaje, evitando repeticiones.

Recuerda: el agente no lee el cuerpo de la habilidad hasta que decide usarla. Por eso, la descripción debe ser lo suficientemente clara para que, incluso sin contexto adicional, el agente sepa si es la herramienta adecuada para la tarea.

El cuerpo de un archivo SKILL.md no es un manual de instrucciones, sino una guía concisa para que el agente ejecute la tarea. El estándar [Agent Skills](https://agentskills.io) recomienda mantenerlo por debajo de 500 líneas y unos 5000 tokens (aproximadamente 20.000 caracteres, ya que el validador estima 4 caracteres por token). ¿Por qué estos límites?

1. Rendimiento: Los agentes procesan múltiples habilidades en paralelo. Un archivo demasiado largo ralentiza la selección y ejecución.
2. Legibilidad: Un cuerpo bien estructurado con encabezados (#, ##) permite que el agente identifique rápidamente las secciones relevantes.
3. Mantenimiento: Habilidades con cuerpos extensos suelen incluir detalles que podrían moverse a archivos externos (en la carpeta references/).

Estructura recomendada: 1. Introducción breve (1-2 párrafos): Explica el propósito de la habilidad y sus casos de uso principales. 2. Instrucciones paso a paso: Usa listas numeradas o viñetas para tareas secuenciales. Ejemplo:

   1. Analiza el texto de entrada para identificar el tipo de documento (factura, contrato, etc.).
   2. Extrae los datos clave: fecha, importe, NIF del emisor y receptor.
   3. Valida los datos según la normativa vigente (ej: formato del NIF en España).

1. Ejemplos: Incluye ejemplos de entrada y salida, pero evita repetir información que ya está en references/.
2. Notas técnicas: Detalles como formatos de archivo soportados o limitaciones.

Errores comunes que detecta el validador: - Placeholders: Frases como "TODO: completar esta sección" o "Lorem ipsum" activan una advertencia. Si la habilidad está en desarrollo, usa el campo metadata para indicar su estado (ej: status: draft). - Enlaces absolutos o anidados: Los enlaces a archivos deben ser relativos y de un solo nivel (ej: references/plantilla.pdf, no ../../docs/plantilla.pdf). - Cuerpo demasiado corto: Menos de 20 palabras suele indicar que la habilidad está incompleta.

Consejo para habilidades complejas: Si tu habilidad requiere muchas instrucciones (ej: un generador de informes fiscales para autónomos en España), mueve los detalles a archivos externos en references/. Por ejemplo: - references/ejemplo-entrada.txt: Ejemplo de datos de entrada. - references/plantilla-salida.xlsx: Plantilla para el informe generado. - references/normativa.md: Extractos de la ley que aplica la habilidad.

El validador no revisa si los archivos enlazados existen, pero sí te avisará si los enlaces no siguen las reglas de formato. Recuerda: el objetivo es que el agente pueda ejecutar la habilidad sin depender de información externa, pero sin saturar el archivo principal.

El formato SKILL.md está diseñado para ser portable: una misma habilidad debería funcionar en diferentes agentes que sigan el estándar [Agent Skills](https://agentskills.io). Sin embargo, plataformas como Claude Code añaden campos adicionales que solo ellas interpretan. El Validador de SKILL.md te ayuda a distinguir entre lo que es parte del estándar y lo que son extensiones específicas.

Campos del estándar (portables): - name, description, license, compatibility: Obligatorios o recomendados por el estándar. Todos los agentes los leen. - allowed-tools: Experimental. El estándar sugiere usarlo como una cadena separada por espacios (ej: allowed-tools: web_search python), no como una lista YAML. - metadata: Objeto YAML para campos no estándar. Si tu habilidad necesita campos específicos de Claude Code (como model o hooks), debes colocarlos aquí.

Extensiones de Claude Code (no portables): - model: Especifica qué modelo de Claude usar (ej: model: claude-3-5-sonnet). Otros agentes lo ignorarán. - hooks: Permite ejecutar código antes o después de la habilidad. Solo funciona en Claude Code. - temperature, max_tokens: Parámetros de generación de texto. No son parte del estándar.

¿Qué pasa si mezclas campos? El validador no marcará un error si incluyes extensiones de Claude Code, pero sí te mostrará una nota para recordarte que esos campos no son portables. Por ejemplo:

name: generar-factura-es
description: Genera facturas electrónicas para autónomos en España
license: MIT
model: claude-3-5-sonnet  # Nota: solo Claude Code lo lee
metadata:
  hooks:
    pre: validar_datos.py  # Nota: solo Claude Code lo ejecuta

Recomendaciones para mantener la portabilidad: 1. *Usa metadata para extensiones: Si tu habilidad depende de campos específicos de Claude Code, colócalos bajo metadata para que otros agentes no fallen al leerlos. 2. Documenta las dependencias: En el campo compatibility, especifica si la habilidad requiere características de Claude Code (ej: compatibility: Claude 3.5 Sonnet o superior). 3. Evita listas YAML en allowed-tools: El estándar recomienda una cadena separada por espacios. El validador te avisará si usas una lista. 4. Prueba en diferentes agentes*: Si publicas tu habilidad en un repositorio público, indica en qué plataformas ha sido probada.

Ejemplo de habilidad portable:

name: resumir-contrato-es
description: Resume contratos en español, destacando cláusulas clave como penalizaciones o plazos de rescisión
license: MIT
compatibility: Cualquier agente que soporte el estándar Agent Skills
metadata:
  model: claude-3-5-sonnet  # Solo Claude Code lo usa
  temperature: 0.3          # Solo Claude Code lo usa

Recuerda: el objetivo del estándar es que las habilidades sean reutilizables. Si tu habilidad solo funciona en Claude Code, está bien, pero debes dejarlo claro en la documentación para evitar confusiones a otros desarrolladores.

El Validador de SKILL.md analiza tu archivo y genera un informe con tres tipos de hallazgos: errores, advertencias y notas. Cada uno tiene un significado distinto y requiere una acción diferente.

1. Errores (rojo): Son violaciones del estándar que impiden que el agente cargue la habilidad. Si hay al menos un error, el archivo no es válido. Ejemplos comunes: - Frontmatter no válido: Causado por errores de sintaxis en YAML (ej: dos puntos sin comillas, tabulaciones en lugar de espacios, bloques no cerrados). - Campo name faltante o inválido: El nombre debe tener máximo 64 caracteres, solo minúsculas, dígitos y guiones simples, y coincidir con el nombre de la carpeta (si se proporciona). - Campo description faltante o demasiado largo: La descripción es obligatoria y no puede superar 1024 caracteres. - Campo compatibility demasiado largo: Máximo 500 caracteres.

2. Advertencias (amarillo): Son sugerencias del estándar que, si se ignoran, pueden afectar el rendimiento o la portabilidad de la habilidad. El archivo sigue siendo válido, pero conviene revisarlas. Ejemplos: - Description demasiado corta: Menos de 60 caracteres suele indicar que falta contexto sobre cuándo usar la habilidad. - Allowed-tools como lista YAML: El estándar recomienda una cadena separada por espacios. - Cuerpo demasiado largo: Más de 500 líneas o 5000 tokens estimados (unos 20.000 caracteres). - Enlaces absolutos o anidados: Los enlaces a archivos deben ser relativos y de un solo nivel (ej: references/plantilla.pdf). - Placeholders como TODO o Lorem ipsum: Indican que la habilidad está incompleta.

3. Notas (azul): Son observaciones sobre campos no estándar o extensiones específicas. No afectan la validez del archivo, pero ayudan a entender su comportamiento. Ejemplos: - Campos solo para Claude Code: Como model, hooks o temperature. Otros agentes los ignorarán. - Allowed-tools experimental: Este campo está en fase de prueba en el estándar. - Falta la frase "cuándo usar": La descripción debería incluir el contexto de uso (ej: "ideal para contratos de arrendamiento en España").

Estructura del informe: El validador muestra primero un veredicto (Válido o No válido), seguido de estadísticas del archivo (líneas, caracteres, tokens estimados) y una tabla con los hallazgos. Cada fila incluye: - Tipo: Error, advertencia o nota. - Campo: El campo afectado (ej: name, description). - Mensaje: Explicación del problema y cómo solucionarlo. - Línea: Número de línea donde se detectó el problema (útil para depurar).

¿Qué NO revisa el validador? - Existencia de archivos enlazados: No verifica si los archivos en references/ o los enlaces relativos existen. - Calidad de las instrucciones: No evalúa si el cuerpo del archivo es claro o útil, solo su formato y tamaño. - Contenido de los campos: Por ejemplo, no valida si la licencia es una licencia real (ej: MIT vs Licencia XYZ).

Consejos para usar el informe: 1. Empieza por los errores: Si hay errores, corrígelos primero. Sin ellos, el archivo no es válido. 2. Exporta los hallazgos: Puedes descargar la tabla como CSV o imagen para revisarla después. 3. No ignores las advertencias: Aunque el archivo sea válido, una descripción vaga o un cuerpo demasiado largo pueden hacer que el agente ignore tu habilidad. 4. Usa las notas para mejorar: Si ves una nota sobre campos específicos de Claude Code, considera moverlos a metadata para mantener la portabilidad.

Ejemplo de flujo de trabajo: 1. Pega tu archivo SKILL.md en el validador. 2. Si hay errores, corrígelos y vuelve a validar. 3. Revisa las advertencias y ajusta lo necesario (ej: acorta la descripción o mueve detalles a references/). 4. Toma nota de las observaciones sobre portabilidad (ej: campos de Claude Code). 5. Exporta el informe para documentar los cambios.

Recuerda: el validador es una herramienta de formato, no un juez de calidad. Una habilidad válida puede ser inútil si las instrucciones son confusas, pero una habilidad inválida ni siquiera será cargada por el agente.

Tanto SKILL.md como llms.txt son archivos de texto diseñados para que los agentes de inteligencia artificial los lean y ejecuten tareas, pero cumplen funciones distintas. Elegir entre uno u otro depende del tipo de interacción que quieras habilitar y de la flexibilidad que necesites.

SKILL.md: habilidades específicas con contexto - Propósito: Define una habilidad concreta con instrucciones detalladas. Por ejemplo: generar facturas electrónicas, resumir contratos legales o traducir textos técnicos. - Estructura: Combina YAML (frontmatter) para metadatos y Markdown para instrucciones. El agente lee primero el frontmatter para decidir si la habilidad es relevante. - Ventajas: - Permite incluir ejemplos, plantillas y referencias externas (en la carpeta references/). - Es portable: el estándar [Agent Skills](https://agentskills.io) permite que funcione en diferentes plataformas. - Ideal para tareas complejas que requieren múltiples pasos (ej: validar un NIF español y generar una factura). - Limitaciones: - Requiere seguir reglas estrictas de formato (ej: nombre en minúsculas, descripción clara). - El cuerpo no debe superar 500 líneas para mantener el rendimiento.

llms.txt: directrices generales para el agente - Propósito: Establece reglas globales para cómo el agente debe comportarse en un proyecto o repositorio. Por ejemplo: evitar generar código con vulnerabilidades, usar un tono formal en las respuestas o priorizar fuentes oficiales. - Estructura: Archivo de texto plano con directrices en lenguaje natural. No tiene frontmatter ni formato YAML. - Ventajas: - Es más flexible: puedes escribir las reglas en el orden que prefieras. - No tiene límites de tamaño o formato, lo que lo hace ideal para instrucciones largas. - Se integra fácilmente en repositorios de código o documentación. - Limitaciones: - No define habilidades específicas, solo guías de comportamiento. - No es portable: cada agente puede interpretar las directrices de manera distinta.

¿Cuándo usar cada uno? | Caso de uso | SKILL.md | llms.txt | |-------------------------------------|-----------------------------------|-----------------------------------| | Crear una habilidad reutilizable | ✅ Ideal (ej: generador de facturas) | ❌ No aplica | | Definir reglas para un proyecto | ❌ No es su propósito | ✅ Ideal (ej: normas de estilo) | | Incluir ejemplos o plantillas | ✅ En references/ | ❌ No soporta archivos externos | | Habilidades con pasos complejos | ✅ Ej: validar datos + generar PDF | ❌ Demasiado detallado | | Directrices para múltiples agentes | ❌ Solo si siguen el estándar | ✅ Funciona en cualquier agente |

Ejemplo práctico: Imagina que estás desarrollando un sistema para gestionar facturas de autónomos en España. Podrías usar: - SKILL.md: Para crear habilidades como generar-factura-es (con instrucciones para validar el NIF, calcular el IVA y generar un PDF) o validar-contrato-es (para revisar cláusulas de arrendamiento). - llms.txt: Para establecer directrices como "Siempre verifica que el NIF tenga el formato correcto según la normativa española" o "Usa un tono formal en las comunicaciones con clientes".

Complementariedad: Ambos formatos pueden usarse juntos. Por ejemplo: 1. Un repositorio podría incluir un llms.txt con reglas generales para el proyecto. 2. Dentro de la carpeta skills/, habría varios archivos SKILL.md con habilidades específicas (ej: skills/generar-factura-es/SKILL.md).

Herramientas para trabajar con ellos: - Para SKILL.md: Usa el Validador de SKILL.md para revisar el formato y el Conversor de JSON a YAML si necesitas editar el frontmatter en JSON primero. - Para llms.txt: No hay un validador específico, pero puedes usar un Contador de palabras para medir su longitud y asegurarte de que las directrices sean claras.

Conclusión: Elige SKILL.md cuando necesites definir una habilidad concreta con instrucciones detalladas y portabilidad. Opta por llms.txt para establecer reglas generales de comportamiento en un proyecto. En muchos casos, la mejor solución es combinar ambos: llms.txt para el contexto global y SKILL.md para las tareas específicas.