Skip to content

orchestration-patterns.md

Latest commit

 

History

History
294 lines (234 loc) · 7.86 KB

orchestration-patterns.md

File metadata and controls

294 lines (234 loc) · 7.86 KB

Orchestration Patterns

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

The Three Layers

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

Each layer has a single responsibility:

  • Commands handle user interaction and parameter collection
  • Agents execute workflows with constrained tool access
  • Skills provide domain-specific knowledge and procedures

Pattern 1: Command > Agent > Skill

The most powerful pattern. A slash command delegates to an agent that has skills 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.

How It Flows

  1. User runs /build-feature add user preferences
  2. Command expands $ARGUMENTS and delegates to planner agent
  3. Planner loads with api-conventions skill already in context
  4. Planner explores code, produces plan using skill knowledge
  5. Control returns to command for approval
  6. Implementation proceeds with full context

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

Researcher Agent

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

Key: runs in background with worktree isolation so it doesn't block the main session.

Architect Agent

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

Key: read-only tools, Opus model for deep reasoning, preloaded project patterns.

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"]
  • 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
  • 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

Pattern 4: Agent Teams Orchestration

For large tasks, coordinate multiple agents working in parallel.

# Enable agent teams
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

  • 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 Agent Teams vs Subagents

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]

The !`command` syntax injects live output. Use for context-aware commands.

Frontmatter Quick 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
mcpServers object Agent-specific MCP servers
hooks object Agent-specific hooks
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
hooks object Skill-specific hooks