≡En resumen
- SKILL.md es el único archivo obligatorio de una skill y debe estar en la raíz de su carpeta.
- El encabezado YAML va entre líneas de tres guiones y debe ser lo primero del archivo.
- La descripción es lo que Claude usa para decidir cuándo activar la skill: di qué hace y cuándo usarla.
- Claude Code admite campos extra, como disable-model-invocation o allowed-tools, que no existen en claude.ai.
- Mantén el cuerpo breve y enlaza a archivos de referencia y scripts para el detalle.
01 ¿Qué es el archivo SKILL.md?
Cuando hablamos de Claude Skills, hablamos en realidad de carpetas, y el corazón de cada carpeta es un archivo llamado exactamente SKILL.md. Es un archivo de texto en Markdown con dos partes: un bloque de metadatos al principio, llamado frontmatter, y las instrucciones que Claude debe seguir.
El formato lo define el estándar abierto Agent Skills, que Anthropic creó y que hoy adoptan otros agentes. Por eso un SKILL.md bien escrito funciona igual en claude.ai, en Claude Code y en otras herramientas compatibles, con pequeñas diferencias en los campos opcionales.
02 Estructura de un SKILL.md
---name: informe-semanaldescription: Genera el informe semanal de resultados de un cliente con la plantilla de la agencia. Úsala cuando pidan el informe de la semana, un resumen de resultados o el reporte del lunes.---# Informe semanal1. Pide el cliente y el rango de fechas si no te los dan.2. Sigue la estructura de plantilla.md.3. Define cada métrica según metricas.md.4. Termina con tres acciones concretas para la semana siguiente.
La carpeta que lo contiene puede incluir más archivos. El estándar recomienda una organización sencilla y referencias de un solo nivel desde el SKILL.md, para que Claude sepa qué abrir y cuándo.
| Elemento | Obligatorio | Para qué sirve |
|---|---|---|
| SKILL.md | Sí | Metadatos e instrucciones principales |
| scripts/ | No | Código que Claude ejecuta (Python, Bash, JavaScript…) sin cargarlo entero en el contexto |
| references/ | No | Documentación que Claude lee solo cuando la necesita |
| assets/ | No | Plantillas, imágenes o tablas de datos |
03 Campos del frontmatter: name, description y opcionales
| Campo | Obligatorio | Reglas |
|---|---|---|
| name | Sí | 1 a 64 caracteres; solo minúsculas, números y guiones; sin guion al principio o al final ni guiones dobles; igual que el nombre de la carpeta |
| description | Sí | 1 a 1.024 caracteres; qué hace la skill y cuándo usarla, con palabras clave de la tarea |
| license | No | Nombre de la licencia o archivo de licencia incluido |
| compatibility | No | Hasta 500 caracteres sobre requisitos del entorno |
| metadata | No | Pares clave-valor libres, como autor o versión |
| allowed-tools | No | Herramientas preaprobadas; experimental y con soporte variable |
04 Campos extra de SKILL.md en Claude Code
Claude Code amplía el formato porque allí las skills también son comandos slash. En Claude Code todos los campos son opcionales: si falta name, se usa el nombre de la carpeta, aunque la descripción sigue siendo muy recomendable.
disable-model-invocation
Con true, solo tú puedes lanzar la skill con /nombre. Útil para acciones con efectos, como desplegar.
user-invocable
Con false, la skill no aparece en el menú de comandos y solo Claude la usa cuando encaja.
allowed-tools y disallowed-tools
Preaprueban o retiran herramientas mientras la skill está activa.
context: fork
Ejecuta la skill en un subagente aislado; agent indica qué tipo de subagente usar.
argument-hint y arguments
Pista de autocompletado y argumentos con nombre para el comando.
model y effort
Cambian el modelo o el nivel de esfuerzo durante el turno en que se usa la skill.
Con disable-model-invocation: true y el cuerpo «Corrige la incidencia $ARGUMENTS siguiendo nuestras normas de código», escribir /fix-issue 123 sustituye $ARGUMENTS por 123. Para referenciar un script incluido sin depender del directorio de trabajo, usa ${CLAUDE_SKILL_DIR}.
Si la skill forma parte de uno de los plugins de Claude Code, su comando lleva delante el nombre del plugin, por ejemplo /mi-plugin:revisar.
05 Cómo escribir un buen SKILL.md
- ✓Empieza la descripción por el caso de uso principal: en Claude Code, la descripción se recorta en el listado si es muy larga.
- ✓Incluye las palabras que la gente usa al pedir la tarea («informe del lunes», «propuesta», «factura»).
- ✓Escribe pasos numerados y verificables en lugar de consejos generales.
- ✓Añade un ejemplo de entrada y de salida esperada.
- ✓Cuenta los casos difíciles: qué hacer si faltan datos o si algo no cuadra.
- ✓Mantén el cuerpo por debajo de unas 500 líneas y mueve el detalle a references/.
- ✓Pon en scripts lo que deba ser exacto y en texto lo que requiera criterio.
Mejorable: «Ayuda con PDFs».
Útil: «Extrae texto y tablas de archivos PDF, rellena formularios y une varios documentos. Úsala cuando el usuario trabaje con PDFs, formularios o extracción de datos de documentos». La segunda dice qué hace, cuándo usarla y con qué palabras suele pedirse.
06 Errores frecuentes y cómo evitarlos
| Síntoma | Causa probable | Solución |
|---|---|---|
| La skill nunca se activa | Descripción vaga o sin las palabras de la tarea | Reescribe la descripción con qué hace y cuándo usarla |
| Se activa cuando no toca | Descripción demasiado amplia | Acota el caso de uso y di cuándo no usarla |
| Error al subirla a claude.ai | Campos que solo existen en Claude Code o name inválido | Deja solo los campos del estándar y revisa mayúsculas y guiones |
| Resultados distintos cada vez | Instrucciones abiertas sin ejemplo | Añade pasos concretos y un ejemplo de salida |
| Consume mucho contexto | Todo el detalle está en el SKILL.md | Mueve tablas y ejemplos largos a archivos de referencia |
Para validar el formato existe la biblioteca de referencia skills-ref del estándar. Y si una tarea es tan larga que conviene aislarla, valora delegarla en un subagente en lugar de inflar la skill.
07 SKILL.md en el trabajo diario de una empresa
Documenta una vez
Los procedimientos que hoy viven en la cabeza de una persona pasan a un archivo versionado.
Comparte con control
Las skills del proyecto se guardan en el repositorio y las de la organización se despliegan desde claude.ai.
Mide y mejora
En Team y Enterprise puedes ver la adopción de cada skill y retocar las que no se usan.
Si quieres convertir manuales internos en skills que funcionen, nuestro equipo de agencia de IA puede ayudarte a priorizar y redactarlas. Cuando la skill necesita apoyarse en una herramienta propia, lo abordamos como desarrollo de apps a medida. En nuestro hub de recursos sobre Claude tienes más material.
Preguntas frecuentes sobre SKILL.md
Es el archivo principal de una skill de Claude: un Markdown con un encabezado YAML que contiene el nombre y la descripción, seguido de las instrucciones que Claude debe seguir.
Según el estándar Agent Skills, name y description. En Claude Code todos son opcionales, pero la descripción es muy recomendable porque decide cuándo se activa la skill.
La recomendación es mantenerlo por debajo de unas 500 líneas y mover el detalle a archivos de referencia que Claude abre solo cuando los necesita.
No. El campo name solo admite minúsculas, números y guiones, hasta 64 caracteres, y debe coincidir con el nombre de la carpeta.
En ~/.claude/skills/nombre/SKILL.md para todos tus proyectos o en .claude/skills/nombre/SKILL.md dentro del repositorio para compartirlo con el equipo.
Sí. Se guardan en la carpeta de la skill, normalmente en scripts/, y Claude los ejecuta cuando las instrucciones lo indican sin cargar su código entero en el contexto.
Gana la de mayor prioridad: la de empresa sobre la personal y la personal sobre la del proyecto. Las de plugins no chocan porque llevan delante el nombre del plugin.
Fuentes consultadas
Sobre el autor
Germán Gutiérrez
Development Manager en appyweb
Dirige el equipo de desarrollo de appyweb: aplicaciones web y móviles, SaaS, integraciones y arquitectura de software.
Ver perfil en LinkedIn ↗