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

Cap 9: Orchestration Workflow

3 de marzo de 2026 Por: Artiko

claude-codeorchestrationworkflowarquitectura

Patrón Command → Agent → Skill

La arquitectura de orquestación de Claude Code sigue un patrón de tres niveles:

flowchart TD
    C["Command\n(punto de entrada del usuario)"]
    A["Agent\n(ejecutor especializado)"]
    S["Skill\n(conocimiento contextual)"]
    C --> A --> S

Command: el usuario invoca /nombre — define QUÉ hacer
Agent: se lanza un agente especializado — define QUIÉN lo hace
Skill: se inyecta conocimiento contextual — define CÓMO hacerlo

Ejemplo completo: Workflow de review

1. Command (punto de entrada)

<!-- .claude/commands/review.md -->
---
description: "Review completo del PR actual"
---

Ejecuta un review completo del PR actual.
Usa el agente code-reviewer para analizar los cambios.

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: sonnet
skills: ["code-style", "security-rules"]
maxTurns: 15
---

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

3. Skills (conocimiento)

<!-- .claude/skills/code-style/SKILL.md -->
# 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 -->
# Reglas de Seguridad
- No hardcodear secretos
- Validar inputs de usuario
- Usar prepared statements para SQL
- Sanitizar outputs HTML

Agent skills vs Skills

Agent skills (precargados)

Se definen en el frontmatter del agente con skills:. Se cargan automáticamente cuando el agente inicia:

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

El agente SIEMPRE tiene acceso a estas instrucciones.

Skills on-demand

Se activan cuando Claude detecta relevancia o el usuario los invoca. No ocupan contexto hasta que se necesitan.

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 compartidos entre múltiples agentes

Ejemplo: Workflow de feature completa

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

Command orquestador

<!-- .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. Usa el agente planning-agent para crear un plan de implementación
2. Presenta el plan al usuario para aprobación
3. Usa el agente coding-agent para implementar
4. Usa el agente testing-agent para escribir y ejecutar tests
5. Usa el agente review-agent para un review final
6. Presenta un resumen de todos los cambios

Flujo de datos

sequenceDiagram
    actor U as Usuario
    participant CM as Command
    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 agente
    AG->>SK: Carga code-style, security-rules
    AG->>AG: Ejecuta Read, Grep, Bash
    AG->>AG: Aplica reglas de skills
    AG-->>CL: Retorna reporte
    CL-->>U: Presenta resultado

Cuándo usar orquestación

Situación	Solución
Tarea simple y directa	Solo CLAUDE.md
Tarea repetible	Command
Tarea que necesita aislamiento	Agent
Conocimiento reutilizable	Skill
Workflow complejo multi-paso	Command → Agent → Skill

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

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

Mecanismo de inyección

Los skills no son módulos importados ni plugins. Son texto Markdown que se concatena al system prompt del agente antes de que procese cualquier mensaje:

El contenido de cada SKILL.md se lee del disco
Se agrega al contexto del agente como instrucciones adicionales
El agente las trata como parte de sus instrucciones base, no como mensajes del usuario

Precargados vs on-demand

flowchart TD
    A[Agente inicia] --> B{¿Tiene skills en frontmatter?}
    B -->|Sí| C[Leer archivos SKILL.md\nde cada skill listado]
    B -->|No| D[Context base del agente]
    C --> E[Concatenar al system prompt]
    D --> E
    E --> F[Agente listo para recibir mensajes]

    G[Sesión activa] --> H{¿Usuario invoca /skill-name\no Claude detecta relevancia?}
    H -->|Sí| I[Leer SKILL.md on-demand]
    I --> J[Inyectar en el contexto actual]
    H -->|No| K[0 tokens consumidos]

Skills precargados vs on-demand

Característica	Precargado (`skills:` en frontmatter)	On-demand
Disponibilidad	Desde el primer mensaje	Solo cuando se activa
Costo en tokens	Siempre presente	0 hasta que se invoca
Cuándo usarlo	Reglas críticas que siempre aplican	Conocimiento situacional
Ejemplo	code-style, security-rules	framework-specific, migrations

Impacto en tokens

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

<!-- Agente con 5 skills precargados 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 esos skills.

Conflictos entre skills

Si dos skills tienen instrucciones contradictorias, prevalece el último cargado (orden de declaración en skills: [...]):

---
# skill-a dice: "usa tabs para indentación"
# skill-b dice: "usa 2 espacios para indentación"
skills: ["skill-a", "skill-b"]  # skill-b gana en este conflicto
---

Best practices

Skills cortos y focused, no monolíticos:

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

<!-- ✅ BUENO: skills pequeños y específicos, cargados 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 un skill aplica a menos del 50% de las tareas del agente, conviene que sea on-demand.

Siguiente: Workflows de Desarrollo