← Volver al listado de tecnologías ← Índice de Claude Code

Cap 9: Orchestration Workflow

2 de marzo de 2026 Por: Artiko

claude-codeorchestrationworkflowarquitectura

Punto de entrada → Agent → Conocimiento

Antes se hablaba de tres sistemas separados (Command, Agent, Skill). Hoy los comandos personalizados se fusionaron con las skills: .claude/commands/review.md y .claude/skills/review/SKILL.md generan ambos /review y comparten el mismo frontmatter. Ante colisión de nombre, gana la skill. La URL /docs/en/slash-commands sirve hoy la página «Extend Claude with skills».

Lo que queda son dos piezas reales de orquestación: skills (conocimiento y flujos invocables) y subagentes (ejecutores con ventana de contexto propia).

flowchart TD
    C["Punto de entrada<br/>(/review — skill o command, mismo frontmatter)"]
    A["Agent<br/>(ejecutor especializado, contexto aislado)"]
    S["Skills del agente<br/>(conocimiento contextual)"]
    C --> A --> S

Punto de entrada: el usuario invoca /nombre — define QUÉ hacer
Agent: se lanza un subagente especializado — define QUIÉN lo hace
Skills: se carga conocimiento contextual — define CÓMO hacerlo

Ejemplo completo: Workflow de review

Antes de construir un workflow desde cero conviene saber que existe la skill incluida /code-review, y que el patrón canónico de cierre de una tarea es la revisión adversarial del diff en contexto fresco: un subagente que no escribió el código revisa el diff contra el plan.

Advertencia documentada: «A reviewer prompted to find gaps will usually report some, even when the work is sound… Chasing every finding leads to over-engineering». Por eso hay que indicarle explícitamente al revisor que solo marque gaps que afecten corrección o requisitos declarados.

1. Punto de entrada

<!-- .claude/commands/review.md  (equivalente: .claude/skills/review/SKILL.md) -->
---
description: "Review completo del diff actual contra el plan"
---

Ejecuta un review del diff actual.
Usa el agente code-reviewer para analizar los cambios.
Marca únicamente los hallazgos que afecten corrección o requisitos declarados.

Ambos archivos producen /review y aceptan el mismo frontmatter; si existieran los dos, prevalece el de .claude/skills/.

2. Agent (ejecutor)

<!-- .claude/agents/code-reviewer.md -->
---
name: code-reviewer
description: "Revisa código enfocándose en calidad y seguridad"
tools: ["Read", "Grep", "Glob", "Bash"]
model: inherit
effort: xhigh
background: true
isolation: true
permissionMode: default
disallowedTools: ["Bash(git push *)"]
skills: ["code-style", "security-rules"]
maxTurns: 15
---

Eres un revisor de código senior. Analiza el diff del trabajo actual.
Para cada archivo modificado, verifica las reglas cargadas en tus skills.
Genera un reporte con hallazgos categorizados por severidad.

Campos del frontmatter de subagente relevantes para orquestación:

Campo	Qué controla
`model`	Default `inherit`. Acepta alias `sonnet \| opus \| haiku \| fable` o un ID completo (`claude-opus-4-8`, `claude-sonnet-5`)
`background`	Ejecución en segundo plano
`isolation`	Aislamiento de la ejecución
`effort`	Nivel de esfuerzo del subagente (`low \| medium \| high \| xhigh \| max`)
`permissionMode`	`default` (alias `manual`), `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`
`tools` / `disallowedTools`	Herramientas disponibles / bloqueadas
`mcpServers`, `hooks`, `memory`	Servidores MCP, hooks y memoria propios del agente
`initialPrompt`	Prompt inicial que recibe el agente

Los subagentes de plugin ignoran por seguridad hooks, mcpServers y permissionMode.

`tools` no es una frontera de seguridad

Recortar tools en el agente de review no crea un límite de seguridad: «subagents run in the same process as the parent session and use the same sandbox configuration». Su valor real es aislamiento de contexto y restricción de herramientas para reducir ruido y errores, no contención.

Para prohibir un subagente de verdad se usa el sistema de permisos: Agent(NombreAgente) en deny.

Detalle importante: en subagentes el campo tools sí funciona como whitelist; en cambio allowed-tools de una skill no restringe nada, solo pre-aprueba.

3. Skills (conocimiento)

Una skill sin description no se puede enrutar: es justamente el texto que dispara su carga.

<!-- .claude/skills/code-style/SKILL.md -->
---
name: code-style
description: "Reglas de estilo de código del proyecto: tamaño de funciones, nombres, tipado e imports"
when_to_use: "Al escribir o revisar código TypeScript del repositorio"
---

# Estilo de Código
- Funciones < 50 líneas
- Nombres descriptivos en camelCase
- No usar any en TypeScript
- Imports ordenados

<!-- .claude/skills/security-rules/SKILL.md -->
---
name: security-rules
description: "Reglas de seguridad para revisión de código: secretos, validación, SQL y salida HTML"
when_to_use: "Durante revisiones de código o al tocar autenticación, queries o renderizado"
disable-model-invocation: false
disallowed-tools: ["Bash(git push *)"]
---

# Reglas de Seguridad
- No hardcodear secretos
- Validar inputs de usuario
- Usar prepared statements para SQL
- Sanitizar outputs HTML

Campos del frontmatter de skill que afectan la orquestación (todos opcionales; solo description es recomendado):

Campo	Qué hace
`description`	Texto que decide si la skill se enruta. Junto con `when_to_use` se trunca a 1.536 caracteres en el listado
`when_to_use`	Condición explícita de activación
`disable-model-invocation`	`true` = invocación solo manual, el modelo no la dispara
`allowed-tools`	PRE-APRUEBA herramientas durante el turno que invoca la skill; no restringe, y caduca con el siguiente mensaje del usuario
`disallowed-tools`	Sí restringe: bloquea herramientas
`model`, `effort`	Modelo y esfuerzo con los que corre la skill
`context`	Ejecución en fork de contexto
`agent`	Delegar la skill a un subagente
`hooks`	Hooks asociados a la skill

Agent skills vs Skills

Agent skills (precargados)

Se definen en el frontmatter del agente con skills:. Se cargan cuando el agente arranca:

---
skills: ["code-style", "testing-conventions"]
---

El agente siempre tiene disponible ese conocimiento desde el primer mensaje.

Skills on-demand

Se activan cuando Claude detecta relevancia o el usuario las invoca. No es cierto que cuesten cero: su metadata está siempre en contexto (es lo que dispara el enrutamiento). Lo que se difiere es el cuerpo.

Diseño de workflows

Principios

Separación de responsabilidades: cada componente tiene un rol claro
Composabilidad: agentes y skills se combinan libremente
Especialización: agentes enfocados en una tarea específica
Reutilización: skills compartidas entre múltiples agentes
Economía: el multi-agente se paga en tokens, no es gratis

La economía del multi-agente

Cifras medidas por Anthropic:

Un agente usa ~4x más tokens que una interacción de chat.
Un sistema multi-agente usa ~15x más tokens.
El uso de tokens explica el 80% de la varianza de desempeño (con llamadas a herramientas y elección de modelo, el 95%).

De ahí dos reglas prácticas:

Multi-agente solo si el valor de la tarea paga el sobrecoste.
Subir de modelo rinde más que duplicar el presupuesto de tokens.

Antipatrón explícito: multi-agente en tareas donde todos los agentes necesitan el mismo contexto o hay fuertes interdependencias — «como la mayoría de tareas de código». Los agentes tienen dificultad para coordinarse y delegar en tiempo real.

Patrón válido: cuando la tarea se paraleliza en direcciones independientes y los requisitos de información exceden una sola ventana de contexto.

Ejemplo: Workflow de feature completa

El fan-out que sigue es didáctico, pero cae justo en el antipatrón: planning, coding, testing y review comparten el mismo contexto y están fuertemente encadenados. En un caso real conviene ejecutarlo como secuencia en una sola sesión, delegando en subagentes solo las partes realmente independientes (investigación, revisión adversarial).

flowchart TD
    CMD["/implement-feature 'agregar autenticación'"]
    P[planning-agent]
    C[coding-agent]
    T[testing-agent]
    R[review-agent]
    SP["skills: architecture<br/>project-conventions"]
    SC["skills: code-style<br/>security-rules"]
    ST["skills: testing-conventions"]
    SR["skills: code-style<br/>security-rules"]
    CMD --> P --> SP
    CMD --> C --> SC
    CMD --> T --> ST
    CMD --> R --> SR

Límites operativos vigentes

Antes de diseñar un fan-out hay que conocer el modo de ejecución por defecto y los topes:

Desde v2.1.198, los subagentes corren en background por defecto y heredan la configuración de extended thinking de la sesión principal; /agents ya no abre el asistente interactivo con pestañas Running/Library.
En v2.1.217, los subagentes no generan subagentes anidados por defecto — hay que subir CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH.
Tope de 20 subagentes concurrentes, ajustable con CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.

Es decir: un orquestador no puede apoyarse en que sus agentes deleguen a su vez, ni lanzar fan-outs ilimitados.

Command orquestador

Las instrucciones vagas al subagente («usa el agente coding-agent para implementar») son el antipatrón de delegación documentado: producen trabajo duplicado, huecos y fallos. Cada subagente debe recibir objetivo, formato de salida, guía sobre herramientas y fuentes, y límites claros, más reglas explícitas de escalado de esfuerzo (1 agente y 3-10 llamadas para hechos simples; 10+ subagentes solo para investigación compleja).

Los subagentes devuelven al coordinador resúmenes condensados de típicamente 1.000-2.000 tokens, no su transcripción: el formato de salida hay que declararlo.

<!-- .claude/commands/implement-feature.md -->
---
description: "Implementa una feature completa con plan, código, tests y review"
argument-hint: "descripción de la feature"
---

Para la feature "$ARGUMENTS":

1. Lanza `planning-agent`.
   - Objetivo: producir un plan de implementación para "$ARGUMENTS".
   - Fuentes: solo archivos del repositorio; sin red.
   - Herramientas: Read, Grep, Glob.
   - Límites: no editar archivos; máximo 10 archivos leídos.
   - Salida: lista numerada de pasos con archivos afectados por paso (máx. 400 palabras).

2. Presenta el plan al usuario para aprobación.

3. Implementa el plan en esta sesión (no delegues: los pasos comparten contexto
   y tienen fuertes interdependencias).

4. Lanza `testing-agent`.
   - Objetivo: escribir y ejecutar tests para los cambios del paso 3.
   - Herramientas: Read, Edit, Bash limitado al runner de tests.
   - Límites: no tocar código de producción.
   - Salida: comando ejecutado, exit code y lista de tests fallidos (máx. 300 palabras).

5. Lanza `review-agent` sobre el diff, en contexto fresco.
   - Objetivo: revisión adversarial del diff contra el plan del paso 1.
   - Límites: marca únicamente gaps que afecten corrección o requisitos
     declarados; no propongas refactors ni mejoras opcionales.
   - Salida: hallazgos con severidad, archivo y línea (máx. 300 palabras).

6. Presenta un resumen de todos los cambios con la evidencia de tests del paso 4.

Escalado de esfuerzo: para cambios de una sola frase, salta los pasos 1 y 2.

Flujo de datos

sequenceDiagram
    actor U as Usuario
    participant CM as Skill /review
    participant CL as Claude
    participant AG as code-reviewer (Agent)
    participant SK as Skills

    U->>CM: /review
    CM->>CL: Define la tarea
    CL->>AG: Lanza subagente (background por defecto)
    AG->>SK: Carga code-style, security-rules
    AG->>AG: Ejecuta Read, Grep, Bash
    AG->>AG: Aplica reglas de skills
    AG-->>CL: Retorna resumen condensado (~1.000-2.000 tokens)
    CL-->>U: Presenta resultado

Cuándo usar orquestación

Situación	Solución	Coste relativo
Tarea simple y directa	Solo CLAUDE.md	1x
Tarea repetible	Skill (o command, mismo sistema)	1x
Tarea que necesita aislamiento de contexto	Agent	~4x
Conocimiento reutilizable	Skill	1x
Investigación paralelizable en direcciones independientes	Varios agentes	~15x
Todos los agentes necesitan el mismo contexto	No usar multi-agente	—

Cómo se Cargan las Skills — Implementación Real

La mayoría de documentación explica QUÉ son las skills. Esta sección explica CÓMO las carga Claude Code internamente.

Divulgación progresiva (tres niveles)

Una skill no se concatena entera al system prompt al arrancar. Una skill es un directorio con SKILL.md como entrypoint obligatorio más archivos opcionales (reference.md, examples/, scripts/), y se carga en tres niveles:

Metadata siempre en contexto: solo name + description/when_to_use están en el system prompt desde el inicio. Es lo que permite enrutar la skill, y se trunca a 1.536 caracteres en el listado.
Cuerpo bajo demanda: el contenido de SKILL.md se carga cuando la skill se invoca — y permanece en contexto en los turnos siguientes, así que es un coste recurrente, no un pago único.
Archivos de apoyo: reference.md, examples/, scripts/ solo se leen si SKILL.md los referencia.

De ahí la regla de enrutamiento: CLAUDE.md para lo que aplica siempre; skills para conocimiento de dominio o flujos ocasionales, que cargan bajo demanda «without bloating every conversation».

Precargados vs on-demand

flowchart TD
    A[Agente inicia] --> B{¿Tiene skills en frontmatter?}
    B -->|Sí| C["Leer archivos SKILL.md<br/>de cada skill listado"]
    B -->|No| D[Context base del agente]
    C --> E[Cuerpo disponible desde el primer mensaje]
    D --> E
    E --> F[Agente listo para recibir mensajes]

    G[Sesión activa] --> H{"¿Usuario invoca /skill-name<br/>o el modelo la enruta?"}
    H -->|Sí| I[Leer SKILL.md on-demand]
    I --> J["Cuerpo entra al contexto<br/>y permanece en turnos siguientes"]
    H -->|No| K["Coste mínimo permanente:<br/>metadata en el system prompt"]

Skills precargadas vs on-demand

Característica	Precargada (`skills:` en frontmatter)	On-demand
Disponibilidad	Desde el primer mensaje	Solo cuando se activa
Costo en tokens	Cuerpo completo siempre presente	Metadata siempre (hasta 1.536 caracteres por skill en el listado); cuerpo completo solo al invocarse, y permanece después
Cuándo usarla	Reglas críticas que siempre aplican	Conocimiento situacional
Ejemplo	code-style, security-rules	framework-specific, migrations

Impacto en tokens

Una skill de 200 líneas ocupa aproximadamente 400 tokens de contexto. Con 5 skills precargadas son unos 2.000 tokens consumidos antes de que el agente haga cualquier cosa.

<!-- Agente con 5 skills precargadas de 200 líneas c/u -->
---
skills: ["code-style", "security-rules", "testing", "architecture", "api-conventions"]
---

Overhead: ~2.000 tokens por cada llamada al agente, independientemente de si usa esas skills. Con skills on-demand, ese overhead baja al listado de metadata, pero no a cero.

Precedencia entre skills

No existe una regla documentada de «gana la última declarada en skills: [...]». Lo que sí está documentado es la precedencia por ubicación:

flowchart LR
    E["Enterprise (managed)"] --> P["Personal<br/>~/.claude/skills/&lt;name&gt;/SKILL.md"] --> R["Proyecto<br/>.claude/skills/&lt;name&gt;/SKILL.md"]

Enterprise (managed) > personal ~/.claude/skills/<name>/SKILL.md > proyecto .claude/skills/<name>/SKILL.md.
Las skills de plugin usan namespace plugin-name:skill-name y nunca colisionan.
En monorepos, las skills anidadas se exponen como apps/web:deploy (v2.1.203+).

Si dos skills con nombres distintos dan instrucciones contradictorias, no hay resolución automática: hay que separar contextos mutuamente excluyentes o unificarlas.

Best practices

Skills cortas y focused, no monolíticas:

<!-- ❌ MALO: skill monolítica de 300 líneas -->
skills: ["todo-el-proyecto"]

<!-- ✅ BUENO: skills pequeñas y específicas, cargadas cuando aplican -->
skills: ["code-style"]  # 20 líneas, siempre aplica
# security-rules y testing se activan on-demand según la tarea

Regla de decisión: si una skill aplica a menos del 50% de las tareas del agente, conviene que sea on-demand.

Cuidar name y description: son lo único que decide si la skill se dispara. Dividir SKILL.md cuando crece, y usar disable-model-invocation: true para las que solo deban invocarse a mano.

Siguiente: Workflows de Desarrollo