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

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