Skills para agentes de código: deja de repetirle el mismo prompt a tu IA

Si usas un agente para programar, conoces la escena: abres una sesión nueva y vuelves a explicarle las reglas del proyecto, el formato que esperas y lo que no debe tocar. El agente no recuerda la conversación de ayer, así que tú repites el mismo prompt largo cada mañana.

Las skills existen para eso. Brais Moure lo explica en un taller de MoureDev que te recomendamos ver completo. Esta guía parte de sus ideas, comprueba los detalles técnicos en la documentación oficial de cada herramienta y añade lo que aprendimos al escribir nuestra propia skill.

Qué es una skill

Una skill es una carpeta con un archivo SKILL.md. Ese archivo tiene dos partes:

1. Una cabecera en YAML con, como mínimo, name y description.
2. Un cuerpo en Markdown con las instrucciones: pasos, restricciones, ejemplos y el formato de salida que esperas.

La carpeta puede llevar más cosas. La especificación recomienda tres subcarpetas opcionales:

• scripts/: código que el agente puede ejecutar, por ejemplo una validación o una prueba.
• references/: documentación que el agente lee solo cuando la necesita.
• assets/: plantillas, esquemas o archivos de datos.

El formato lo creó Anthropic y lo publicó como estándar abierto en agentskills.io. Hoy lo leen Claude Code, Codex, Cursor, OpenCode, GitHub Copilot en VS Code y muchos otros agentes.

La parte que más importa: la descripción

El agente no lee todas tus skills al empezar. Carga solo el nombre y la descripción de cada una, unas cien palabras como mucho. Cuando lo que le pides coincide con una descripción, lee el SKILL.md completo. Los archivos de references/ y scripts/ los abre solo si las instrucciones se lo piden. La especificación llama a esto carga progresiva.

Por eso la descripción decide si la skill sirve. Si es vaga, el agente no la usará cuando la necesitas, o la usará cuando no toca.

Compara estas dos:

description: Ayuda con artículos.

description: Revisa un borrador de artículo de Loki Evolved antes de publicarlo: tuteo, fuentes, enlaces internos y formato del frontmatter. Úsala cuando te pidan revisar, corregir o preparar un artículo, borrador o post.

La segunda dice qué hace, cuándo usarla y con qué palabras se la van a pedir. La especificación pone un límite de 1024 caracteres para la descripción y de 64 para el nombre, que solo admite minúsculas, números y guiones y debe coincidir con el nombre de la carpeta.

Dónde guarda las skills cada agente

Aquí hay que corregir una idea que circula mucho: el formato de la skill es el mismo, pero cada agente busca las skills en su propia carpeta.

• Claude Code: .claude/skills/<nombre>/SKILL.md dentro del proyecto, o ~/.claude/skills/ para tenerlas en todos tus proyectos.
• Codex: .agents/skills/ dentro del repositorio, o ~/.agents/skills/ en tu carpeta de usuario.
• Cursor y OpenCode también usan .agents/skills/.

Si trabajas con varios agentes, no hace falta copiar la skill a mano en cada carpeta. El instalador npx skills, del que hablamos más abajo, guarda una copia y crea enlaces simbólicos para cada agente.

Cómo se activa una skill

Hay dos formas, y las dos funcionan en los agentes principales.

Invocación explícita: la llamas por su nombre.

• En Claude Code escribes /nombre-de-la-skill al principio del mensaje, por ejemplo /revisar-borrador.
• En Codex escribes $nombre-de-la-skill, o usas /skills para ver la lista.

Invocación implícita: pides la tarea con tus palabras («revisa este borrador antes de publicarlo») y el agente reconoce que su descripción coincide.

La implícita es cómoda, pero no siempre la quieres. Una skill que publica, despliega o borra algo debería ejecutarse solo cuando tú la llamas. En Claude Code eso se consigue con disable-model-invocation: true en la cabecera; en Codex, con allow_implicit_invocation: false en su archivo de configuración de la skill. Estos campos no son parte del estándar común: revisa la documentación de tu agente antes de usarlos.

Una skill real: la que revisa nuestros borradores

Mientras preparábamos esta guía creamos una skill para nuestro propio flujo editorial. En Loki Evolved cada artículo pasa por la misma revisión antes de publicarse: tuteo y no voseo, cada dato con su fuente primaria, enlaces internos a guías relacionadas y un frontmatter completo. En vez de explicarlo en cada sesión, lo guardamos en esta carpeta del repositorio del sitio:

.claude/skills/revisar-borrador/
├── SKILL.md
├── references/
│   └── guia-de-estilo.md
└── scripts/
    └── validar_frontmatter.py

Este es el SKILL.md:

---
name: revisar-borrador
description: Revisa un borrador de artículo de Loki Evolved antes de publicarlo: tuteo, fuentes, enlaces internos y formato del frontmatter. Úsala cuando te pidan revisar, corregir o preparar para publicar un artículo, borrador o post de content/articulos.
---

# Revisar un borrador de Loki Evolved

No edites el archivo. Entrega un informe; los cambios los decide la editora.

1. Ejecuta `python3 .claude/skills/revisar-borrador/scripts/validar_frontmatter.py <archivo>`
   y copia su resultado.
2. Lee `references/guia-de-estilo.md` y marca cada frase en voseo
   («tenés», «pedile») con su versión en tuteo.
3. Lista cada cifra, fecha, precio o función de un producto y di si
   tiene una fuente enlazada. Si no la tiene, márcala como «sin fuente».
4. Propón de dos a cuatro enlaces a otros artículos de content/articulos
   que traten el mismo tema, con la ruta /signal/<slug>.

## Formato de salida

- Frontmatter: OK o la lista de errores del script
- Tuteo: tabla con frase original y propuesta
- Afirmaciones sin fuente: lista
- Enlaces internos sugeridos: lista con el motivo

Fíjate en el reparto de trabajo. Lo que tiene que salir siempre igual, comprobar que el frontmatter tiene título, slug, clúster y código, lo hace un script, porque un script no interpreta: responde lo mismo cada vez. Lo que necesita criterio, decidir si una frase suena natural o qué artículo enlazar, queda en las instrucciones. Brais lo resume en el taller con una idea que compartimos: un modelo de lenguaje no responde dos veces igual, y la skill le pone un arnés. Nosotros añadiríamos un matiz: la skill reduce la variación, pero lo único que de verdad se comporta igual cada vez es el código que va en scripts/.

La probamos en Claude Code con una petición normal, sin nombrar la skill: «Revisa el borrador content/articulos/rag-cuando-si-cuando-no.md antes de publicarlo». El agente la activó solo, ejecutó el script, no tocó el archivo y entregó el informe con las cuatro secciones. Además encontró algo que se nos había escapado: ese artículo no enlaza ninguna fuente. Para eso sirve una skill: la revisión que harías con calma un buen día, aplicada igual en todos los borradores.

Cuándo usar una skill y cuándo un archivo de reglas

No todo debe ser una skill. Muchos agentes leen un archivo de reglas del proyecto en cada sesión, como AGENTS.md o CLAUDE.md.

• Pon en el archivo de reglas lo que aplica siempre: el stack, cómo se ejecutan las pruebas, las carpetas que no se tocan.
• Haz una skill con lo que aplica a una tarea concreta: revisar un borrador, preparar una entrega, migrar un componente.

La diferencia está en el contexto. El archivo de reglas se carga entero en cada sesión. La skill solo ocupa su descripción hasta que la necesitas.

Instalar skills de la comunidad sin sustos

No hace falta escribirlo todo desde cero. En el taller, Brais muestra cómo instalar skills de otros desarrolladores. La herramienta más usada es el CLI de skills de Vercel Labs, con su directorio en skills.sh:

# Ver qué skills trae un repositorio sin instalar nada
npx skills add propietario/repositorio --list

# Instalar una sola skill en el proyecto actual
npx skills add propietario/repositorio --skill nombre-de-la-skill

# Buscar skills por tema
npx skills find testing

Con -g la instalas en tu carpeta de usuario y queda disponible en todos tus proyectos.

Algunas skills conocidas que se mencionan en el taller:

• frontend-design, de Anthropic: guía al agente para diseñar interfaces con criterio visual y no con el aspecto genérico de siempre.
• skill-creator: te ayuda a escribir skills nuevas. Viene con Codex y también está en el repositorio de skills de Anthropic.
• find-skills, del propio repositorio de Vercel Labs: busca skills que encajen con lo que necesitas.
• La colección de Matt Pocock, con skills como /tdd o /grill-me, pensadas para trabajar con pruebas y cuestionar un plan antes de escribir código.

Antes de instalar cualquiera, recuerda que una skill es código que tu agente ejecuta con tus permisos. Tres comprobaciones rápidas:

1. Lee el SKILL.md completo. Busca instrucciones que no tengan que ver con lo que promete la descripción.
2. Abre cada archivo de scripts/. Si descarga algo de internet, lee variables de entorno o envía datos fuera, necesitas saber por qué.
3. Prefiere repositorios con autor identificable, historial y versiones. Instala una skill concreta con --skill, no el repositorio entero.

Cuántas skills son demasiadas

Brais advierte en el taller contra la sobreingeniería, y tiene razón, aunque conviene entender por qué. Como el agente carga solo las descripciones, tener muchas skills no llena el contexto de golpe. El problema es otro: si varias descripciones se parecen, el agente duda entre ellas o elige la que no es. Y cada skill que instalas sin revisar es código que no conoces.

Nuestra regla: empieza con una skill para la tarea que más repites. Añade otra solo cuando notes que vuelves a escribir el mismo prompt por tercera vez. Las que sirven a un solo proyecto van en la carpeta del proyecto. Las que usas en todos, en tu carpeta de usuario.

Por dónde empezar hoy

1. Elige la tarea que más le explicas a tu agente.
2. Escribe en una frase qué hace y en otra cuándo se usa. Esa es tu descripción.
3. Crea la carpeta en la ruta de tu agente, con su SKILL.md.
4. Pruébala dos veces: una llamándola por su nombre y otra pidiéndola con tus palabras.
5. Si algo debe salir siempre igual, sácalo a un script.

Sigue leyendo

• Vibe coding con criterio: cómo especificar y revisar lo que escribe el agente.
• Cómo crear una skill para Claude Code y Codex: el paso a paso para construir una skill que verifica entregas.
• El fin de la «amnesia» en Claude: skills, conectores y plugins dentro de las apps de Claude, el complemento de esta guía si no programas.
• Cómo verificar una respuesta de IA antes de usarla: la revisión que nuestra skill automatiza, explicada paso a paso.
• Ingeniería inversa con IA: construye tu propia versión con REA: un método para pedirle al agente software a tu medida.

Fuentes

• Brais Moure (MoureDev), taller sobre Skills para agentes de IA en YouTube.
• Especificación de Agent Skills, el estándar abierto.
• Documentación de skills de Claude Code.
• Documentación de skills de Codex.
• skills.sh y el repositorio vercel-labs/skills en GitHub.