tomevault-io 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 | Purpose | Model | Tools |
|---|---|---|---|
| scout-fast | Quick reconnaissance | Haiku | Read, Glob, Grep |
| builder | Code implementation | Sonnet | Read, Write, Edit, Bash |
| reviewer | Code review | Sonnet | Read, Grep, Glob, Bash |
| planner | Task planning | Sonnet | Read, Glob, Grep |
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:
| Tool | Purpose | Parameters |
|---|---|---|
create_agent |
Spin up new agent | template, name |
command_agent |
Send prompt to agent | agent_id, prompt |
check_agent_status |
Get agent progress | agent_id |
list_agents |
View all active agents | - |
delete_agent |
Clean up agent | agent_id |
read_agent_logs |
View agent responses | agent_id |
Step 5: Design Observability Layer
Essential metrics to track:
| Metric | Purpose |
|---|---|
| Agent status | Know what's running |
| Context usage | Monitor token consumption |
| Costs | Track spend per agent |
| Tool calls | See what agents are doing |
| Results | Verify outputs |
| Time | Measure execution duration |
Observability Components:
- Agent Cards - Status, model, context, cost per agent
- Event Stream - Real-time log of all activities
- Cost Tracking - Per-agent and total costs
- Result Inspector - consumed/produced assets
- 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:
| Component | Purpose |
|---|---|
| Claude Agent SDK | Core orchestration |
| MCP Servers | Agent management tools |
| Database | Agent state persistence |
| WebSocket | Real-time updates |
| UI/CLI | User interface |
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
| Avoid | Why | Instead |
|---|---|---|
| Orchestrator doing work | Context pollution | Delegate everything |
| Missing observability | Flying blind | Track all metrics |
| Keeping dead agents | Resource waste | Delete when done |
| No lifecycle management | Can't scale | CRUD operations |
| Generic agents | Unfocused work | Specialized templates |
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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.