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 commands/build-feature.md--- description : Build a feature end-to-end with planning, implementation, and tests argument-hint : & lt;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
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 < 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 outputCurrent branch: ! \` git branch --show-current \` → Current branch: feature/webhooks
${VAR} — Inject environment variableSession: ${CLAUDE_SESSION_ID} → Session: sess_abc123
$ARGUMENTS — All user input after commandFeature: $ARGUMENTS → Feature: add webhook support
$ARGUMENTS[n] — Specific word from inputAction: $ARGUMENTS[ 0 ] Target: $ARGUMENTS[ 1 ] → Action: add → Target: webhook
Frontmatter Reference Command Frontmatter Field Type Purpose descriptionstring Shown in / menu argument-hintstring Placeholder text allowed-toolsstring[] Tool whitelist modelstring Override model
Agent Frontmatter Field Type Purpose namestring Agent identifier descriptionstring When to use (include PROACTIVELY for auto-invoke) toolsstring[] Allowed tools disallowedToolsstring[] Blocked tools modelstring Model override permissionModestring Permission level maxTurnsnumber Turn limit skillsstring[] Preloaded skills memorystring user / project / localbackgroundboolean Default to background execution isolationstring worktree for git isolationcolorstring Display color in agent teams
Skill Frontmatter Field Type Purpose namestring Skill identifier descriptionstring When to invoke argument-hintstring Parameter hint disable-model-invocationboolean Prevent auto-invocation user-invocableboolean Show in / menu allowed-toolsstring[] Tool whitelist modelstring Model override contextstring fork for isolated executionagentstring Delegate to specific agent
Best Practices 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
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
Use specialized debugger agent: /debug "API returns 500 on user creation" # → debugger agent with hypothesis-driven approach # → Systematic investigation # → Root cause analysis
Use read-only reviewer: # Reviewer agent with checklist # → Security check # → Performance check # → Test coverage check
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