# How to Implement Multi-Agent Orchestration with Claude Code Skills: A Complete Guide

> Master multi-agent orchestration with Claude Code skills. This guide shows you how to build an orchestrator using YAML, Python, and the Agent Workflow Designer. Get started today.

- Repository: [Alireza Rezvani/claude-skills](https://github.com/alirezarezvani/claude-skills)
- Tags: how-to-guide
- Published: 2026-03-09

---

**Multi-agent orchestration with Claude Code skills is implemented by creating an orchestrator agent that coordinates multiple specialist skill packages through structured YAML configurations, validated by the [`agent_orchestrator.py`](https://github.com/alirezarezvani/claude-skills/blob/main/agent_orchestrator.py) utility, using patterns like hierarchical delegation or parallel fan-out defined in the Agent Workflow Designer.**

The **alirezarezvani/claude-skills** repository provides a comprehensive framework for building complex AI workflows through **multi-agent orchestration with Claude Code skills**. This approach allows you to compose specialized agents—such as marketing operations, data engineering, and product management—into cohesive pipelines that handle end-to-end tasks with predictable token budgets and cost controls.

## Architectural Overview of Claude Code Multi-Agent Systems

Claude Code skills are packaged as self-contained **skill folders** that expose Python automation tools, reference guides, and assets. An **orchestrator agent** sits atop these packages and coordinates their execution through standardized contracts.

### The Orchestrator Agent Pattern

The architecture centers on a YAML-defined orchestrator that declares which specialist tools it can invoke. In [`engineering/agent-workflow-designer/SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering/agent-workflow-designer/SKILL.md), the system defines five core patterns: sequential pipeline, parallel fan-out/fan-in, hierarchical delegation, event-driven, and consensus. The orchestrator selects patterns based on task dependency graphs, ensuring optimal execution paths.

Each orchestrator configuration specifies:
- **Tool definitions** using `ToolDefinition` schemas that declare input/output keys and token estimates
- **Pattern selection** determining how agents communicate (e.g., `hierarchical` for manager-worker relationships)
- **State management** through the `AgentHandoff` object, which carries step counters, token budgets, and cost accounting to prevent context bleed

### Core Components: AgentHandoff and Tool Contracts

The `AgentHandoff` structure, defined in the Agent Workflow Designer skill, ensures clean hand-offs between agents. It tracks:
- Current execution step and iteration count
- Remaining token budget via `ContextBudget` classes
- Cost estimation per model invocation

Specialist tools register through strict contracts. The orchestrator passes only required data via `input_key` and `output_key` mappings, enforced by the validation logic in [`engineering-team/senior-prompt-engineer/scripts/agent_orchestrator.py`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering-team/senior-prompt-engineer/scripts/agent_orchestrator.py).

### Error Recovery and Cost Optimization

The orchestration layer includes `with_retry` decorators that implement exponential back-off with optional model fallback. Cost optimization is handled through:
- **Token-budget classes** that cap context windows per agent
- **Cost-estimation routines** in [`agent_orchestrator.py`](https://github.com/alirezarezvani/claude-skills/blob/main/agent_orchestrator.py) that calculate per-run expenses before execution
- **Parallelism controls** using `asyncio` for concurrent agent execution in the parallel fan-out pattern

## Step-by-Step Implementation Guide

Follow these steps to build a production-ready multi-agent orchestration system:

1. **Create an orchestrator YAML** based on [`templates/agent-template.md`](https://github.com/alirezarezvani/claude-skills/blob/main/templates/agent-template.md), declaring the agent name, model (e.g., `sonnet`), pattern, and tool inventory.
2. **Add required tools** by listing skill packages like `marketing-ops`, `data-engineer`, or `product-team` in the `tools` array.
3. **Validate the configuration** by running the CLI validator to check tool registration and detect dependency loops.
4. **Visualize the workflow** to generate ASCII or Mermaid diagrams for documentation and debugging.
5. **Execute the orchestrator** either via CLI for one-off tasks or programmatically using the `HierarchicalOrchestrator` class for integrated applications.
6. **Iterate on the configuration** based on validation warnings regarding duplicated tool names or missing required configuration keys.

## Code Examples

### Defining an Orchestrator Configuration

Create a YAML file at [`agents/orchestrator/cs-multi-orchestrator.yaml`](https://github.com/alirezarezvani/claude-skills/blob/main/agents/orchestrator/cs-multi-orchestrator.yaml):

```yaml
---
name: multi-agent-orchestrator
description: Coordinates marketing, data-engineering and product-team skills to deliver end-to-end campaigns
skills: marketing-ops, data-engineer, product-team
domain: orchestrator
model: sonnet
tools:
  - name: marketing-ops
    description: Router + campaign orchestrator
  - name: data-engineer
    description: Pipeline orchestration for data prep
  - name: product-team
    description: Product backlog alignment
pattern: hierarchical
max_iterations: 20
system_prompt: |
  You are an orchestrator. Decompose the user's request into subtasks, assign each to the most appropriate skill, and synthesize a final answer.
---

```

This template follows the structure defined in [`templates/agent-template.md`](https://github.com/alirezarezvani/claude-skills/blob/main/templates/agent-template.md), establishing a hierarchical pattern where the orchestrator delegates to three specialist domains.

### Validating and Visualizing Workflows

Use the [`agent_orchestrator.py`](https://github.com/alirezarezvani/claude-skills/blob/main/agent_orchestrator.py) utility to validate and diagram your configuration:

```bash

# Validate configuration integrity

python engineering-team/senior-prompt-engineer/scripts/agent_orchestrator.py agents/orchestrator/cs-multi-orchestrator.yaml --validate

# Generate Mermaid flowchart

python engineering-team/senior-prompt-engineer/scripts/agent_orchestrator.py agents/orchestrator/cs-multi-orchestrator.yaml --visualize --format mermaid > workflow.mmd

```

The validation checks for tool registration consistency, required configuration keys, and cyclic dependencies. The visualization outputs a Mermaid diagram showing the flow from user query through tool selection to final answer synthesis.

### Running Hierarchical Orchestration

Execute the orchestrator programmatically using Python:

```python
from pathlib import Path
from engineering.agent_workflow_designer.SKILL import HierarchicalOrchestrator
import yaml

# Load orchestrator configuration

config_path = Path("agents/orchestrator/cs-multi-orchestrator.yaml")
with config_path.open() as f:
    cfg = yaml.safe_load(f)

# Initialize orchestrator

orchestrator = HierarchicalOrchestrator()

# Define complex multi-domain request

request = """
Launch a Q2 product launch campaign that includes:
- Market research (use marketing-ops)
- Data pipeline to ingest social-media metrics (use data-engineer)
- Feature backlog prioritisation (use product-team)
Provide a timeline and cost estimate.
"""

# Execute orchestration

response = orchestrator.run(request)
print(response)

```

The `HierarchicalOrchestrator` class, along with helper constants like `ORCHESTRATOR_SYSTEM` and `SPECIALIST_SYSTEMS`, is defined in [`engineering/agent-workflow-designer/SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering/agent-workflow-designer/SKILL.md). This implementation handles task decomposition, parallel tool execution where possible, and result synthesis.

### Parallel Fan-Out Execution

For tasks requiring concurrent research across multiple domains, use the async parallel pattern:

```python
import asyncio
from engineering.agent_workflow_designer.SKILL import parallel_research

competitors = ["Acme", "BetaCorp", "GammaTech", "DeltaSoft", "Epsilon"]
research_type = "cloud-security"

# Execute parallel fan-out across all competitors

result = asyncio.run(parallel_research(competitors, research_type))

print("Combined synthesis:")
print(result["synthesis"])

```

This demonstrates the **Parallel Fan-out/Fan-in** pattern (Pattern 2 in the SKILL file), which uses `asyncio` to fire multiple agent instances concurrently and aggregates results through a synthesis step.

## Key Files and References

The multi-agent orchestration framework relies on these specific files in the **alirezarezvani/claude-skills** repository:

- [`engineering/agent-workflow-designer/SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering/agent-workflow-designer/SKILL.md) – Design guide containing all five orchestration patterns, Python snippets, `AgentHandoff` schema, budgeting logic, and implementation pitfalls.
- [`engineering-team/senior-prompt-engineer/scripts/agent_orchestrator.py`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering-team/senior-prompt-engineer/scripts/agent_orchestrator.py) – CLI tool for parsing orchestrator YAML, validating configurations, detecting loops, visualizing workflows, and estimating token costs.
- [`templates/agent-template.md`](https://github.com/alirezarezvani/claude-skills/blob/main/templates/agent-template.md) – Boilerplate for creating new `cs-*` orchestrator agents with required front-matter structure.
- [`marketing-skill/marketing-ops/SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/marketing-skill/marketing-ops/SKILL.md) – Example specialist skill providing campaign orchestration capabilities callable by the multi-agent system.
- [`engineering-team/senior-data-engineer/scripts/pipeline_orchestrator.py`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering-team/senior-data-engineer/scripts/pipeline_orchestrator.py) – Data pipeline specialist tool demonstrating how domain-specific orchestrators integrate into the broader multi-agent architecture.

## Summary

- **Multi-agent orchestration with Claude Code skills** requires an orchestrator YAML configuration that declares specialist tools and selects from five execution patterns (sequential, parallel, hierarchical, event-driven, or consensus).
- The `AgentHandoff` object and `ContextBudget` classes manage state and token costs across agent boundaries, preventing context bleed.
- Use [`engineering-team/senior-prompt-engineer/scripts/agent_orchestrator.py`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering-team/senior-prompt-engineer/scripts/agent_orchestrator.py) to validate configurations and generate Mermaid workflow diagrams before execution.
- The `HierarchicalOrchestrator` class and `parallel_research` function provide ready-to-use implementations for manager-worker and parallel fan-out patterns respectively.
- All components are pure-Python, relying only on standard libraries plus the Anthropic client, making the orchestration layer lightweight and portable across environments.

## Frequently Asked Questions

### What is the difference between hierarchical and parallel fan-out patterns in Claude Code orchestration?

**Hierarchical delegation** uses a manager agent to decompose tasks and delegate to workers sequentially, suitable for complex dependencies where later steps require earlier results. **Parallel fan-out/fan-in** executes multiple agents concurrently using `asyncio` and aggregates their outputs, ideal for research tasks across multiple domains or competitors where inputs are independent. Both patterns are defined in [`engineering/agent-workflow-designer/SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering/agent-workflow-designer/SKILL.md) with specific Python implementations provided.

### How does the orchestrator prevent token budget overruns in multi-agent workflows?

The `ContextBudget` class and `AgentHandoff` object enforce strict token accounting by passing remaining budget allocations with every agent hand-off. The [`agent_orchestrator.py`](https://github.com/alirezarezvani/claude-skills/blob/main/agent_orchestrator.py) utility calculates per-run cost estimates before execution, and the `max_iterations` parameter in the YAML configuration prevents infinite loops. This ensures predictable costs even when chaining multiple specialist agents.

### Can I mix different AI models within a single orchestration workflow?

Yes, the orchestrator supports model fallback and specialization through the `ToolDefinition` schema. While the orchestrator itself runs on a primary model (e.g., `sonnet`), individual specialist tools can specify different models in their configurations. The `with_retry` decorator in [`agent_orchestrator.py`](https://github.com/alirezarezvani/claude-skills/blob/main/agent_orchestrator.py) handles exponential back-off and can trigger model fallback if a specific agent fails or hits rate limits.

### Where should I store my custom orchestrator configurations in the repository?

Store orchestrator YAML files in the `agents/orchestrator/` directory following the naming convention `cs-{name}-orchestrator.yaml`. Base your structure on [`templates/agent-template.md`](https://github.com/alirezarezvani/claude-skills/blob/main/templates/agent-template.md), which provides the required front-matter including `name`, `description`, `skills`, `pattern`, and `system_prompt` fields. Validate the file path using the CLI tool before committing to ensure all referenced skill packages exist in the repository.