Campos del frontmatter
Dos campos son obligatorios y el resto opcionales. Las restricciones de abajo son las que aplica un validador, y por eso hay skills que fallan por motivos que parecen cosméticos, como una mayúscula en el nombre.
| Campo | Obligatorio | Restricción |
|---|---|---|
name | Obligatorio | 1 to 64 characters. Lowercase a-z, 0-9 and hyphens only. No leading or trailing hyphen, no consecutive hyphens. Must match the parent directory name. |
description | Obligatorio | 1 to 1024 characters. Must say what the skill does and when to use it, with keywords an agent can match against a task. |
license | Opcional | A license name, or the name of a bundled license file. Recommended to keep it short. |
compatibility | Opcional | Up to 500 characters. Only include it when the skill has real environment requirements, such as a target product, system packages or network access. |
metadata | Opcional | A map of string keys to string values for anything the spec does not define. Use distinctive key names to avoid collisions. |
allowed-tools Experimental | Opcional | A space separated string of pre-approved tools, for example Bash(git:*) Read. Support varies between agent implementations. |
Estructura de directorios
Solo SKILL.md es obligatorio. Los demás directorios son convención y existen para que el material grande quede fuera del contexto del agente hasta que haga falta.
| Ruta | Obligatorio | Para qué sirve |
|---|---|---|
SKILL.md | Obligatorio | Frontmatter plus the instructions themselves. |
scripts/ | Opcional | Executable code the agent can run. |
references/ | Opcional | Documentation loaded on demand, not up front. |
assets/ | Opcional | Templates, images, data files. |
Divulgación progresiva y presupuesto de contexto
Las skills se cargan en tres etapas. Esto decide si una biblioteca grande es usable, porque la primera etapa se paga por cada skill instalada en cada sesión.
| Etapa | Coste | Se carga | Contiene |
|---|---|---|---|
| Metadata | around 100 tokens | Loaded at startup for every installed skill | name and description only |
| Instructions | under 5,000 tokens recommended | Loaded when the skill is activated | the whole SKILL.md body |
| Resources | as needed | Loaded only when the task requires them | files under scripts/, references/ and assets/ |
Reglas que conviene memorizar
- Keep SKILL.md under 500 lines and move detail into references/.
- Keep file references one level deep from SKILL.md.
- The name must match the directory name, so renaming a skill means renaming both.
- Most skills do not need compatibility. Add it only when the environment really matters.
Valida antes de publicar
La librería de referencia comprueba el frontmatter y las convenciones de nombre, lo que detecta los errores que si no aparecen como una skill que simplemente nunca se carga.
skills-ref validate ./my-skillFuentes
Todas las restricciones de esta página vienen de la especificación publicada, leída en la fecha indicada. Verifica la fuente antes de depender de un campo en producción.
Agent Skills specification Última revisión: 2026-08-05