Un archivo SKILL.md es un documento Markdown con un bloque de frontmatter YAML arriba, y es la unidad que cargan las herramientas de agentes cuando quieres un procedimiento reutilizable en lugar de un prompt de una sola vez. Esta guía cubre el formato: cómo se organiza el archivo, qué campos del frontmatter cambian el comportamiento, cómo decide el agente si activa una skill y qué errores dejan una skill muerta sin avisar.

La documentación de Claude Code describe el formato en Extend Claude with skills y lo sitúa dentro de un estándar abierto Agent Skills que funciona en varias herramientas de IA. Puedes pegar cualquier bloque de frontmatter en el validador de YAML de UrsaKit mientras lees: te da la línea y la columna del primer error de sintaxis, algo que aquí importa más de lo habitual porque una skill con el YAML roto se carga igual, solo que con todos los campos ignorados.

01Una skill es un procedimiento guardado, no un prompt más largo

Casi cualquier entorno de agente ya tiene un archivo de hechos permanentes: un AGENTS.md, un CLAUDE.md o un archivo de reglas del editor. Ese archivo se carga entero en cada turno, así que tiene que ser corto. Una skill funciona al revés: el agente solo ve el frontmatter mientras trabaja con normalidad y arrastra el cuerpo al contexto cuando la tarea lo pide.

La documentación lo plantea sin rodeos: el cuerpo de una skill solo se carga cuando se usa, así que un material de consulta largo no cuesta casi nada hasta que hace falta. Por eso una checklist de publicación de 40 pasos puede vivir en el repositorio sin contaminar cada pregunta que no tiene que ver.

AGENTS.md  ->  always in context      ->  keep it to facts and constraints
SKILL.md   ->  loaded when relevant   ->  put long procedures here

Cada producto amplía el formato común. Claude Code añade control de invocación, ejecución en subagentes e inyección dinámica de contexto sobre los campos estándar, de modo que una skill escrita para una herramienta suele seguir funcionando en otra, aunque puede ganar comportamiento al mudarse.

02Desde dónde se cargan los SKILL.md

La ubicación decide el alcance, y el alcance decide si tu compañero de equipo recibe la skill al clonar el repositorio.

Las skills de proyecto son las que conviene versionar. El agente busca .claude/skills/ en el directorio donde arranca y en cada directorio padre hasta la raíz del repositorio, así que abrir una sesión dentro de packages/frontend/ sigue encontrando una skill definida arriba. Un directorio .claude/skills/ por debajo del directorio de trabajo no se carga al arrancar, y eso pilla a quien guarda la skill junto al código que describe.

Los comandos personalizados y las skills se han fusionado en un solo concepto. Un archivo en .claude/commands/deploy.md y una carpeta en .claude/skills/deploy/SKILL.md producen la misma invocación /deploy. Para trabajo nuevo conviene la forma de skill, porque solo ella puede llevar archivos de apoyo.

Algunos equipos mantienen un directorio en el repositorio, como .agent/skills/, y enlazan o copian entradas a la ruta que espera su herramienta. Es una decisión de convención, no parte del formato. El archivo que importa sigue siendo SKILL.md.

03Los campos del frontmatter, uno por uno

El frontmatter va entre marcadores --- al principio del archivo y se parsea como YAML. Los nombres de campo van en minúsculas con guiones, salvo when_to_use. Un nombre que no encaja con el esquema se ignora sin error, así que una errata se ve exactamente igual que un campo sin usar.

---
name: config-guard
description: Validate JSON and YAML config files before a commit. Use when the user asks to check a config file, debug a failing lint step, or prepare a release.
allowed-tools: Read Grep Bash(python3 *)
---

Dos detalles causan casi toda la confusión. Primero, description y when_to_use se concatenan y se truncan a 1.536 caracteres cuando el agente lista las skills disponibles, así que la primera frase carga con el peso del enrutado. Segundo, los campos booleanos aceptan yes, no, on, off, 1 y 0 en cualquier combinación de mayúsculas, lo que significa que un "false" entre comillas y un false sin ellas pueden comportarse distinto después de que YAML haga lo suyo.

Un YAML roto no falla a voces.

Si el frontmatter no se parsea, la skill se carga igual pero sin ningún campo definido. Te queda una skill sin descripción, así que el agente nunca enruta hacia ella y en los registros no aparece nada evidente. Valida el bloque antes de depurar cualquier otra cosa.

04Cómo decide el agente si activa una skill

La activación es una coincidencia de texto, no una consulta a un registro. El agente lee la lista de nombres y descripciones, la compara con la petición actual y carga el cuerpo de las que parecen relevantes. Ese modelo tiene tres consecuencias que puedes diseñar de antemano.

1. Escribe la descripción como la petición, no como la función. «Úsala cuando el usuario pida revisar un archivo de configuración» enruta mejor que «utilidades de validación de configuración».
2. Mantén el cuerpo estrecho. Una skill que cubre cinco trabajos sin relación tiene una descripción demasiado amplia para enrutar bien.
3. Nombra la carpeta con el verbo. Como name toma por defecto el nombre de la carpeta, .claude/skills/check-config/SKILL.md se comporta mejor que una carpeta llamada utils.

También puedes saltarte el enrutado. Una persona siempre puede escribir /skill-name, y disable-model-invocation: true fuerza ese camino para procedimientos que no quieres que se ejecuten solos. El permiso de allowed-tools dura un turno: la documentación indica que se borra cuando envías tu siguiente mensaje, así que una skill no puede escalar permisos en silencio a lo largo de una sesión.

05Un SKILL.md mínimo que puedes copiar

Esta es una skill completa que valida archivos de configuración antes de un commit. La carpeta se llama config-guard y el archivo vive en .claude/skills/config-guard/SKILL.md.

---
name: config-guard
description: Validate JSON and YAML config files before a commit. Use when the user asks to check a config file, debug a failing lint step, or prepare a release.
allowed-tools: Read Grep Bash(python3 *)
---

# Config Guard

Validate every changed config file and report failures as a table.

## Steps

1. List changed files with git diff --name-only -- '*.json' '*.yaml' '*.yml'
2. Parse each file with Python and capture the first error.
3. Print a table with file, line and message. Do not fix anything silently.

Dos hábitos la mantienen viva. Valida el frontmatter antes de hacer commit y escribe el cuerpo en imperativo. El cuerpo es un procedimiento que el agente va a ejecutar, no documentación para que lea una persona, así que «valida cada archivo» resiste mejor las ediciones que «el paso de validación se ejecuta».

06Por qué una skill no se activa

Hay dos nombres de carpeta reservados que conviene conocer antes de elegir uno. Claude Code omite una skill llamada synced fuera de su propio directorio de sincronización, y no carga una carpeta llamada anthropic-skills ni nada que empiece por anthropic-skills: salvo que viva dentro de un plugin.

07Skills, MCP y AGENTS.md

Los tres resuelven problemas distintos, y elegir mal es la razón de que algunas configuraciones se sientan impredecibles.

La regla práctica: una skill cambia cómo trabaja el agente; un servidor MCP le da algo nuevo que usar. Si una skill dedica la mayor parte del texto a explicar cómo llamar a una API, la llamada pertenece a MCP y el procedimiento que la rodea pertenece a la skill.

08Trata cada skill como código no confiable

El cuerpo de una skill son instrucciones, y el agente va a seguirlas. Eso convierte una skill de terceros en una superficie de inyección sin necesidad de ningún ejecutable: una skill hostil o descuidada puede decirle al agente que lea archivos que no debería, o que describa su trabajo de forma engañosa.

Antes de instalar una skill de un marketplace o del repositorio de un desconocido, lee el cuerpo entero, revisa allowed-tools y busca instrucciones que apunten a archivos fuera del proyecto. El mismo criterio que aplicas al script postinstall de una dependencia vale aquí, solo que sin el script.

Si quieres la mitad de validación de este flujo en un solo sitio: el validador de YAML caza errores del frontmatter, el formateador de YAML reindenta sin tocar los comentarios y el validador de JSON cubre los archivos de configuración que una skill trae junto a su SKILL.md. El generador de JSON Schema sirve cuando quieres un contrato de equipo en lugar de una convención.

09Fuentes

• Documentación de Claude Code — Extend Claude with skills（fecha de consulta: 2026-10-04）