Agent Skills: Cómo Enseñarle a un Agente de IA lo que tu Equipo Ya Sabe

En el fondo, una skill es un directorio con un único archivo obligatorio: SKILL.md. Su frontmatter en YAML lleva metadata — como mínimo una description — y el cuerpo en markdown debajo son las instrucciones que el agente sigue una vez que la skill se carga. No hace falta nada más para armar una:

---
description: Summarize uncommitted changes and flag anything risky
---

Run `git diff HEAD`, summarize it in three bullets, then list any risks.

Eso ya es una skill completa y funcionando. La description es lo único que un agente ve antes de decidir si aplica a la tarea actual — todo lo que está debajo del frontmatter recién se carga cuando ese match ocurre.

Una skill puede crecer bastante más allá de tres líneas. Puede empaquetar documentos de referencia, templates y scripts ejecutables junto a SKILL.md, y apuntar a ellos por nombre para que el agente traiga cada uno solo cuando las instrucciones realmente lo piden. Ese empaquetado es lo que hace que las skills funcionen en cualquier tamaño, desde un recordatorio de una línea hasta un flujo de varios pasos con sus propios scripts de test.

Antes de las skills había exactamente tres formas de lograr que un agente siguiera el procedimiento puntual de un equipo. Pegarlo en la conversación, y desaparece apenas termina la sesión. Meterlo en el system prompt o en un archivo como CLAUDE.md que carga en cada turno, y ahora se paga su costo completo en tokens en cada request — incluidos los que no tienen nada que ver. Construir un agente dedicado alrededor, y queda una carga de mantenimiento que no viaja a ninguna otra herramienta.

Ninguno de esos trade-offs es realmente sobre el procedimiento — son sobre cuándo se paga por él. La description de una skill está en contexto desde el arranque, lo suficientemente barata como para tener docenas a mano, y sus instrucciones reales solo cargan cuando una tarea hace match. El resto del tiempo, no cuestan nada.

Esa es toda la propuesta: no un agente más inteligente, sino una forma de darle exactamente el contexto que le falta, justo cuando lo necesita, sin cobrarle peaje a todo lo demás que está haciendo.

El mecanismo detrás de eso se llama progressive disclosure, y funciona en tres etapas. Al arrancar, el agente carga solo el nombre y la description de cada skill disponible — suficiente para saber qué existe, no para leer nada de eso. Cuando una tarea hace match con una, el cuerpo completo de SKILL.md entra en contexto. Y si esa skill empaqueta sus propios archivos de referencia, scripts o templates, esos cargan solo cuando sus propias instrucciones apuntan al agente hacia ellos.

La guía práctica sale directo del mecanismo: mantené el SKILL.md en sí por debajo de las 500 líneas y los 5.000 tokens, más o menos — lo justo y necesario para cada corrida — y movés cualquier cosa más larga, como una referencia de API completa o un set grande de ejemplos, a su propio archivo que las instrucciones enlazan por nombre.

Las mejores skills salen de una tarea real y repetida, no de una descripción genérica de buenas prácticas — así que acá va una sacada directamente de este repositorio. Cada post de este blog sigue el mismo patrón de siete archivos: un componente de página, uno o dos componentes de diagrama, una entrada en un registro central, y bloques de traducción que coinciden en dos archivos de idioma. Ese es exactamente el tipo de procedimiento que vale la pena capturar una sola vez en lugar de reexplicarlo cada vez.

.claude/skills/new-post/
├── SKILL.md                    # overview + the procedure
├── references/
│   └── message-keys.md         # full blog.<key> shape, both locales
├── assets/
│   └── page.template.tsx       # starting point for the new route
└── scripts/
    └── check-locales.mjs       # diffs en.json vs es.json key trees

El SKILL.md en sí se mantiene corto — un procedimiento numerado, más los gotchas que este repositorio produjo de verdad:

---
description: Add a new article to the dizenz blog. Use when asked to
  write, draft, or publish a blog post for the site.
allowed-tools: Read Write Edit Bash(pnpm lint)
---

## Procedure

1. Pick a slug and copy `assets/page.template.tsx` to
   `app/[locale]/blog/<slug>/page.tsx`.
2. Add a `blog.<camelKey>` block to both `messages/en.json` and
   `messages/es.json` — see `references/message-keys.md` for the shape.
3. Prepend an entry to `BLOG_POSTS` in `lib/blog-posts.ts` and add the
   slug to `SLUG_TO_MESSAGE_KEY`.
4. Run `node scripts/check-locales.mjs <camelKey>` — both locales must
   report the same key tree.
5. Run `pnpm lint`.

## Gotchas

- Prose lives in `messages/{locale}.json`. Never inline copy in the page
  file — only code samples and icon arrays go there.
- `en.json` and `es.json` must have identical key trees. Only the values
  differ.
- A slug missing from `SLUG_TO_MESSAGE_KEY` silently breaks the localized
  card for any multi-word slug — it falls back to the raw slug as the key.
- Spanish copy is Argentine voseo ("Instalalo", "Creá"), not neutral
  Spanish.
- Display order in `BLOG_POSTS` is array order, not `date`. `date` is
  SEO-only metadata.

Un puñado de campos del frontmatter definen cómo se comporta una skill una vez que existe. Estos cuatro cubren la mayor parte de lo que necesita una skill real:

Fijate qué falta en esa sección de gotchas: consejos genéricos tipo 'escribí código claro' o 'testeá tus cambios.' El valor de una skill está casi todo en lo que el agente se equivocaría sin ella — un archivo puntual, una regla puntual, un error que alguien cometió de verdad. Cada corrección que necesita la salida de un agente es un gotcha esperando que lo agreguen.

Dónde vive una skill determina quién puede usarla. Para algo que solo le importa a un repositorio, subirla al directorio .claude/skills/ de ese repo es todo el paso de publicación — cualquiera que clone el proyecto la tiene automáticamente, sin instalación aparte:

mkdir -p .claude/skills/new-post
git add .claude/skills/new-post
git commit -m "chore: add new-post skill"

# That's the whole distribution step for a single repo — anyone who
# clones it and opens Claude Code gets the skill automatically.

Compartir una skill entre repositorios, o con gente fuera de un equipo, significa envolverla en un plugin en cambio: un manifiesto que describe el plugin (plugin.json), y un catálogo de marketplace (marketplace.json) que dice dónde encontrarlo.

{
  "name": "blog-tools",
  "description": "Skills for writing and maintaining the dizenz blog",
  "version": "1.0.0",
  "author": { "name": "dizenz" }
}

{
  "name": "dizenz",
  "owner": { "name": "dizenz" },
  "plugins": [
    {
      "name": "blog-tools",
      "source": "./plugins/blog-tools",
      "description": "Skills for writing and maintaining the dizenz blog"
    }
  ]
}

De ahí en más, cualquiera puede agregar el marketplace e instalar el plugin por nombre. Su skill queda con el namespace del plugin, así que las skills new-post de dos equipos nunca chocan:

/plugin marketplace add dizenz/claude-plugins
/plugin install blog-tools@dizenz

# Namespaced under the plugin, so it can't collide with anyone
# else's new-post skill:
/blog-tools:new-post

Para toda una organización, ese mismo plugin puede desplegarse a través de managed settings en lugar de una instalación opcional — cada asiento la tiene sin que nadie corra un comando.

Una skill subida directo al .claude/skills/ de un proyecto se actualiza en el momento en que cambia el archivo — sin reiniciar, sin reinstalar. Cualquiera que tenga el repo clonado ve la versión nueva en su próximo prompt.

# In the plugin repo: bump the version, then push
# .claude-plugin/plugin.json: "version": "1.1.0"
git commit -am "chore: bump blog-tools to 1.1.0"
git push

# On the consumer's machine
/plugin marketplace update dizenz

Una skill distribuida por plugin no se actualiza sola. Subir el campo version en plugin.json es lo que le avisa a un marketplace que hay una release nueva; si te lo salteás, cada consumidor sigue corriendo la copia vieja indefinidamente, en silencio.

Hay un detalle más del ciclo de vida que vale la pena conocer antes de depender de una skill a mitad de una tarea: una vez invocada, su contenido renderizado se queda en la conversación por el resto de esa sesión y nunca se vuelve a leer. Editar una skill mientras un agente ya la tiene cargada no cambia nada hasta la próxima invocación desde cero.

Antes de mandar una edición, vale la pena confirmar que de verdad es una mejora y no una regresión disfrazada — el plugin skill-creator automatiza exactamente eso, corriendo los mismos prompts de test contra las dos versiones y comparando los resultados lado a lado.

Agent Skills arrancó como un formato de Anthropic pero no se quedó en eso — hoy es una especificación abierta, y una lista larga de otros agentes y editores ya leen la misma forma de SKILL.md, desde Cursor y GitHub Copilot hasta Gemini CLI y Codex. Una skill escrita para uno de ellos es, en gran parte, una skill escrita para todos.

Esa es la diferencia real con meter todo en el system prompt: una skill es portable de una forma en que las instrucciones específicas de un proveedor nunca lo fueron. También combina naturalmente con MCP — MCP le da al agente el alcance para tocar un sistema, una skill le da el procedimiento para usar ese alcance bien. Escribí el conocimiento una vez, y sigue rindiendo en todos lados donde aparezca un agente que hable el formato.