Aprender

La respuesta corta

La mayoría de los practicantes piensa que un "agent" de Claude Code es "una skill con pasos adicionales". Ese modelo mental está equivocado de una manera útil.

Una skill carga instrucciones en tu conversación actual. Un subagent se ejecuta en su propia ventana de contexto, con su propio system prompt, su propio acceso a herramientas y sus propios permisos, y luego devuelve un resultado. Dónde ocurre el trabajo —y dónde se consumen los tokens— es la diferencia que importa.

Pero "agents" en Claude Code significa al menos cuatro cosas, y confundirlas hace que la función sea difícil de razonar.

Los cuatro significados de "agent"

1. El propio Claude Code es un entorno agentic. La CLI ya tiene herramientas, un bucle de ejecución y la capacidad de planear y actuar en varios pasos. Es agentic antes de que configures nada.
2. Los subagents son la primitiva personalizada dentro del producto. Cuando alguien dice "estoy construyendo un agent", casi siempre se refiere a un subagent: un asistente especializado que se ejecuta en su propia ventana de contexto con un system prompt personalizado, acceso específico a herramientas y permisos independientes.
3. Los agent teams son una capa separada y multi-sesión. Los subagents funcionan dentro de una sola sesión; los agent teams coordinan sesiones separadas. Los teams son instancias independientes de Claude Code que se comunican mediante una lista de tareas compartida y mensajería entre pares. Son experimentales, están deshabilitados por defecto y requieren una bandera de entorno.
4. El Claude Agent SDK es las mismas herramientas y el bucle agent expuesto como una biblioteca programable, fuera de la CLI.

Este artículo trata la capa 2 — los subagents.

Por qué existen los subagents: gestión del contexto

La razón principal es el contexto finito. Cada llamada a una herramienta, cada lectura de archivo, cada análisis parcial entra en la ventana y permanece ahí. A medida que una sesión crece, se llena de trabajo intermedio —ruido que degrada el rendimiento (llámalo rotura de contexto).

Un subagent cambia la forma de ese problema. Pídele que investigue por qué falla una suite de pruebas: lee 20 archivos, busca patrones de error, revisa la configuración —todo en su propia ventana. Tu hilo principal recibe un resumen limpio, no la búsqueda. La documentación oficial lo dice claramente: el trabajo del subagent no consume tu contexto principal.

Tres razones secundarias:

• Especialización — un revisor enfocado con los estándares de tu equipo en su propio system prompt es más fiable que un asistente general que mantiene esos estándares junto con todo lo demás.
• Aplicación de restricciones — especificas exactamente qué herramientas puede usar un subagent. Un agente de investigación de solo lectura que no puede escribir archivos ni ejecutar shell tiene un perfil de riesgo distinto al del asistente principal.
• Control de costos — los subagents pueden ejecutarse en un modelo distinto. Enrutar tareas ligeras a Haiku mientras la sesión principal usa Sonnet es un control de costes real.

Construir un subagent

Un subagent es un archivo Markdown con frontmatter YAML, en .claude/agents/ (proyecto) o ~/.claude/agents/ (personal).

---
name: code-reviewer
description: Reviews code changes for quality, security, and best practices.
 Use proactively after any significant code change.
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, read the changed files and provide
specific, actionable feedback. Focus on what matters. Flag security issues
first, then logic problems, then style.

Los campos:

• name — identificador único, en minúsculas, solo guiones.
• description — el campo más importante. Claude lo lee para decidir si delegar. Escríbelo de forma conductual: qué hace el agent y cuándo usarlo. "Use proactively" es una señal documentada para activarlo sin que se le pida.
• tools — restringe a qué puede acceder el agent. disallowedTools hereda el conjunto de herramientas principal y luego elimina herramientas específicas.
• model — enruta a sonnet, opus, haiku o a un id de modelo completo. Omítelo para heredar el modelo de la sesión principal.
• Body — se convierte en el system prompt del agent. Recibe esto, el directorio de trabajo y nada más desde la sesión principal.

Este revisor puede leer y buscar pero no puede editar ni ejecutar shell —un revisor de solo lectura no puede modificar accidentalmente lo que está revisando.

Agents vs skills: la frontera

Las skills y los subagents viven ambos en .claude/, ambos usan frontmatter y ambos son conjuntos de instrucciones. La diferencia es dónde ocurre el trabajo:

• Una skill se carga en tu conversación actual; sus instrucciones y archivos de referencia pasan a formar parte del contexto activo. Claude las sigue en el mismo hilo, y cada paso se acumula en tu ventana principal.
• Un subagent se ejecuta por separado en su propia ventana de contexto y devuelve un resultado.

Una frase que lo captura:

> Una skill cambia lo que Claude sabe o cómo debería abordar un flujo de trabajo. > Un subagent cambia quién está haciendo el trabajo, en qué contexto y con qué herramientas.

Ejemplo concreto: para aplicar los estándares de revisión de tu equipo a lo largo de toda una sesión, usa una skill. Para revisar 40 archivos en una sola pasada sin llenar tu contexto principal, usa un subagent.

Buenas prácticas

• La description es la interfaz de enrutamiento. Claude lee las descriptions para decidir cuándo delegar — no lee el body primero. Escribe condiciones de activación, no identidad. "You are an expert reviewer with 20 years of experience" pertenece al system prompt, no a la description.
• Restringe las herramientas deliberadamente. Un agent que hereda todas las herramientas es uno sobre el que no puedes razonar cuando falla. Concede solo lo que la tarea necesita. La restricción de herramientas es seguridad y predictibilidad.
• Un trabajo por agent. Una única description para "revisa código, escribe tests, actualiza docs y realiza despliegues" enruta de forma inconsistente. Tres archivos estrechos superan a uno amplio. El consenso de la comunidad —colecciones de 100+ subagents estrechos— apunta lo mismo: muchos agents enfocados rinden más que uno generalista.
• Usa model como palanca de costos. haiku en agents rutinarios reduce el coste; opus se justifica en contextos largos y de razonamiento intenso. El valor por defecto (inherit) aplica el modelo más potente a todo, que a menudo es excesivo.

Una nota rápida sobre agent teams

Los agent teams son sesiones independientes de Claude Code coordinadas a través de sesiones separadas mediante una lista de tareas compartida y mensajería entre pares. Son experimentales, están deshabilitados por defecto y consumen muchos más tokens (cada compañero tiene su propia ventana de contexto facturada).

La señal práctica: mientras tus subagents te informen a ti y no necesiten hablar entre sí, no necesitas agent teams. El momento en que uno necesita pasar hallazgos a otro es cuando la actualización justifica su coste.

Cuando los subagents no son la herramienta correcta

La propia guía de Anthropic: encuentra la solución más simple y solo aumenta la complejidad cuando sea necesario.

Evita un subagent cuando:

• La tarea es puntual — el sobrecoste de autoría (nombrar, description, herramientas, pruebas, mantenimiento) solo compensa para flujos recurrentes.
• El contexto no es el problema — si el trabajo es ligero, un prompt bien escrito en la sesión principal es más rápido y fácil de depurar.
• Te atrae la trampa del monolito — un agent que cubre investigación, implementación, revisión y documentación es inatestable y se selecciona de forma inconsistente.

Conclusión

Los subagents son una herramienta de gestión de contexto y un límite de ejecución, no una mejora de capacidad per se. Un solo agent configurado con cuidado —una description enfocada, un conjunto de herramientas restringido, una tarea clara— es un trabajo razonable de una tarde. La complejidad puede crecer a partir de ahí, pero no tiene por qué empezar por ahí.

---

Fuentes primarias: la documentación de Claude Code sobre subagents y agent teams, y la guía de Anthropic sobre ingeniería de contexto. Definiciones y estado experimental verificadas contra la documentación oficial el 2026-08-07.