Skills: procedimientos reutilizables para agentes
Una carpeta con instrucciones, y opcionalmente scripts y referencias, que enseña al agente un tipo de tarea concreto. Solo se carga cuando hace falta.
Antes de empezar
- AGENTS.md: instrucciones persistentes para un proyectoTécnica
Un archivo Markdown en la raíz del repositorio que explica al agente cómo funciona tu proyecto: comandos, convenciones y cómo comprobar los cambios. Es una guía, no un mecanismo de control.
Publicado
La idea clave: si
AGENTS.mdes lo que todo el equipo debe saber, una Skill es el manual de un trabajo concreto. El agente solo ve su nombre y su descripción hasta que la necesita; entonces carga el manual completo.
El problema
Con el tiempo descubres procedimientos que el agente debería seguir siempre de la misma forma: preparar las notas de una versión, añadir un endpoint, revisar una migración. Si los metes todos en AGENTS.md, el archivo crece sin control y el agente carga el procedimiento de versiones incluso cuando solo está corrigiendo una errata.
Cómo funciona
Una Skill es una carpeta con un archivo SKILL.md. Según la especificación abierta de Agent Skills, ese archivo empieza con dos campos obligatorios, name y description, seguidos de las instrucciones en Markdown. Opcionalmente, la carpeta puede incluir scripts/ (código que el agente puede ejecutar), references/ (documentación de apoyo) y assets/ (plantillas o datos).
La clave es la carga progresiva:
- Al empezar, el agente solo ve el nombre y la descripción de cada Skill disponible. Ocupan muy poco.
- Cuando una tarea encaja con la descripción —o cuando la invocas tú por su nombre—, carga el
SKILL.mdcompleto. - Si el procedimiento lo pide, lee las referencias o ejecuta los scripts de la carpeta.
Así puedes tener muchas Skills sin llenar el contexto: solo pagas por la que usas.
Por eso la descripción es lo más importante. Es lo único que el agente ve para decidir si la Skill aplica, así que debe decir qué hace y cuándo usarla, con las palabras que aparecerían en una petición real.
Ejemplo práctico
La ubicación depende del cliente. Claude Code, por ejemplo, busca las Skills del proyecto en .claude/skills/:
.claude/
└── skills/
└── release-notes/
└── SKILL.md
Contenido de SKILL.md:
---
name: release-notes
description: Redacta notas de versión a partir de los commits de Git. Úsala cuando pidan notas de versión, un changelog o un resumen de cambios para una release.
---
# Notas de versión
1. Lee los commits desde la última etiqueta (`git log <etiqueta>..HEAD`).
2. Agrupa los cambios en: incompatibles, novedades y correcciones.
3. Escribe cada punto pensando en quien usa el proyecto, no en quien lo programa.
4. No inventes cambios: cada punto debe corresponder a un commit.
5. Si no hay una etiqueta anterior, pregunta desde qué punto empezar.
El nombre de la carpeta coincide con name, como pide la especificación. Y la descripción incluye las palabras que alguien usaría al pedirlo: “notas de versión”, “changelog”.
¿Skill, AGENTS.md o herramienta?
| Si es… | Usa… |
|---|---|
| Una regla que aplica a casi todas las tareas | AGENTS.md |
| Un procedimiento para un tipo de tarea | Una Skill |
| Una capacidad nueva (consultar una API, una base de datos) | Una herramienta o un servidor MCP |
Una Skill puede explicar cómo usar una herramienta, pero no la instala ni le concede permisos.
Errores comunes
- Descripciones vagas. “Ayuda con las versiones” no le dice al agente cuándo usarla. Sé específico sobre qué hace y cuándo aplica.
- Descripciones demasiado amplias. Una Skill que “ayuda con el código” se activará donde no debe.
- Skills de una sola línea. Si cabe en una frase y aplica siempre, va en
AGENTS.md. - Scripts con demasiado poder. Los scripts de una Skill se ejecutan con los permisos del agente. Revísalos como revisarías cualquier otro código.
- Instalar Skills de terceros sin leerlas. Son instrucciones y código que el agente va a seguir. Léelas antes, igual que harías con una dependencia.
Cuándo usarlo
Cuando repitas el mismo procedimiento varias veces o veas que AGENTS.md empieza a llenarse de pasos que solo sirven para un tipo de tarea. Empieza sin scripts ni referencias: un SKILL.md claro suele bastar.
Siguiente paso
Todo lo que has visto hasta aquí le da información al agente. El siguiente bloque trata de lo que el agente puede hacer: Herramientas y permisos.
Fuentes
Consultadas el 2026-10-05.
- Agent Skills: Specification.
- Extend Claude with skills, documentación de Claude Code.
Contenido relacionado
- Herramientas y permisosTécnica
Qué es una herramienta, cómo la usa un agente y cómo decidir qué puede hacer sin preguntar, qué necesita tu aprobación y qué queda prohibido.
Publicado - Subagentes y delegaciónTécnica
Cuándo conviene repartir una tarea entre varios agentes con su propio contexto, cómo darles encargos claros y cómo reunir sus resultados sin perder el control.
Publicado