Orchestration Patterns

Orchestration patterns define how Commands, Agents, and Skills work together to handle complex development tasks. Each pattern solves specific coordination challenges.

Pattern 1: Command > Agent > Skill

The most powerful pattern for complex features. Three layers with single responsibilities.

Structure

Command (entry point, user-facing)
  └── Agent (execution, constrained tools)
        └── Skill (domain knowledge, preloaded)

Example: Feature Builder

Command
Agent
Skill

commands/build-feature.md

---
description: Build a feature end-to-end with planning, implementation, and tests
argument-hint: &lt;feature description&gt;
---

Build this feature using a structured approach:

1. Delegate to the planner agent to create a plan
2. Wait for plan approval
3. Implement the plan
4. Run quality gates
5. Create a commit

Feature: $ARGUMENTS

agents/planner.md

---
name: planner
description: Break down tasks into plans
tools: ["Read", "Glob", "Grep"]
skills: ["api-conventions", "project-patterns"]
model: opus
---

skills/api-conventions/SKILL.md

---
name: api-conventions
description: API design patterns for this project
user-invocable: false
---

REST endpoints use camelCase. Auth via Bearer tokens.
Error responses follow RFC 7807.

Flow Diagram

How It Flows

User runs command

/build-feature add user preferences

Command expands arguments

Substitutes $ARGUMENTS with “add user preferences”

Agent loads with skills

Planner starts with api-conventions and project-patterns in context

Agent explores

Uses constrained tools (Read, Glob, Grep) to understand codebase

Agent produces plan

Applies skill knowledge to design solution

Control returns

Command waits for user approval

Implementation proceeds

With full context and approved plan

Pattern 2: Multi-Phase Development (RPI)

Research > Plan > Implement with validation gates between phases.

Structure

.claude/
├── commands/
│   └── develop.md          # Entry point
├── agents/
│   ├── researcher.md       # Phase 1: explore and validate
│   ├── architect.md        # Phase 2: design
│   └── implementer.md      # Phase 3: build
└── skills/
    └── project-patterns/
        └── SKILL.md         # Shared knowledge

The Flow

/develop "add webhook support"
    │
    ▼
[Research Phase] → researcher agent
    │  - Explore existing code
    │  - Find similar patterns
    │  - Check dependencies
    │  - Score confidence (0-100)
    │
    ├── Score &lt; 70 → HOLD (ask user for more context)
    │
    ▼
[Plan Phase] → architect agent
    │  - Design the solution
    │  - List all files to change
    │  - Identify risks
    │  - Present plan for approval
    │
    ├── User rejects → Back to research
    │
    ▼
[Implement Phase] → implementer agent
    │  - Execute the plan step by step
    │  - Run tests after each step
    │  - Quality gates at checkpoints
    │
    ▼
[Verify] → reviewer agent
    │  - Code review the changes
    │  - Security check
    │  - Performance check
    │
    ▼
[Commit] → /commit command

Never skip phases. Research before planning, plan before implementing.

Phase Agents

Researcher
Architect
Implementer

---
name: researcher
description: Explore codebase to assess feasibility
tools: ["Read", "Glob", "Grep", "Bash"]
background: true
isolation: worktree
memory: project
---

Runs in background with worktree isolation so it doesn’t block the main session.

---
name: architect
description: Design implementation plans with risk assessment
tools: ["Read", "Glob", "Grep"]
skills: ["project-patterns"]
model: opus
---

Read-only tools, Opus model for deep reasoning, preloaded project patterns.

---
name: implementer
description: Execute approved plans step by step
tools: ["Read", "Edit", "Write", "Bash"]
skills: ["quality-gates"]
model: sonnet
---

Full tool access, quality gates skill preloaded.

Pattern 3: Agent Skills vs On-Demand Skills

Two ways to use skills—understand when to use each.

Agent Skills (Preloaded)

# In agent frontmatter
skills: ["api-conventions", "error-handling"]

Characteristics:

Full skill content injected into agent context at startup
Always available, no invocation needed
Use for: domain knowledge the agent always needs
Cost: uses context tokens

On-Demand Skills (Invoked)

# In skill frontmatter
user-invocable: true
context: fork  # Optional: isolated execution

Characteristics:

User runs /skill-name or Claude invokes via Skill() tool
Content loaded only when called
Use for: procedures run occasionally
context: fork runs in isolated subagent context

Decision Matrix

Scenario	Use
Agent always needs this knowledge	Agent skill (preloaded)
User triggers occasionally	On-demand skill
Heavy procedure, don’t pollute context	On-demand with `context: fork`
Background-only, never user-facing	`user-invocable: false`

Use preloaded skills for <10KB of critical knowledge. Use on-demand for everything else.

Pattern 4: Agent Teams Orchestration

For large tasks, coordinate multiple agents working in parallel.

# Enable agent teams (experimental)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Team Composition

Role	Agent	Responsibility
Lead	Main session	Coordinate, assign tasks, synthesize
Frontend	Teammate 1	UI components, styling, client logic
Backend	Teammate 2	API endpoints, database, server logic
Tests	Teammate 3	Test coverage, integration tests

Communication Flow

Key features:

Lead assigns tasks via shared task list
Teammates work independently in their own context windows
Teammates message each other directly (not just report back)
Lead synthesizes results and handles conflicts

When to Use

Factor	Subagents	Agent Teams
Context	Shares parent session	Independent windows
Communication	Returns result only	Direct messaging
Duration	Short tasks	Long sessions
Isolation	Optional worktree	Always isolated
Coordination	Parent manages	Shared task list

Pattern 5: Dynamic Command Substitution

Commands support string substitution for dynamic context.

# In a command file

Current branch: !\`git branch --show-current\`
Last commit: !\`git log --oneline -1\`
Modified files: !\`git diff --name-only\`

Session: ${CLAUDE_SESSION_ID}
User argument: $ARGUMENTS
First word: $ARGUMENTS[0]

Substitution types:

Command Output
Environment Variables
User Arguments
Argument Array

!\`command\` — Execute command and inject output

Current branch: !\`git branch --show-current\`
→ Current branch: feature/webhooks

${VAR} — Inject environment variable

Session: ${CLAUDE_SESSION_ID}
→ Session: sess_abc123

$ARGUMENTS — All user input after command

Feature: $ARGUMENTS
→ Feature: add webhook support

$ARGUMENTS[n] — Specific word from input

Action: $ARGUMENTS[0]
Target: $ARGUMENTS[1]
→ Action: add
→ Target: webhook

Frontmatter Reference

Command Frontmatter

Field	Type	Purpose
`description`	string	Shown in `/` menu
`argument-hint`	string	Placeholder text
`allowed-tools`	string[]	Tool whitelist
`model`	string	Override model

Agent Frontmatter

Field	Type	Purpose
`name`	string	Agent identifier
`description`	string	When to use (include PROACTIVELY for auto-invoke)
`tools`	string[]	Allowed tools
`disallowedTools`	string[]	Blocked tools
`model`	string	Model override
`permissionMode`	string	Permission level
`maxTurns`	number	Turn limit
`skills`	string[]	Preloaded skills
`memory`	string	`user` / `project` / `local`
`background`	boolean	Default to background execution
`isolation`	string	`worktree` for git isolation
`color`	string	Display color in agent teams

Skill Frontmatter

Field	Type	Purpose
`name`	string	Skill identifier
`description`	string	When to invoke
`argument-hint`	string	Parameter hint
`disable-model-invocation`	boolean	Prevent auto-invocation
`user-invocable`	boolean	Show in `/` menu
`allowed-tools`	string[]	Tool whitelist
`model`	string	Model override
`context`	string	`fork` for isolated execution
`agent`	string	Delegate to specific agent

Best Practices

Do

Use read-only agents for planning phases

Preload frequently-needed skills (< 10KB)

Use context: fork for heavy procedures

Set background: true for long exploration

Use agent teams for parallel work domains

Include PROACTIVELY in agent descriptions for auto-invocation

Don’t

Real-World Examples

Feature Development

Use multi-phase orchestration:

/develop "add user authentication"
# → Research phase: explores existing auth patterns
# → Plan phase: designs JWT + refresh token approach
# → Implement phase: builds step by step
# → Review phase: security audit

Bug Investigation

Use specialized debugger agent:

/debug "API returns 500 on user creation"
# → debugger agent with hypothesis-driven approach
# → Systematic investigation
# → Root cause analysis

Code Review

Use read-only reviewer:

# Reviewer agent with checklist
# → Security check
# → Performance check
# → Test coverage check

Parallel Exploration

Use agent teams:

# Lead coordinates 3 teammates:
# → Teammate 1: explores GraphQL approach
# → Teammate 2: explores REST approach
# → Teammate 3: evaluates trade-offs
# → Lead synthesizes findings

Get Started

Core Concepts

Skills

Agents

Commands

Hooks & Events

Configuration

Guides

Pattern 1: Command > Agent > Skill

Structure

Example: Feature Builder

Flow Diagram

How It Flows

Pattern 2: Multi-Phase Development (RPI)

Structure

The Flow

Phase Agents

Pattern 3: Agent Skills vs On-Demand Skills

Agent Skills (Preloaded)

On-Demand Skills (Invoked)

Decision Matrix

Pattern 4: Agent Teams Orchestration

Team Composition

Communication Flow

When to Use

Pattern 5: Dynamic Command Substitution

Frontmatter Reference

Command Frontmatter

Agent Frontmatter

Skill Frontmatter

Best Practices

Do

Don’t

Real-World Examples

Next Steps

Multi-Phase Development

Parallel Worktrees

Build docs developers (and LLMs) love

Get Started

Core Concepts

Skills

Agents

Commands

Hooks & Events

Configuration

Guides

Documentation Index

​Pattern 1: Command > Agent > Skill

​Structure

​Example: Feature Builder

​Flow Diagram

​How It Flows

​Pattern 2: Multi-Phase Development (RPI)

​Structure

​The Flow

​Phase Agents

​Pattern 3: Agent Skills vs On-Demand Skills

​Agent Skills (Preloaded)

​On-Demand Skills (Invoked)

​Decision Matrix

​Pattern 4: Agent Teams Orchestration

​Team Composition

​Communication Flow

​When to Use

​Pattern 5: Dynamic Command Substitution

​Frontmatter Reference

​Command Frontmatter

​Agent Frontmatter

​Skill Frontmatter

​Best Practices

​Do

​Don’t

​Real-World Examples

​Next Steps

Multi-Phase Development

Parallel Worktrees

Build docs developers (and LLMs) love

Pattern 1: Command > Agent > Skill

Structure

Example: Feature Builder

Flow Diagram

How It Flows

Pattern 2: Multi-Phase Development (RPI)

Structure

The Flow

Phase Agents

Pattern 3: Agent Skills vs On-Demand Skills

Agent Skills (Preloaded)

On-Demand Skills (Invoked)

Decision Matrix

Pattern 4: Agent Teams Orchestration

Team Composition

Communication Flow

When to Use

Pattern 5: Dynamic Command Substitution

Frontmatter Reference

Command Frontmatter

Agent Frontmatter

Skill Frontmatter

Best Practices

Do

Don’t

Real-World Examples

Next Steps