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

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 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, 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.

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 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, 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:

---
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, establishing a hierarchical pattern where the orchestrator delegates to three specialist domains.

Validating and Visualizing Workflows

Use the agent_orchestrator.py utility to validate and diagram your configuration:

# 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:

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. 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:

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 – 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 – CLI tool for parsing orchestrator YAML, validating configurations, detecting loops, visualizing workflows, and estimating token costs.
• templates/agent-template.md – Boilerplate for creating new cs-* orchestrator agents with required front-matter structure.
• 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 – 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 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 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 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}