Skills y Subagentes: Deja de Repetir Contexto Cada Sesión
TL;DR: Las skills son bundles reutilizables de instrucciones que un agente carga solo cuando las necesita. Los subagentes delegan tareas caras a un proceso con ventana de contexto propia. Juntos, y con el formato SKILL.md común entre Claude Code y Codex, reemplazan el copy-paste de prompts en cada sesión y mantienen el contexto principal limpio.
Por qué el prompt repetido ya no escala
Cualquier desarrollador que lleve meses trabajando con agentes de código conoce la rutina: abres sesión, pegas el mismo bloque de instrucciones sobre cómo hacer commits, cómo correr los tests, qué convención de nombrado usar. Multiplica eso por cinco agentes distintos en un día y tienes la famosa "rueda de hámster del prompt engineering".
La documentación oficial de Codex y de Claude Code apunta al mismo patrón: empaquetar ese conocimiento en archivos reutilizables que el agente descubre solo cuando son relevantes. No es una moda de una herramienta. Es un estándar abierto que empieza a funcionar cross-platform.
¿Qué es una skill?
Una skill es un bundle de instrucciones, recursos y scripts opcionales que un agente de código carga bajo demanda para completar una tarea concreta. Vive en un directorio con un archivo SKILL.md y un YAML frontmatter con name y description.
La clave es la progressive disclosure: el agente ve al arrancar solo el nombre y la descripción de cada skill disponible. Cuando detecta que una tarea encaja con esa descripción, carga el cuerpo completo. Esto significa que tener 40 skills instaladas cuesta apenas unos cientos de tokens en el contexto, frente a los miles que consumen los servidores MCP cuando cargan todas sus herramientas.
¿Qué es un subagente?
Un subagente es un proceso aislado que el agente principal lanza para una tarea específica, con su propia ventana de contexto y sus propias herramientas. Cuando termina, devuelve un resumen. Lo que vio y leyó durante el camino no contamina el contexto del hilo principal.
El caso típico es explorar una parte del repo para entender cómo está montada una feature: un subagente puede leerse 30 archivos, sintetizar una explicación de 10 líneas y el agente principal solo recibe esa síntesis. Esto es parecido al patrón que explico en cómo eliminar el context drift inflando menos tu CLAUDE.md: delegar la exploración es una de las formas más rentables de proteger la ventana principal.
Skills vs Subagentes vs CLAUDE.md vs MCP
Antes de escribir la primera skill conviene tener claro cuándo usar cada capa. Esta es la regla simple que me funciona:
| Capa | Qué resuelve | Cuándo usarla | Coste de contexto |
|---|---|---|---|
| CLAUDE.md / AGENTS.md | Reglas globales del proyecto | Instrucciones válidas en TODA sesión | Siempre cargado |
| Skill | Workflow reutilizable y puntual | Tareas concretas que se repiten (commit, worktree, refactor) | 50-100 tokens hasta activarse |
| Subagente | Aislar contexto de una tarea cara | Exploración, QA, revisión profunda | Cero en el hilo principal |
| MCP | Conectar herramientas externas | APIs, bases de datos, navegador | Miles de tokens siempre cargados |
La pista práctica: si puedes resolverlo con una skill, no montes un MCP. Si la tarea genera exploración pesada, mándala a un subagente antes de dejar que reviente tu hilo principal.
Anatomía de una skill: el archivo SKILL.md
La estructura mínima es un directorio con el archivo SKILL.md. Según la especificación de Codex y la equivalente en Claude Code, esto es lo que contiene:
# Frontmatter YAML: metadata que el agente ve al arrancar
---
name: conventional-commit
description: Crea un commit siguiendo Conventional Commits tras revisar los cambios staged. Usar cuando el usuario pide "haz un commit" o similar.
allowed-tools: Bash, Read
---
# Cuerpo Markdown: instrucciones que se cargan al activar la skill
Pasos a seguir:
1. Ejecuta `git diff --staged` y analiza los cambios.
2. Determina el tipo (feat, fix, refactor, docs, chore).
3. Genera el mensaje en formato `tipo(scope): descripcion`.
4. Pide confirmacion al usuario antes de ejecutar `git commit`.
La estructura de directorios completa admite más piezas cuando las necesitas:
mi-skill/
├── SKILL.md # Obligatorio: frontmatter + instrucciones
├── scripts/ # Opcional: codigo ejecutable (bash, python)
├── references/ # Opcional: documentacion adicional bajo demanda
└── assets/ # Opcional: plantillas, snippets
El campo description es el más importante. Es lo que decide si el agente activa o no la skill ante un prompt. Escríbelo como si fuera una query de búsqueda: incluye las frases reales que tu equipo usa para pedir esa tarea.
Crear tu primera skill paso a paso
Voy con un caso concreto: empaquetar el workflow de "crear una rama nueva para una feature con un plan numerado". Lo hago cada vez que arranco algo nuevo y siempre le explicaba los mismos pasos al agente.
Paso 1: crea el directorio de skills del proyecto.
# Claude Code busca aqui por defecto en el repo
mkdir -p .claude/skills/nueva-feature
# En Codex la ruta equivalente es ~/.codex/skills o la definida en config
Paso 2: escribe el SKILL.md con description específico.
---
name: nueva-feature
description: Crea una rama feature/NNN-slug y un archivo plans/NNN-slug.md vacio. Usar cuando el usuario dice "empiezo feature X" o "nueva rama para X".
---
# Nueva feature
1. Lista `plans/` y encuentra el mayor numero NNN existente.
2. Incrementa en 1 y usa ese numero.
3. Crea rama `feature/NNN-slug` desde main actualizada.
4. Crea `plans/NNN-slug.md` con plantilla vacia.
5. Confirma al usuario el numero asignado.
Paso 3: prueba la activación. Abre el agente en el repo y escribe "empiezo feature auth-oauth". Si la descripción está bien, el agente debe activar la skill sin que le cuentes los pasos. Si no activa, el description no matchea; ajústalo con las frases reales que usas.
Paso 4: itera. La primera versión rara vez es buena. Cuando notes que el agente se salta un paso, añádelo al cuerpo de la skill. Trátalo como un runbook vivo.
Un caso real: convertir el copy-paste diario en tres skills
En el flujo de trabajo típico de un desarrollador con agentes hay tres bloques que se repiten cada día. Estos son los que me ahorran más fricción convertidos en skills:
/commit: leer diff staged, decidir tipo y scope según Conventional Commits, pedir confirmación antes de ejecutar./review: lanzar un subagente concontext: forkque revise los cambios no committed contra las reglas delCLAUDE.mdy devuelva una lista de issues./test-changed: detectar los archivos cambiados, inferir los tests relacionados y correrlos en modo watch hasta que pasen.
Las tres combinan skill (instrucciones) y subagente (aislamiento de contexto). El patrón lo explico más a fondo en cómo los subagentes convierten un agente en un equipo aplicado a Cursor, pero el mismo mental model aplica a Claude Code y Codex.
En Producción
Pasar de usar skills en proyectos personales a meterlas en un equipo cambia las prioridades. Esto es lo que importa cuando varias personas dependen del mismo conjunto:
- Versionado y revisión: commitea las skills en el repo (
.claude/skills/o equivalente). Trátalas como código: PR review, issues cuando fallan, changelog cuando cambias el comportamiento. - Permisos explícitos: usa el campo
allowed-toolspara pre-aprobar solo lo mínimo. Una skill de commit no necesita acceso a red. Una skill de scraping no debería poder borrar archivos. - Coste de activación: cada skill extra añade tokens al prompt del sistema. En el post sobre cómo reducir el gasto de tokens cubro el cálculo, pero la regla práctica es: si no la has usado en un mes, bórrala.
- Rollback: fija la versión de la skill en tu repo. Si actualizas y rompe,
git revertte devuelve al estado anterior. No dependas de marketplaces externos para workflows críticos. - Observabilidad: mira cuántas veces se activa cada skill. Las que nunca se activan tienen un
descriptionmal escrito o no sirven; las que se activan cuando no toca indican falsos positivos y hay que acotar el description.
Errores comunes y cómo depurarlos
- Error: la skill no se activa nunca. Causa: el
descriptionno contiene las frases que usa el usuario. Solución: reescríbelo incluyendo ejemplos literales ("usar cuando el usuario dice 'haz un commit'"). - Error: la skill se activa cuando no debe y lanza comandos no deseados. Causa: descripción demasiado amplia. Solución: acota el alcance y añade la frase "NO usar para X" al final de la descripción.
- Error: el agente ignora pasos del cuerpo. Causa: instrucciones ambiguas o con condicionales. Solución: reescribe como lista numerada de pasos verificables.
- Error: el subagente devuelve un resumen inútil. Causa: no le diste criterios explícitos de qué reportar. Solución: termina el prompt del subagente con "reporta únicamente X, Y, Z en menos de N líneas".
Un patrón más sutil: las skills auto-generadas a partir de sesiones previas, como las que se describen en AgentHandover, arrastran contexto efímero que no aporta. Revisa siempre a mano lo que genera la máquina antes de commitearlo.
Preguntas frecuentes
¿Las skills funcionan igual en Claude Code y Codex?
El formato SKILL.md es compatible entre ambos y se apoya en el estándar abierto Agent Skills. Las diferencias están en campos extra del frontmatter: Claude Code soporta allowed-tools, model y context: fork, mientras que Codex usa metadatos en agents/openai.yaml. Para skills simples, el mismo archivo funciona sin cambios.
¿Necesito subagentes si ya uso skills?
No siempre. Las skills resuelven el problema de repetir instrucciones. Los subagentes resuelven el problema de consumir tokens en tareas de exploración o QA. Si tu trabajo cabe en una ventana de contexto sin problemas, empieza solo con skills y añade subagentes cuando notes que el hilo principal se satura.
¿Puedo versionar skills entre equipos distintos?
Sí. Commitéalas en el repo del proyecto dentro de .claude/skills/ o equivalente en Codex, y trátalas como cualquier archivo de configuración: revisión por PR, issues cuando fallan, changelog cuando cambian. Esto es lo que diferencia un prompt improvisado de un activo del equipo.
Cierre
El cambio real que introducen skills y subagentes no es tener más botones en el agente, es separar dos capas que antes estaban mezcladas: el conocimiento operativo del equipo y el trabajo concreto de cada sesión. Las skills convierten tus mejores prompts en activos versionables, los subagentes evitan que la exploración se coma tu ventana de contexto, y el formato SKILL.md abierto te libera de apostar todo a un único proveedor.
Si nunca has escrito una, empieza hoy con la más obvia: la skill de commit. En media hora tienes la plantilla y en una semana no volverás a explicarle a ningún agente cómo quieres que haga commits en tu proyecto. El siguiente tema que cubriré es cómo encadenar varias skills en un pipeline multi-agente sin que el planner y el executor se pisen.
¿Has empezado a empaquetar tus workflows en skills o sigues pegando el mismo prompt cada mañana? Cuéntamelo en Twitter @sergiomarquezp_ con el SKILL.md del que más orgulloso estés.