Skills de IA: deja de meter todo en un SKILL.md gigante

TL;DR: Una Agent Skill es una carpeta con un fichero SKILL.md (instrucciones + recursos) que tu CLI de coding carga solo cuando una tarea la necesita, no en cada prompt. El error de la mayoría no es crear skills, es crearlas como un volcado monolítico de todo lo que el agente "debería saber". Aquí tienes la regla para diseñar una skill que se active cuando toca y no queme tu contexto, con plantilla, árbol de decisión y los casos en los que no compensa.

El instinto: empaquetar todo tu conocimiento en un solo fichero

Llevas semanas pegando las mismas convenciones de tu equipo en cada prompt: el estilo de commits, la estructura de tests, cómo montar un Dockerfile que pasa el linter. La solución obvia es empaquetarlo en una skill. Y ahí viene el error: abres un SKILL.md, vuelcas las 600 líneas de tu guía de estilo dentro y le pones una descripción del tipo "convenciones del proyecto".

Parece lógico. Cuanto más contexto le des al agente, mejor decidirá, ¿no? Técnicamente es justo al revés, y por dos motivos concretos.

Motivo uno: el body se carga entero al activarse. Las skills funcionan por progressive disclosure, un sistema de tres capas. Según la documentación de ingeniería de Anthropic, al arranque el agente solo lee el name y la description de cada skill (unos 100 tokens). El cuerpo completo del SKILL.md no entra en contexto hasta que el agente decide que esa skill es relevante. Si lo activas, se carga todo. Un body de 600 líneas son miles de tokens que se inyectan cada vez que la skill se dispara, compitiendo por el mismo presupuesto que tu código y diluyendo el razonamiento del modelo.

Motivo dos: una descripción vaga no se activa nunca. El description es el único contrato que el agente ve antes de decidir si carga la skill. Si pones "convenciones del proyecto", el modelo no tiene forma de saber cuándo aplica. La skill se vuelve impredecible: a veces se activa donde no debe (ruido en tareas que no le tocaban), y casi nunca cuando realmente hace falta.

Esta es la definición que conviene tener clara: una Agent Skill es un paquete en disco (un SKILL.md con metadatos y procedimiento, más scripts y referencias opcionales) que el agente descubre por su descripción y carga bajo demanda cuando una tarea encaja. No es un prompt largo guardado en un fichero. Esa diferencia es justo lo que estás tirando a la basura cuando la haces gigante.

La regla de decisión: descripción afilada, body lean, detalle en references/

La regla es simple y se moja: si el conocimiento es procedimiento que el agente sigue (cómo hacer X), va en una skill; si es una referencia pesada que solo se consulta a veces, va en references/ y la cargas por demanda; si lo necesitas en cada turno sin excepción, no es una skill, va en tu CLAUDE.md o AGENTS.md.

El truco está en respetar las tres capas en lugar de pelearte con ellas. Cada una tiene un presupuesto:

Capa	Qué carga	Cuándo	Presupuesto
1. Descubrimiento	name + description	Al arranque, para todas las skills	~100 tokens por skill
2. Activación	Cuerpo del SKILL.md	Cuando la tarea encaja con la descripción	<5.000 tokens / <500 líneas
3. Recursos	Ficheros de scripts/, references/, assets/	Solo cuando el body apunta a ellos	Efectivamente ilimitado (está en disco)

Esos límites no son inventados: la especificación abierta de Agent Skills fija el name en un máximo de 64 caracteres (minúsculas, números y guiones) y el description en 1.024 caracteres, y recomienda mantener el body por debajo de 500 líneas. Estimaciones independientes apuntan a que repartir el conocimiento en estas capas, en vez de un único prompt gigante, recorta el consumo de tokens en torno a un 40% a complejidad de tarea similar (es una estimación de un análisis técnico de terceros, no un número oficial; tómalo como orden de magnitud). Si vienes de pelearte con el coste de contexto, esto conecta directo con la idea de darle memoria a tu agente sin inflar el contexto: el problema de fondo es el mismo, qué entra en la ventana y qué se queda fuera.

El artefacto: plantilla de SKILL.md mínima y reutilizable

Esta es la estructura que copias mañana. El body manda al agente a leer detalle solo cuando lo necesita, en lugar de tragárselo entero:

---
name: react-testing
description: Escribe y arregla tests de componentes React con Testing Library y Vitest. Úsala cuando el usuario pida crear, revisar o depurar tests de componentes, hooks o interacciones de UI en el frontend.
---

# Tests de componentes React

## Cuándo aplicar
Tareas de testing de UI: componentes, hooks, eventos de usuario.
No usar para tests de backend ni de integración E2E.

## Procedimiento
1. Usa `screen.getByRole` antes que `getByTestId`.
2. Envuelve interacciones en `userEvent`, no `fireEvent`.
3. Para casos complejos de mocking, lee `references/mocking.md`.

## Comando de verificación
Ejecuta exactamente: `npm run test -- --run`

Fíjate en tres cosas. La description dice qué hace y cuándo usarla, en tercera persona: la guía oficial de Claude insiste en el punto de vista en tercera persona porque la descripción se inyecta en el system prompt y la inconsistencia rompe el descubrimiento. El body es corto y delega el mocking complejo a un fichero aparte. Y el comando de verificación es literal, para que el agente no improvise flags.

La estructura de carpetas que acompaña es predecible y reutilizable:

react-testing/
├── SKILL.md          # Metadatos + procedimiento (lean)
├── references/       # Detalle pesado: mocking.md, patrones avanzados
├── scripts/          # CLIs pequeños que el agente ejecuta
└── assets/           # Plantillas, configs base

Mantenla agnóstica del CLI

El formato SKILL.md es idéntico entre herramientas; lo único que cambia es dónde la colocas. Por eso una skill bien hecha vale en Claude Code, Codex y Gemini CLI sin reescribir nada, algo que ya cubrimos al hablar de cómo usar las mismas skills en Codex y Cursor. La tabla de rutas:

CLI	Ruta personal	Ruta de proyecto
Claude Code	~/.claude/skills/	.claude/skills/
Codex CLI	.agents/skills/
Gemini CLI	.gemini/skills/

Las rutas las recoge un análisis del patrón de progressive disclosure; revisa la doc de tu CLI por si tu versión cambia la convención. La regla práctica para no atarte: no metas en el body instrucciones específicas de un agente ("usa la herramienta Bash de Claude Code"); describe la acción, no la herramienta concreta.

¿Esto debería ser una skill? Árbol de decisión

• ¿Lo necesitas en cada turno, sin excepción? → No es skill. Va en CLAUDE.md / AGENTS.md. Aquí ayuda revisar patrones para tu CLAUDE.md.
• ¿Es procedimiento que se activa por intención (testing, formato, un flujo concreto)? → Skill. Es el caso ideal.
• ¿Necesitas ejecutar una herramienta externa con estado (una API, una DB en vivo)? → Probablemente un servidor MCP encaja mejor; la skill aporta el "cómo", no la ejecución con estado.
• ¿Es conocimiento de un solo uso para esta tarea? → Déjalo en el prompt. Crear una skill que no vas a reutilizar es trabajo "por si acaso".

Cuándo NO aplica (y los riesgos que nadie te cuenta)

Las skills no son la respuesta a todo, y dos matices honestos lo dejan claro.

El anti-patrón silencioso: skills que se cargan siempre. Si tu descripción es tan amplia que la skill se activa en casi cualquier tarea, has reinventado el prompt gigante por la puerta de atrás. Una skill grande activada constantemente quema más tokens que el contexto repetido que querías evitar, y eso impacta directo en tu factura, un tema que conecta con elegir tu modelo por coste real. El antídoto es la misma disciplina de toda buena arquitectura: una skill, una responsabilidad clara, como en el principio de separación de responsabilidades. Pequeñas y activadas por intención, no enormes y siempre presentes.

El riesgo de supply chain. Una skill de terceros es código que corre con los permisos de tu agente: ficheros, red, secretos. No es un detalle teórico. Un estudio reciente sobre skills de comunidad encontró una tasa de vulnerabilidad del 26,1% en 42.447 skills analizadas, incluyendo prompt injection escondido en los propios ficheros. La regla mínima: instala solo skills auditadas, fija versiones y no le des secretos al agente por defecto. Crear las tuyas propias, además de reutilizables, es la forma más segura de empezar.

Las skills tampoco sustituyen un buen ejemplo práctico cuando el conocimiento es muy específico de un dominio. Si tu flujo es, por ejemplo, extraer y preparar documentos, la skill encapsula el procedimiento pero el grueso técnico sigue viviendo en tu pipeline, como en el procesamiento de PDFs para IA: la skill dice "cómo", tu código hace el trabajo pesado.

Preguntas frecuentes

¿En qué se diferencia una skill de un MCP server?

Una skill inyecta conocimiento procedimental (cómo resolver algo) y se carga por demanda; un servidor MCP expone herramientas que ejecutan acciones y devuelven resultados. La skill prepara al agente, el MCP actúa. Para conocimiento reutilizable sin estado, la skill es más ligera; para integrar un sistema externo con estado, el MCP encaja mejor.

¿Cuánto debe medir el cuerpo del SKILL.md?

La especificación recomienda mantener el body por debajo de unas 500 líneas o aproximadamente 5.000 tokens, porque se carga entero al activar la skill. Todo lo que supere ese límite debería moverse a la carpeta references/, que el agente lee solo cuando las instrucciones del body lo indican.

¿Una skill escrita para Claude Code funciona en Codex o Gemini CLI?

Sí, el formato SKILL.md es compatible en lo esencial entre herramientas, aunque cada CLI puede añadir campos propietarios o comportamientos divergentes. Lo único que cambia, en lo básico, es la ruta donde la colocas. Para que sea portable de verdad, evita referenciar herramientas específicas de un CLI dentro del body y describe las acciones de forma neutral.

El takeaway

Crear una skill no es volcar tu conocimiento en un fichero, es decidir qué entra en contexto y cuándo. La descripción es el contrato de activación: si es vaga, la skill no existe; si es precisa, el agente la encuentra. El body es presupuesto de tokens que pagas cada vez que se activa: mantenlo lean y manda el detalle a references/. Una skill pequeña, con una responsabilidad clara y una descripción afilada, le ahorra a tu agente exactamente el ruido que un prompt gigante le metería. La pregunta que conviene hacerse antes de escribir la primera línea no es "¿qué más le cuento?", sino "¿qué necesita leer solo cuando le hace falta?".