orchestrator-design

Orchestrator Design Skill

Design O-Agent (Orchestrator Agent) systems for managing fleets of specialized agents.

Purpose

Guide the architectural design of orchestrator systems that create, command, monitor, and delete specialized agents through a single unified interface.

When to Use

• Designing multi-agent systems
• Building fleet management architecture
• Creating scalable agent workflows
• Implementing the Single Interface Pattern

Prerequisites

• Understanding of the Three Pillars (@three-pillars-orchestration.md)
• Familiarity with agent lifecycle patterns (@agent-lifecycle-crud.md)
• Access to Claude Agent SDK documentation

SDK Requirement

Implementation Note: Orchestrator patterns require Claude Agent SDK with custom MCP tools. Claude Code subagents cannot spawn other subagents.

Design Process

Step 1: Define Orchestration Scope

Answer these questions:

• What workflows will be orchestrated?
• What agent types are needed?
• What is the expected scale?
• What observability is required?

Output: Scope document (requirements and constraints)

Step 2: Design Agent Templates

For each agent type needed:

Template Structure:

---
name: template-name
description: What this agent does
tools: [tool1, tool2]
model: sonnet|haiku
---

# System Prompt

[Agent-specific instructions]

Step 3: Design Orchestrator System Prompt

The orchestrator needs a specific identity:

# Orchestrator Agent

## Purpose
Manage and coordinate specialized agents to accomplish complex tasks.
You do NOT perform work directly - you orchestrate other agents.

## Capabilities
- Create specialized agents from templates
- Command agents with detailed prompts
- Monitor agent progress
- Aggregate and report results
- Delete agents when work is complete

## Workflow Pattern
1. Analyze task requirements
2. Create appropriate agents
3. Command agents with detailed instructions
4. Monitor progress
5. Aggregate results
6. Report to user
7. Delete agents

## Context Protection
- Keep your context focused on orchestration
- Delegate detailed work to specialized agents
- Do not read files directly
- Do not write code

Step 4: Define Management Tools

Design the MCP tools for agent management:

Step 5: Design Observability Layer

Essential metrics to track:

Observability Components:

1. Agent Cards - Status, model, context, cost per agent
2. Event Stream - Real-time log of all activities
3. Cost Tracking - Per-agent and total costs
4. Result Inspector - consumed/produced assets
5. Log Viewer - Filterable activity history

Step 6: Design Workflow Phases

Standard orchestration workflow:

Phase 1: Scout
├── Create scouts (parallel)
├── Command each with specific area
├── Monitor until complete
└── Aggregate findings

Phase 2: Build
├── Create builder
├── Command with scout reports
├── Monitor implementation
└── Aggregate changes

Phase 3: Review
├── Create reviewer
├── Command to verify implementation
├── Monitor review
└── Generate final report

Cleanup: Delete all agents

Step 7: Plan Deployment Architecture

Required components for SDK implementation:

Output Format

When designing an orchestrator system, provide:

## Orchestrator System Design

**Name:** [system-name]
**Purpose:** [1-2 sentences]
**Scale:** [expected agent count and concurrency]

### Agent Templates

| Template | Purpose | Model | Tools |
| --- | --- | --- | --- |
| ... | ... | ... | ... |

### Orchestrator Configuration

**System Prompt:** [included or file reference]
**Management Tools:** [list of MCP tools]
**Observability:** [metrics and components]

### Workflow Design

[Phase diagram with agent creation/deletion points]

### Architecture

[Deployment diagram with components]

### Implementation Notes

[SDK considerations, constraints, scaling factors]

Design Checklist

• Orchestration scope defined
• Agent templates designed
• Orchestrator system prompt written
• Management tools specified
• Observability layer planned
• Workflow phases designed
• Deployment architecture planned

Anti-Patterns

Cross-References

• @three-pillars-orchestration.md - Framework foundation
• @single-interface-pattern.md - O-Agent architecture
• @agent-lifecycle-crud.md - Lifecycle management
• @multi-agent-context-protection.md - Context boundaries
• @results-oriented-engineering.md - Result patterns

Version History

• v1.0.0 (2025-12-26): Initial release

Last Updated

Date: 2025-12-26 Model: claude-opus-4-5-20251101