Orchestration Workflow

Overview

The Orchestration Workflow is a design pattern that coordinates multiple Claude Code components to handle complex, multi-step tasks. It demonstrates how Commands, Agents, and Skills work together in a hierarchical workflow. Pattern: Command → Agent (with skill) → Skill

This pattern is ideal for workflows that require user interaction, data fetching, and output generation as separate concerns.

Architecture

The orchestration workflow separates concerns across three component types:

Command

Entry point that handles user interaction and orchestrates the workflow

Agent

Data fetcher that uses preloaded skills as domain knowledge

Skill

Output creator that generates visual or formatted results

Flow Diagram

When to Use

Use the orchestration workflow when you need:

Multi-Step Processes

Breaking complex tasks into discrete phases (gather input → fetch data → generate output)

User Interaction

Asking users for preferences or decisions before proceeding

Specialized Agents

Leveraging agents with domain-specific knowledge (preloaded skills)

Reusable Components

Creating modular, reusable components that can be mixed and matched

Real Example: Weather System

The weather system demonstrates orchestration with a command that coordinates an agent and skill to fetch and display weather data.

Component Details

Command: weather-orchestrator

Location: .claude/commands/weather-orchestrator.mdPurpose: Entry point that orchestrates the workflowResponsibilities:

Ask user for temperature unit (Celsius/Fahrenheit)
Invoke weather-agent via Task tool
Invoke weather-svg-creator via Skill tool
Display results to user

Model: haiku (fast, cheap for orchestration)

Agent: weather-agent

Location: .claude/agents/weather-agent.mdPurpose: Fetch weather data using preloaded skillPreloaded Skill: weather-fetcher (agent skill pattern)Process:

Follows weather-fetcher skill instructions
Fetches temperature from Open-Meteo API
Returns temperature value and unit to command

Model: sonnet (balanced for API integration)

---
name: weather-agent
skills:
  - weather-fetcher  # Preloaded into agent context
tools: WebFetch, Read, Write, Edit
model: sonnet
memory: project
---

Skill: weather-fetcher (Preloaded)

Location: .claude/skills/weather-fetcher/SKILL.mdPurpose: Instructions for fetching temperature dataPattern: Agent Skill (preloaded, not invoked directly)Data Source: Open-Meteo API for Dubai, UAE

---
name: weather-fetcher
description: Instructions for fetching weather data
user-invocable: false  # Background knowledge only
---

The skill provides step-by-step instructions:

Choose API URL based on unit (Celsius/Fahrenheit)
Fetch data via WebFetch tool
Extract temperature from JSON response
Return value and unit

Skill: weather-svg-creator (Independent)

Location: .claude/skills/weather-svg-creator/SKILL.mdPurpose: Create visual SVG weather cardPattern: Skill (invoked via Skill tool)Outputs:

orchestration-workflow/weather.svg - SVG weather card
orchestration-workflow/output.md - Weather summary

The skill receives temperature data from the command’s context and generates styled output files.

Execution Flow

/weather-orchestrator

Code Snippets

Command
Agent
Skill (Preloaded)
Skill (Independent)

.claude/commands/weather-orchestrator.md

---
description: Fetch weather and create SVG card
model: haiku
---

# Weather Orchestrator Command

## Workflow

### Step 1: Ask User Preference
Use AskUserQuestion to ask for Celsius or Fahrenheit.

### Step 2: Fetch Weather Data
Use Task tool to invoke weather-agent:
- subagent_type: weather-agent
- prompt: Fetch temperature in [user's unit]

### Step 3: Create SVG Weather Card
Use Skill tool to invoke weather-svg-creator:
- skill: weather-svg-creator

.claude/agents/weather-agent.md

---
name: weather-agent
description: Fetch weather data for Dubai
tools: WebFetch, Read, Write, Edit
model: sonnet
memory: project
skills:
  - weather-fetcher
---

# Weather Agent

You are a specialized weather agent.

## Your Task
1. Follow weather-fetcher skill instructions
2. Fetch current temperature
3. Return temperature value and unit to caller

.claude/skills/weather-fetcher/SKILL.md

---
name: weather-fetcher
description: Fetch weather temperature data
user-invocable: false
---

# Weather Fetcher Skill

## Instructions

1. **Fetch Weather Data**: Use WebFetch with API URL
   - Celsius: https://api.open-meteo.com/v1/forecast?...
   - Fahrenheit: https://api.open-meteo.com/v1/forecast?...

2. **Extract Temperature**: From JSON response
   - Field: `current.temperature_2m`

3. **Return Result**: Temperature value and unit

.claude/skills/weather-svg-creator/SKILL.md

---
name: weather-svg-creator
description: Creates SVG weather card
---

# Weather SVG Creator Skill

## Task
Create SVG weather card and write output files.

## Instructions

1. Create SVG with temperature from context
2. Write to orchestration-workflow/weather.svg
3. Write summary to orchestration-workflow/output.md

Key Design Principles

Two Skill Patterns

Agent Skills: Preloaded via skills: field (domain knowledge)
Skills: Invoked via Skill tool (independent execution)

Command as Orchestrator

Command handles user interaction and coordinates workflow - doesn’t implement business logic

Agent for Data

Agent uses preloaded skill to fetch data, then returns it to command

Skill for Output

Independent skill receives data from context and creates visual/formatted outputs

Clean Separation of Concerns

Component	Responsibility	Data Flow
Command	User interaction, orchestration	Receives user input → coordinates agents/skills → displays results
Agent	Domain knowledge, data fetching	Receives request → executes skill instructions → returns data
Skill	Output generation	Receives data from context → creates files → reports completion

Implementation Guide

Design Your Workflow

Identify the stages:

What user input is needed?
What data needs to be fetched?
What output needs to be generated?

Create Command

Create .claude/commands/your-command.md:

Handle user interaction with AskUserQuestion
Orchestrate agents with Task tool
Invoke skills with Skill tool
Use fast model (haiku) for orchestration

Create Agent with Preloaded Skill

Create .claude/agents/your-agent.md:

Define agent with skills: field
List required tools
Choose appropriate model for task

Create .claude/skills/your-skill/SKILL.md:

Set user-invocable: false (background knowledge)
Provide detailed instructions for agent

Create Output Skill

Create .claude/skills/output-creator/SKILL.md:

Define what data it expects from context
Specify output files to create
Keep focused on single output responsibility

Test the Workflow

/your-command

Verify:

User prompts work correctly
Agent fetches data successfully
Skill generates expected output
Error handling works gracefully

Use haiku for commands (fast orchestration), sonnet for agents (balanced reasoning), and let skills inherit the command’s context.

Advanced Patterns

Multiple Agents

Orchestrate multiple specialized agents:

## Step 2: Gather Data from Multiple Sources

1. Use Task tool to invoke weather-agent (temperature)
2. Use Task tool to invoke location-agent (coordinates)
3. Use Task tool to invoke timezone-agent (local time)

## Step 3: Combine Results

Use Skill tool to invoke data-combiner skill with all results.

Conditional Workflows

Branch based on user input or data:

## Step 1: Ask User for Report Type

Use AskUserQuestion: "Summary or Detailed?"

## Step 2: Conditional Execution

If "Summary":
  - Invoke summary-agent
  - Invoke summary-formatter skill

If "Detailed":
  - Invoke detailed-agent
  - Invoke detailed-formatter skill

Error Handling

Handle failures gracefully:

## Error Handling

1. If agent fails to fetch data:
   - Retry once
   - If still failing, use cached data (if available)
   - Inform user of degraded results

2. If skill fails to create output:
   - Fall back to text-only output
   - Log error for debugging

Best Practices

Do use commands for orchestration - they’re lightweight and user-facing

Do preload skills into agents when they need domain-specific knowledge

Do keep skills focused on single responsibilities

Do use appropriate models: haiku for commands, sonnet for agents

Don’t put business logic in commands - delegate to agents/skills

Don’t invoke agents directly via bash - always use Task tool

Don’t create circular dependencies between components

Troubleshooting

Agent not using preloaded skill

Problem: Agent doesn’t follow skill instructionsSolution:

Verify skill is listed in agent’s skills: field
Check skill file is at .claude/skills/skill-name/SKILL.md
Ensure agent prompt references the skill

Skill not found when invoked

Problem: Skill tool can’t find the skillSolution:

Check skill directory structure: .claude/skills/skill-name/SKILL.md
Verify name: in frontmatter matches invocation
Ensure SKILL.md file exists (case-sensitive)

Data not passing between components

Problem: Skill doesn’t receive data from agentSolution:

Agent must return data to command explicitly
Command must invoke skill AFTER receiving agent response
Skill receives data from current conversation context

RPI Workflow

Research → Plan → Implement pattern for feature development

Agent Teams

Multiple agents working in parallel on shared tasks

Git Worktrees

Isolated development environments for parallel work

Resources

Commands Guide

Learn more about creating commands

Agents Guide

Deep dive into agent configuration

Skills Guide

Master skills and progressive disclosure

Example Code

Full working example on GitHub

Get Started

Core Concepts

Best Practices

Workflows & Patterns

Implementation Examples

Overview

Architecture

Command

Agent

Skill

Flow Diagram

When to Use

Real Example: Weather System

Component Details

Execution Flow

Code Snippets

Key Design Principles

Two Skill Patterns

Command as Orchestrator

Agent for Data

Skill for Output

Clean Separation of Concerns

Implementation Guide

Advanced Patterns

Multiple Agents

Conditional Workflows

Error Handling

Best Practices

Troubleshooting

RPI Workflow

Agent Teams

Git Worktrees

Resources

Commands Guide

Agents Guide

Skills Guide

Example Code

Build docs developers (and LLMs) love

Get Started

Core Concepts

Best Practices

Workflows & Patterns

Implementation Examples

​Overview

​Architecture

Command

Agent

Skill

​Flow Diagram

​When to Use

​Real Example: Weather System

​Component Details

​Execution Flow

​Code Snippets

​Key Design Principles

Two Skill Patterns

Command as Orchestrator

Agent for Data

Skill for Output

​Clean Separation of Concerns

​Implementation Guide

​Advanced Patterns

​Multiple Agents

​Conditional Workflows

​Error Handling

​Best Practices

​Troubleshooting

​Related Patterns

RPI Workflow

Agent Teams

Git Worktrees

​Resources

Commands Guide

Agents Guide

Skills Guide

Example Code

Build docs developers (and LLMs) love

Overview

Architecture

Flow Diagram

When to Use

Real Example: Weather System

Component Details

Execution Flow

Code Snippets

Key Design Principles

Clean Separation of Concerns

Implementation Guide

Advanced Patterns

Multiple Agents

Conditional Workflows

Error Handling

Best Practices

Troubleshooting

Related Patterns

Resources