Skills y subagentes: el ladrillo base de los agentes IA

TL;DR: Las skills empaquetan pasos, checks y formato en una unidad reutilizable que cualquier harness moderno (Claude Code, Codex, OpenClaw) entiende. Combinadas con subagentes, convierten tareas repetidas en piezas auditables: dejas de copiar prompts entre proyectos y empiezas a versionar workflows como código. En este artículo verás la anatomía de una skill, cuándo conviene un subagente en su lugar y qué cambia al llevarlas a producción.

¿Por qué las skills ya no son un extra?

Durante 2025 las skills eran un detalle de Claude Code. En 2026 el panorama cambió: Codex incorporó skills experimentales, OpenClaw las soporta nativamente y los nuevos harnesses como oh-my-openagent tratan skills y subagentes como ciudadanos de primera clase. El estándar SKILL.md ya funciona como interfaz común entre herramientas.

El efecto práctico es simple: si escribes una skill bien hecha hoy, sirve mañana en otro harness sin reescribirla. Eso convierte el trabajo de afinar prompts en algo capitalizable, no en arena que se cuela entre los dedos al cambiar de cliente o de modelo.

Hay un cambio cultural detrás. Antes el debate giraba en torno a qué prompt uso. Ahora gira en torno a qué tareas vale la pena empaquetar. Las skills son la respuesta operativa a esa segunda pregunta.

¿Qué es una skill?

Una skill es un archivo Markdown autocontenido que describe cómo ejecutar una tarea concreta, incluyendo pasos, validaciones y formato de salida esperado. El harness la carga bajo demanda (progressive disclosure) cuando detecta que el contexto la requiere, no en cada turno.

La diferencia clave con un prompt suelto es que la skill vive en disco, se versiona en git y puede invocarse con un nombre estable. No depende del estado de la conversación ni de que recuerdes su redacción exacta.

¿Qué es un subagente?

Un subagente es un agente secundario que el harness lanza con un contexto aislado para resolver una subtarea específica y devolver solo el resultado relevante. No hereda tu historial ni contamina el contexto principal al volver.

Skills y subagentes son piezas distintas pero complementarias. Una skill describe cómo hacer algo. Un subagente describe quién lo hace en una sesión aparte.

Anatomía de una skill bien hecha

La estructura mínima que funciona en Claude Code, Codex y OpenClaw es la misma: frontmatter YAML con metadata y cuerpo Markdown con instrucciones. Ejemplo de una skill para revisar pull requests de Python:

---
name: python-pr-review
description: Revisa un PR de Python aplicando checks de tipado, tests y estilo antes de aprobar
type: review
---

## Pasos

1. Lee el diff completo con `git diff main...HEAD`.
2. Verifica que cada función nueva tenga type hints.
3. Comprueba que hay tests para cada rama lógica añadida.
4. Ejecuta `ruff check .` y `mypy .` y reporta errores con línea.

## Formato de salida

- **Veredicto**: APROBADO | CAMBIOS PEDIDOS | RECHAZADO
- **Bloqueantes**: lista de issues que impiden merge
- **Sugerencias**: mejoras opcionales

Tres cosas hacen que esta skill sea reutilizable de verdad:

• Pasos numerados: el agente no improvisa el orden, lo que reduce variabilidad entre ejecuciones.
• Comandos explícitos: ruff, mypy, git diff. Si el harness tiene tool use, sabe exactamente qué ejecutar.
• Formato de salida fijo: el resultado es parseable y comparable entre PRs.

Fíjate en lo que no hay: lenguaje motivacional, ejemplos largos, ni explicaciones de por qué importa cada paso. Una skill no es documentación, es un contrato de ejecución.

Skills vs subagentes: cuándo usar cada uno

La regla práctica que aplico en mi flujo diario:

Situación	Skill	Subagente
Tarea corta, contexto compartido necesario	Sí	No
Búsqueda que devuelve mucho ruido	No	Sí
Pasos repetibles con formato fijo	Sí	No
Tareas paralelas independientes	No	Sí
Refactor que toca varios archivos	Sí	Opcional
Investigación cross-repo	No	Sí

El criterio simple: si necesitas el resultado dentro de tu contexto principal, skill. Si necesitas aislar para no contaminar tu sesión, subagente. Muchas tareas combinan ambos: una skill que internamente lanza subagentes para fases pesadas.

Para profundizar en cómo organizar tu colección y decidir qué tareas merecen pieza propia, hay un análisis previo sobre construir tu librería de Claude Skills que complementa esta anatomía.

Implementación paso a paso

Convertir una tarea repetida en skill sigue siempre el mismo patrón. Lo aplico cada vez que detecto que estoy explicándole al agente el mismo procedimiento por tercera vez.

1. Identifica la tarea: que sea repetible, con entrada y salida claras. Si no sabes describirla en una frase, todavía no está madura para skill.
2. Documenta los pasos manualmente: escribe el procedimiento como si se lo explicaras a alguien nuevo. Sin abstracciones.
3. Define el formato de salida: estructura fija, secciones nombradas, campos esperados.
4. Crea el archivo: .claude/skills/nombre-skill.md con frontmatter name, description, type.
5. Pruébala en frío: en una sesión nueva, sin contexto previo, pídele al agente que la aplique a un caso real.
6. Itera el wording: cada vez que el agente falle, ajusta los pasos o el formato. No la descripción.

El paso 5 es el que más se salta la gente. Si tu skill solo funciona cuando tu sesión ya tiene el contexto cargado, no es una skill, es un atajo personal. Para skills funcionando bien, conviene tener hooks que ejecuten checks automáticos sin depender de que el agente recuerde lanzarlos.

En producción

Llevar skills a un equipo introduce problemas que no aparecen en uso individual. Estos son los que me he encontrado:

Versionado y compatibilidad. Una skill que funciona con Opus 4.7 puede degradarse en Sonnet 4.6 si depende de razonamiento extendido. Anota en el frontmatter qué modelo testaste y cuándo. Cuando cambie el modelo, vuelve a validar antes de asumir que sigue funcionando.

Coste real. Cada skill cargada suma tokens al system prompt. Con 30-40 skills activas estás añadiendo 5-10k tokens por turno, aunque el harness use progressive disclosure. Audita qué skills están realmente activas y elimina las que no usas hace meses.

Conflictos entre skills. Si tienes python-pr-review y strict-type-review, el agente puede aplicar las dos a la vez y generar salidas duplicadas. Define qué skills son mutuamente excluyentes en su descripción.

Drift silencioso. Una skill que ayer funcionaba puede romperse porque cambió la API de una herramienta que invoca. Sin tests, no te enteras hasta que un PR sale mal revisado. Una opción ligera es ejecutar un caso canónico semanalmente y comparar el output con uno fijado.

El aislamiento también importa. Si tu skill modifica archivos, ejecutarla dentro de un sandbox para agentes evita que un error contamine tu rama principal. Y para integraciones con servicios externos, conviene revisar prácticas de secret scanning en GitHub MCP antes de que una skill suba credenciales por descuido.

Errores comunes y depuración

Error: La skill se ignora aunque la nombres explícitamente. Causa: el frontmatter no tiene name o la descripción es genérica y el harness no la indexa bien. Solución: asegúrate de que description menciona palabras concretas de la tarea, no metafrases tipo "ayuda con código".

Error: La salida varía entre ejecuciones con el mismo input. Causa: el formato de salida está descrito en prosa, no como estructura. Solución: usa headers Markdown fijos (## Veredicto, ## Bloqueantes) y bullets con nombre de campo.

Error: Funciona en local pero falla cuando otro miembro del equipo la usa. Causa: depende de herramientas o paths específicos de tu máquina. Solución: lista en la skill las dependencias necesarias (ruff, mypy, etc.) y haz que falle pronto si no están instaladas.

Error: La skill aplica pasos que ya no son válidos. Causa: drift por cambios externos sin revisión. Solución: anota fecha de última revisión en el frontmatter y agenda revisión trimestral.

Preguntas frecuentes

¿Cuántas skills es razonable tener?

Entre 10 y 25 skills cubren la mayoría de tareas repetidas de un developer individual. Pasar de 40 suele indicar que estás convirtiendo en skill cosas que solo usas una vez al mes. Mejor borrar y recrear cuando vuelvan a hacer falta.

¿Una skill puede llamar a otra?

Depende del harness. Claude Code y OpenClaw permiten referenciar otras skills por nombre dentro del cuerpo. Codex todavía no compone skills automáticamente. Si necesitas composición fiable, modela las dependencias como pasos explícitos dentro de la skill principal.

¿Skills o subagentes para tareas largas?

Subagentes. Una tarea de varias horas con búsquedas, lecturas y razonamiento profundo contamina tu contexto principal si la ejecutas inline. Lánzala en un subagente que devuelva solo el resultado final estructurado, y deja la skill como envoltorio que define el formato de invocación.

Cierre

Hemos visto que una skill bien hecha no es un prompt vitaminado, sino una unidad ejecutable con contrato de entrada y salida. La clave está en empaquetar solo lo que repites y en mantenerlo auditable: si dentro de seis meses no entiendes para qué sirve una skill, bórrala. Los subagentes complementan ese patrón cuando el aislamiento de contexto importa más que la compartición de estado.

Mi recomendación: empieza con tres skills (review, debugging, setup) y nada más. Cuando una de ellas falle en producción, ajústala antes de crear la cuarta. El siguiente paso natural es definir una política clara de qué promover a memoria persistente y qué dejar como skill, algo que tocaré en próximas entradas.

¿Has empezado a versionar tus skills o sigues con prompts sueltos? Cuéntamelo en Twitter @sergiomarquezp_.