Orchestration Patterns

How to wire Commands, Agents, and Skills together for complex workflows

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

commands/build-feature.md

---
description: Build a feature end-to-end with planning, implementation, and tests
argument-hint: <feature description>
---

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

Agent

agents/planner.md

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

Skill

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

1. User runs command

   /build-feature add user preferences

2. Command expands arguments

   Substitutes $ARGUMENTS with “add user preferences”

3. Agent loads with skills

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

4. Agent explores

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

5. Agent produces plan

   Applies skill knowledge to design solution

6. Control returns

   Command waits for user approval

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

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

Architect

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

Implementer

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

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

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

Environment Variables

${VAR} — Inject environment variable

Session: ${CLAUDE_SESSION_ID}
→ Session: sess_abc123

User Arguments

$ARGUMENTS — All user input after command

Feature: $ARGUMENTS
→ Feature: add webhook support

Argument Array

$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

Next Steps

Multi-Phase Development

Deep dive into Research > Plan > Implement

Parallel Worktrees

Enable zero dead time with parallel sessions