¿Qué es una skill y cómo se escribe el SKILL.md?

¿Qué es una skill y en qué se diferencia del archivo de reglas?

Según la definición del estándar abierto, una skill es una carpeta que contiene un archivo SKILL.md. El archivo empieza con al menos un nombre (name) y una descripción (description), y debajo lleva instrucciones que le explican al agente cómo hacer una tarea. La carpeta también puede incluir scripts, documentos de referencia y plantillas.

El formato lo creó Anthropic. Claude Code incorporó las skills el 16 de octubre de 2025, con la versión 2.0.20, y Anthropic publicó el formato como estándar abierto el 18 de diciembre de 2025. A 18 de octubre de 2026, las páginas de skills de Claude Code, Codex, Cursor, Gemini CLI y Copilot dicen que se basan en este estándar. La propia lista del estándar incluye 46 productos; el sitio del estándar dice que la lista solo muestra una parte de los productos que lo admiten. El 18 de junio de 2026, Google sustituyó Gemini CLI por Antigravity CLI para los usuarios gratuitos y los suscriptores de Google AI Pro y Ultra; Gemini CLI sigue disponible con una licencia de empresa o una clave de API de pago. Antigravity también lee las skills y busca las skills del proyecto en .agents/skills.

Lo que la distingue del archivo de reglas (AGENTS.md, CLAUDE.md, GEMINI.md) es cuándo se lee. El archivo de reglas se lee entero en cada sesión. Las instrucciones de una skill, en cambio, solo se cargan cuando la tarea encaja con ellas. Las herramientas lo explican con sus propias palabras:

• Claude Code: a diferencia de CLAUDE.md, el cuerpo de una skill solo se carga cuando se usa. Por eso un texto de referencia largo apenas ocupa espacio hasta que hace falta.
• Gemini CLI: los archivos de contexto como GEMINI.md dan al espacio de trabajo un trasfondo permanente; una skill es conocimiento experto que se abre cuando hace falta.
• Codex: AGENTS.md define el comportamiento del agente, y las skills empaquetan procesos que se repiten.
• Copilot: las instrucciones sencillas que sirven para casi cualquier tarea van en las custom instructions, y las instrucciones detalladas que solo deben leerse cuando hacen falta van en una skill.

Los formatos antiguos también se están pasando a las skills. En Claude Code, los comandos de .claude/commands/ se han fusionado con las skills. Codex ha dejado obsoletos los custom prompts y recomienda usar skills en su lugar. Cursor incluye una skill /migrate-to-skills que convierte reglas y comandos slash en skills.

Los archivos de reglas los explicamos en nuestro artículo sobre AGENTS.md y CLAUDE.md; los comandos que se ejecutan siempre, en nuestro artículo sobre hooks; y los ayudantes que trabajan en un contexto aparte, en nuestro artículo sobre subagentes. Este artículo trata la capa intermedia: las instrucciones que el agente solo abre cuando las necesita.

¿Cuándo lee el agente una skill?

El estándar lo llama divulgación progresiva (progressive disclosure). El agente no lee una skill de una vez; la lee por partes, a medida que la tarea lo pide:

El primer paso se paga en cada sesión, aunque la skill no se use nunca. Por eso importa cuántas skills instales. Dos herramientas dicen cuánto espacio recibe esta lista:

• Claude Code reserva para la lista el 1 % de la ventana de contexto del modelo. Si la lista no cabe, quita las descripciones de las skills que menos usas. Además, en la lista cada descripción se corta a los 1.536 caracteres.
• Codex reserva para la lista como mucho el 2 % de la ventana de contexto, o 8.000 caracteres si no conoce la ventana. Con skills.max_context_tokens puedes subir esta parte hasta 10.000 tokens como máximo. Si hay muchas skills instaladas, Codex acorta primero las descripciones.
• Cursor, Gemini CLI y Copilot: la documentación no lo dice.

Una vez abierta, la skill también ocupa espacio. En Claude Code, el contenido de una skill invocada entra en la conversación como un único mensaje y se queda ahí en los turnos siguientes. Cuando la conversación se compacta, de cada skill solo se vuelven a añadir los primeros 5.000 tokens. Por eso, escribe la instrucción más importante al principio del archivo.

¿Dónde se guardan las skills en cada herramienta?

El estándar define qué va dentro de una carpeta de skill, pero no dónde está esa carpeta. Su guía para quienes desarrollan herramientas lo dice claramente y presenta .agents/skills como la carpeta común que se está extendiendo entre herramientas. Esto decía la documentación de las cinco herramientas el 18 de octubre de 2026:

Fuente: la documentación de skills de cada herramienta, 18 de octubre de 2026. En estas carpetas, cada skill está en su propia subcarpeta: .agents/skills/<nombre>/SKILL.md. Cursor lee las carpetas de Claude Code y de Codex por compatibilidad. Las carpetas personales de Copilot salen de la documentación de la CLI; la documentación de VS Code añade ~/.claude/skills. «La documentación no lo dice»: en las páginas que leímos ese día no encontramos ninguna frase que lo explique.

Ninguna carpeta aparece en la documentación de las cinco herramientas. Cuatro herramientas leen .agents/skills; la documentación de Claude Code solo menciona .claude/skills y no dice nada de .agents/skills. Además de Claude Code, Cursor y Copilot leen .claude/skills; la documentación de Codex y la de Gemini CLI no mencionan esta carpeta. Que una carpeta no esté en la documentación no significa que la herramienta no la lea. Pero si te guías por la documentación, ninguna carpeta te asegura por sí sola que una skill se abra en las cinco herramientas.

Las herramientas también se comportan distinto cuando dos skills tienen el mismo nombre. La guía del estándar presenta como convención común de todas las herramientas que la skill del proyecto prevalezca sobre la personal, y la documentación de Gemini CLI y la de Copilot CLI la siguen. En la documentación de Claude Code el orden es el contrario: la skill personal prevalece sobre la del proyecto. Codex no fusiona las dos y muestra ambas en la lista.

Las subcarpetas también se leen de forma distinta. Claude Code y Codex leen cada carpeta skills desde la carpeta en la que iniciaste la sesión hasta la raíz del repositorio. Cursor encuentra cada carpeta .cursor/skills o .agents/skills dentro del repositorio y solo sugiere sus skills mientras trabajas con archivos de esa carpeta. Gemini CLI solo mira un nivel por debajo de la carpeta skills: .gemini/skills/<nombre>/SKILL.md se encuentra; lo que está más abajo, no.

¿Cómo se usa la misma skill en las cinco herramientas?

Si tus skills están en .agents/skills, Codex, Cursor, Gemini CLI y Copilot las leen; para Claude Code hace falta un paso más. El camino más corto que respalda la documentación es este: escribe la skill en .agents/skills/<nombre>/ y haz que .claude/skills/<nombre> apunte a ella con un symlink.

mkdir -p .claude/skills
# la skill está en .agents/skills/resumen-pr/SKILL.md
ln -s ../../.agents/skills/resumen-pr .claude/skills/resumen-pr
git add .claude/skills/resumen-pr

La documentación de Claude Code dice que una carpeta de skill (.claude/skills/<nombre>) puede ser un symlink a una carpeta que está en otro sitio. Aunque varias ubicaciones apunten al mismo destino, Claude Code carga la skill una sola vez. Convertir toda la carpeta .claude/skills en un único symlink no aparece en la documentación; esta describe un enlace por skill. Si enlazas en el sentido contrario, la documentación de Codex también dice que Codex sigue el destino de las carpetas de skills enlazadas con symlink.

Si alguien de tu equipo usa Windows, ten en cuenta una cosa. Según la documentación de Git, con core.symlinks desactivado, un symlink aparece como un pequeño archivo de texto que contiene la ruta del enlace. Y git clone desactiva ese ajuste por su cuenta si el sistema de archivos no admite symlinks. Comprueba aparte que el enlace funciona en su máquina.

También miramos qué hacen los repositorios populares. Para el artículo sobre AGENTS.md analizamos el 13 de octubre de 2026 los 100 repositorios con más estrellas; esta vez buscamos SKILL.md en los mismos árboles de archivos. De los 98 repositorios cuyo árbol pudimos leer completo, 41 tienen al menos un SKILL.md. De ellos, 21 guardan sus skills en una carpeta de herramienta en la raíz:

La carpeta más frecuente es .agents/skills, la que leen cuatro herramientas. 7 repositorios enlazan las dos carpetas con un symlink. En 5 de ellos, .claude/skills apunta a .agents/skills; en 1, al revés, .agents/skills apunta a .claude/skills; y en 1, .claude/skills apunta a .github/skills, la carpeta de Copilot. vercel/next.js y flutter/flutter enlazan toda la carpeta .claude/skills. langgenius/dify, en cambio, enlaza cada skill por separado, que es como lo describe la documentación de Claude Code.

¿Qué va al principio de un SKILL.md?

Un SKILL.md tiene dos partes: arriba del todo, YAML entre dos líneas --- (el frontmatter), y debajo, instrucciones en Markdown. El estándar define seis campos para el frontmatter:

Fuente: la especificación de Agent Skills, 18 de octubre de 2026.

Las herramientas no aplican estas reglas con el mismo rigor:

• En Claude Code todos los campos son opcionales; solo se recomienda description. Si falta name, se usa el nombre de la carpeta. Los campos que no reconoce los ignora sin dar error.
• Codex, Cursor, Gemini CLI y Copilot exigen name y description.
• Gemini CLI se salta el archivo sin avisar si falta alguno de los dos campos o si hay algo antes de la primera línea --- (un título, un comentario, incluso una línea en blanco). Además toma el nombre de la skill del campo name, no de la carpeta; el estándar y Cursor, en cambio, exigen que el nombre coincida con el de la carpeta.
• Copilot CLI también admite en el nombre mayúsculas, espacios, guiones bajos, puntos y dos puntos. El estándar solo acepta minúsculas, números y guiones.

Las reglas sobre etiquetas XML no son del estándar, sino de Anthropic. Según sus reglas para claude.ai y la API, name y description no pueden contener etiquetas XML, y name no puede contener las palabras «anthropic» ni «claude». Los campos propios de Claude Code (como when_to_use, context y hooks) funcionan en Claude Code. Pero si subes la misma skill a claude.ai o a la Skills API, cualquier campo fuera del estándar detiene la subida: Unexpected key(s) in SKILL.md frontmatter.

Si vas a usar una skill en más de una herramienta, empieza solo con los campos del estándar. El ejemplo de abajo usa solo los dos campos obligatorios y cumple las reglas sobre campos de la documentación de las cinco herramientas:

Para decidir qué va en el cuerpo, hazle a cada línea la pregunta de la guía del estándar: ¿haría mal el agente esta tarea sin esta instrucción? Si la respuesta es no, borra la línea. Lleva los textos de referencia largos a references/ y enlázalos directamente desde SKILL.md. Tanto el estándar como la guía de Anthropic recomiendan que los archivos de referencia estén a un solo nivel de SKILL.md.

¿Qué hay que escribir en la descripción?

Antes de elegir una skill, el agente solo ve su descripción. La guía del estándar lo dice claramente: «the description carries the entire burden of triggering.» La documentación de las herramientas dice lo mismo: Claude Code, Codex, Cursor y Copilot eligen una skill por su descripción. Según la guía de Gemini CLI, la descripción es también la única información que tiene el modelo antes de abrir la skill.

• Di qué hace y cuándo usarla. El estándar, Claude Code, Cursor y Copilot piden las dos cosas juntas. Una descripción como «Helps with PDFs.» no le dice nada al agente; es el mal ejemplo del propio estándar.
• Usa las palabras que diría tu usuario. La lista de solución de problemas de Claude Code empieza por aquí: ¿incluye la descripción palabras clave que los usuarios dirían de forma natural?
• Pon lo importante al principio. Cuando la lista no cabe, las descripciones se acortan. Claude Code corta cada descripción de la lista a los 1.536 caracteres. Codex acorta primero las descripciones cuando hay muchas skills instaladas; por eso su documentación recomienda poner al principio el caso de uso y las palabras que la activan.
• Distínguela de skills parecidas. La guía de Gemini CLI pide descripciones que se distingan entre sí y de lo que el modelo ya sabe hacer.

Las guías no coinciden en la persona gramatical. La guía de Anthropic pide la tercera persona y dice que las descripciones que empiezan con «I can help you…» o «You can use this…» pueden dificultar que se descubra la skill. La guía de agentskills.io, en cambio, recomienda escribir la descripción como una instrucción al agente, con el patrón «Use this skill when…». Los ejemplos de ambas guías siguen el mismo camino: primero qué hace la skill y luego, con «Use when…», cuándo usarla. El ejemplo de arriba está escrito así.

Ni siquiera una buena descripción garantiza que la skill se abra siempre. Según la guía del estándar, los agentes recurren a las skills sobre todo para tareas que no pueden resolver solos. Una petición de un solo paso como «lee este PDF» puede no abrir una skill de PDF aunque la descripción encaje a la perfección. Para Copilot, la documentación de VS Code también dice que el descubrimiento no garantiza que la skill se invoque en cada prompt pertinente.

¿Llamas tú a la skill o la elige el agente?

Las dos cosas. En las cinco herramientas, el agente puede abrir por su cuenta una skill que considera adecuada para la tarea. Llamarla a mano, y evitar que el agente la elija solo, depende de la herramienta:

Fuente: la documentación de skills de cada herramienta, 18 de octubre de 2026. En Claude Code y Copilot, user-invocable: false hace lo contrario: solo el agente puede abrir la skill.

Desactiva la elección del agente en las tareas con efectos secundarios. La documentación de Claude Code lo explica así: «You don't want Claude deciding to deploy because your code looks ready.» Las skills que despliegan, hacen commit o envían mensajes son de este tipo. Con este ajuste, Claude Code ni siquiera pone la descripción de la skill en el contexto, así que tampoco ocupa espacio en la lista. Encontrarás un ejemplo de skill que se llama a mano, una que convierte una petición de revisión en el comando /revisar, en nuestro artículo sobre el prompt de revisión de código.

En Gemini CLI es distinto: solo el agente puede llamar a activate_skill, la herramienta que abre una skill; tú no. A cambio, el agente te pide permiso cada vez que abre una skill.

¿Cómo saber si una skill funciona?

La documentación de Claude Code empieza con un aviso: «Seeing a skill trigger tells you Claude found it, not that it did what you intended.» Que una skill se abra y que haga bien el trabajo son dos preguntas distintas, y cada una se mide por separado.

Las dos se miden comparando. Reúne unos cuantos prompts realistas; ejecuta cada uno en una sesión nueva, una vez con la skill activada y otra con ella desactivada, y pon los resultados uno al lado del otro. La sesión nueva es importante, porque el contexto que se acumula mientras escribes la skill oculta los huecos de sus instrucciones.

Para medir con qué frecuencia se abre una skill, la guía de agentskills.io da una receta concreta:

• Escribe unos 20 prompts: la mitad debería abrir la skill y la otra mitad no.
• Elige los que no deberían abrirla entre tareas parecidas. Los prompts que usan las mismas palabras pero piden otra cosa son los que mejor muestran lo precisa que es la descripción.
• El modelo no toma siempre la misma decisión. Ejecuta cada prompt varias veces (3 es un buen comienzo) y calcula con qué frecuencia se abrió la skill.
• Un umbral de 0,5 es razonable: en los prompts que deberían abrir la skill, la tasa debe quedar por encima; en los que no, por debajo.

Por eso un solo intento no cuenta como resultado. Es normal que el mismo prompt abra la skill en una ejecución y no en la siguiente; cuando cambies una descripción, vuelve a ejecutar los mismos prompts el mismo número de veces.

¿Qué comprobar antes de instalar una skill de otra persona?

Una skill no es solo texto: puede ejecutar scripts, permitir que ciertas herramientas se usen sin preguntar y dirigir al agente con sus instrucciones. La documentación de Anthropic dice que una skill maliciosa puede llevar al agente a llamar herramientas o ejecutar código de formas que no encajan con el propósito que declara, y recomienda usar skills solo de fuentes de confianza.

Cada herramienta trata la confianza de forma distinta:

• Claude Code aplica el campo allowed-tools de una skill de proyecto incluso en una ejecución -p en una carpeta en la que nunca has confiado. Por eso su documentación pide leer este campo en las skills incluidas en un repositorio antes de ejecutar Claude Code allí. El campo no restringe herramientas; deja usar sin preguntar las herramientas de la lista durante el turno en que se invoca la skill.
• Copilot dice que GitHub no verifica las skills instaladas con gh skill y que pueden contener inyección de prompts, instrucciones ocultas o scripts maliciosos. Recomienda echarles un vistazo con gh skill preview antes de instalarlas.
• Gemini CLI te pide confirmar el origen al instalar desde una dirección remota y pide permiso cada vez que abre una skill. Además, solo carga las skills de proyecto de .gemini/skills si la carpeta de trabajo está marcada como de confianza.
• Codex y Cursor no tienen ninguna regla sobre confianza en sus páginas de skills: la documentación no lo dice.

La guía del estándar para quienes desarrollan herramientas también recomienda cargar las skills de proyecto solo en carpetas marcadas como de confianza. Un repositorio que acabas de clonar puede añadir instrucciones al contexto del agente sin que te des cuenta.

¿Cuándo usar una skill y cuándo AGENTS.md?

Una no sustituye a la otra, y los repositorios populares usan las dos. De los 41 repositorios analizados que tienen un SKILL.md, 35 también tienen un AGENTS.md o un CLAUDE.md en la raíz.

La diferencia está en cuándo hace falta la información. Lo que vale para cualquier tarea (la estructura del proyecto, los comandos de build, las reglas del tipo «nunca hagas esto») va en el archivo de reglas; un flujo de trabajo que necesitas de vez en cuando, o un texto de referencia largo, va en una skill. El criterio de la documentación de Claude Code funciona bien: si una sección de CLAUDE.md ha dejado de ser un dato y se ha convertido en un procedimiento, conviértela en una skill.

Vercel se hizo esta pregunta con sus propias pruebas en un artículo del 27 de enero de 2026. En pruebas construidas sobre las API de Next.js 16, la skill no se invocó nunca en el 56 % de los casos. Un índice de documentación de 8 KB incrustado en AGENTS.md alcanzó un 100 % de éxito; el mejor resultado de la skill fue un 79 %. Es la medición de un solo equipo sobre un solo tema, y el artículo no dice con cuántas tareas se midió. La conclusión de la propia Vercel tampoco es «una cosa o la otra»: «The two approaches complement each other.» Según el artículo, los flujos de trabajo concretos que el usuario inicia de forma explícita funcionan mejor como skill.

Una regla que hay que cumplir en cada pull request también es cosa del archivo de reglas. Cuando diffox revisa un pull request, lee el AGENTS.md de la raíz del repositorio, o el CLAUDE.md si no lo hay, y usa sus reglas como reglas de revisión. Si quieres que una regla se aplique en cada revisión, escríbela en el archivo de reglas.