Agent Skills: el estándar abierto de skills para agentes de IA

Durante un año, escribir un SKILL.md significaba escribirlo para Claude Code. Ya no. El formato se publicó como estándar abierto y hoy lo implementan una cuarentena larga de productos: Cursor, GitHub Copilot, VS Code, Gemini CLI, Codex, ChatGPT, OpenCode, Goose, Kiro, JetBrains Junie, Amp, Roo Code, Factory, Tabnine o Laravel Boost, entre otros.

Eso cambia la aritmética de escribir uno. Antes invertías una tarde en un procedimiento atado a una herramienta que quizá dejabas de usar en seis meses. Ahora el mismo archivo sobrevive al cambio de producto, y lo que se queda por el camino son detalles de configuración, no el contenido.

Esta guía es la especificación traducida a lo que hace falta saber para escribir uno que funcione en más de un sitio. Los datos vienen de la especificación oficial y de la documentación de cada producto, consultadas el 1 de septiembre de 2026.

Qué es Agent Skills y por qué se convirtió en estándar

Un skill es una carpeta con instrucciones que un agente carga solo cuando le hacen falta. El problema que resuelve es viejo y muy concreto: los agentes son capaces pero no saben cómo se hacen las cosas en tu casa. Cómo se revisa una cláusula en tu despacho, qué formato tiene un informe en tu empresa, qué pasos lleva desplegar en tu infraestructura.

Ese conocimiento se puede meter en el prompt de sistema, pero entonces se paga en cada mensaje, aunque la conversación vaya de otra cosa. La alternativa era pegarlo a mano cada vez. Un skill lo empaqueta en un archivo versionado que el agente abre bajo demanda.

El formato lo desarrolló Anthropic y lo liberó como estándar abierto. La razón de que lo adoptaran los competidores no es generosidad: es que el coste de implementarlo es ridículo —leer carpetas y parsear un YAML— y el beneficio es heredar todo el material que ya existía escrito.

La anatomía de un skill: un archivo y tres carpetas

La estructura completa que define la especificación cabe en seis líneas:

mi-skill/
├── SKILL.md          # Obligatorio: metadatos + instrucciones
├── scripts/          # Opcional: código ejecutable
├── references/       # Opcional: documentación de apoyo
├── assets/           # Opcional: plantillas, imágenes, datos
└── ...               # Cualquier otro archivo o carpeta

Solo SKILL.md es obligatorio. Las tres carpetas son convenciones, no requisitos: puedes meter lo que quieras dentro de la carpeta del skill, pero si respetas los nombres, cualquiera que abra el repositorio entiende el reparto sin preguntar.

El criterio para separar en carpetas no es estético, es de contexto. Lo que va en references/ el agente lo lee solo si el trabajo lo pide; lo que va en el cuerpo de SKILL.md se carga entero en cuanto el skill se activa. Un manual de 4.000 palabras dentro del cuerpo se paga cada vez que el skill entra en juego, aunque solo hiciera falta el párrafo tercero.

El frontmatter, campo por campo y con sus límites

La cabecera YAML va entre marcas --- al principio del archivo. Solo dos campos son obligatorios:

Un skill mínimo válido es esto y nada más:

---
name: revision-de-contratos
description: Revisa contratos de prestación de servicios y señala cláusulas de riesgo. Úsalo cuando el usuario comparta un contrato, un borrador o mencione revisión legal de un acuerdo.
---

Instrucciones aquí.

De los seis campos, el que decide si el skill sirve de algo es description, y casi nadie le dedica el tiempo que merece. Es lo único que el agente tiene delante cuando decide si activarlo o no: si dice «ayuda con contratos», no se activará ante «mírate este borrador de acuerdo marco». La especificación es explícita en que debe describir qué hace y cuándo usarlo, e incluir palabras clave que ayuden a reconocer la tarea. Tienes 1.024 caracteres. Usa unos cuantos.

El detalle que más falla en la práctica: name tiene que coincidir con el nombre de la carpeta. Renombrar la carpeta y olvidar el YAML deja un skill que el validador rechaza y que algunos clientes sencillamente ignoran sin avisar.

Divulgación progresiva: los tres niveles de carga

El mecanismo que hace que tener treinta skills instalados no arruine cada sesión se llama divulgación progresiva, y funciona en tres escalones:

1. Metadatos (~100 tokens). Al arrancar, el agente carga solo el name y la description de cada skill disponible. Lo justo para saber cuál puede venir a cuento.
2. Instrucciones (menos de 5.000 tokens recomendados). Cuando una tarea encaja con la descripción, se lee el cuerpo entero de SKILL.md.
3. Recursos (bajo demanda). Los archivos de scripts/, references/ y assets/ solo se abren si las instrucciones llevan al agente hasta ellos.

La recomendación operativa que se deriva: mantén SKILL.md por debajo de 500 líneas y saca el material de referencia a archivos aparte. Y al referenciarlos, usa rutas relativas desde la raíz del skill y mantenlas a un nivel de profundidad; las cadenas de referencias anidadas hacen que el agente vaya abriendo archivos sin control.

Regla de bolsillo: el nivel 1 se paga en todas las sesiones, el nivel 2 en las sesiones donde el skill se activa, y el nivel 3 casi nunca. Escribe cada cosa en el nivel más barato donde siga siendo útil.

Dónde lo busca cada herramienta

Aquí es donde se acaba la portabilidad automática. El formato es el mismo, pero cada producto mira en sus propias carpetas. Estas son las rutas según la documentación oficial de cada uno, consultadas el 1 de septiembre de 2026:

Lee la tabla en vertical y sale la conclusión práctica: .agents/skills/ es el denominador común. Cursor, VS Code con Copilot y Codex la leen los tres. Si vas a dejar skills en un repositorio compartido por un equipo que no usa todo el mundo la misma herramienta, esa es la carpeta.

Claude Code es la excepción: no lee .agents/skills/. Sí acepta, en cambio, que la carpeta del skill sea un enlace simbólico a otro sitio del disco, así que la salida limpia en una máquina con varias herramientas es tener el contenido en un único lugar y enlazarlo desde .claude/skills/. Y en el sentido contrario, VS Code sí lee .claude/skills/, con lo que un repositorio que ya tenga skills de Claude Code funciona en Copilot sin tocar nada.

Qué se rompe al mover un skill de una herramienta a otra

El cuerpo del archivo viaja bien: son instrucciones en Markdown y ningún producto las interpreta de forma especial. Lo que no viaja igual es el frontmatter, porque cada uno ha añadido campos propios por encima de la especificación.

Claude Code acepta bastantes más de los seis del estándar —control de quién puede invocar el skill, ejecución en un subagente, inyección de contexto dinámico—, pero fuera de Claude Code solo puedes contar con los seis. Las subidas a claude.ai y la API de Skills, de hecho, aceptan exactamente name, description, license, compatibility, metadata y allowed-tools.

Cursor añade los suyos (paths para limitar el skill a ciertos archivos, icon, color), y VS Code otros distintos (argument-hint, user-invocable, context: fork). Coinciden en uno: disable-model-invocation, para que el skill solo se active si lo pides tú. Un campo desconocido no suele romper nada —se ignora—, pero tampoco hace nada, y ahí está el riesgo: un skill que dependía de paths para no activarse fuera de sitio se activará en todas partes en cuanto lo muevas.

Tres reglas para escribir uno pensado para viajar:

• No dependas del frontmatter para acotar. Si el skill solo debe usarse en cierto contexto, dilo en la description con palabras, no en un campo que la mitad de los clientes ignora.
• Cuidado con allowed-tools. Los nombres de las herramientas no son los mismos entre productos, y el campo está marcado como experimental. Escribe el skill para que funcione aunque ninguna herramienta esté preaprobada.
• Declara el entorno en compatibility. Si tu skill necesita git, Python o acceso a internet, ponlo ahí en vez de dejar que falle en la máquina de otro. Aunque el cliente no actúe sobre el campo, lo lee la persona que instala el skill.

Validarlo antes de compartirlo

Hay una biblioteca de referencia, skills-ref, en el repositorio del estándar. Comprueba que el frontmatter es válido y que se respetan las reglas de nombres:

skills-ref validate ./mi-skill

Merece la pena pasarlo antes de publicar nada, porque los tres errores que más se repiten los caza todos: el name que no coincide con la carpeta, las mayúsculas o los guiones consecutivos en el nombre, y la descripción vacía o de tres palabras. Ninguno de los tres da error visible al usar el skill: simplemente el agente no lo activa nunca y tú das por hecho que el modelo no se entera.

Por dónde empezar hoy

Si no tienes ninguno escrito, el mejor primer skill no es el más ambicioso: es el procedimiento que ya has pegado tres veces esta semana en un chat. Sácalo a una carpeta, ponle una descripción que diga cuándo aplica, y déjalo en .agents/skills/ si trabajas con varias herramientas o en .claude/skills/ si solo usas Claude Code.

A partir de ahí, el orden natural es: cómo se escribe uno que se active cuando toca, en qué se diferencia de un prompt y de un plugin, y cuándo el problema no se resuelve con instrucciones sino con un servidor MCP.

Y antes de escribir el tuyo desde cero, mira si ya existe. En el catálogo hay material en español por profesión que se copia y se adapta en menos tiempo del que cuesta redactar una buena descripción.