claude-code-best-practice/orchestration-workflow/orchestration-workflow.md

# Orchestration Workflow

This document describes the **Command → Agent → Skills** orchestration workflow, demonstrated through a weather data fetching and transformation system.

<table width="100%">
<tr>
<td><a href="../">← Back to Claude Code Best Practice</a></td>
<td align="right"><img src="../!/claude-jumping.svg" alt="Claude" width="60" /></td>
</tr>
</table>

## System Overview

The weather system demonstrates the **Command → Agent → Skills** architecture pattern, where:
- A command orchestrates the workflow
- An agent executes tasks using preloaded skills
- Skills provide domain-specific knowledge and instructions

## Flow Diagram

```
          ┌─────────────────────────────────────────────────┐
          │                 User Interaction                 │
          └─────────────────────────────────────────────────┘
                                   │
                                   ▼
                     ┌───────────────────────────┐
                     │  /weather-orchestrator    │
                     │  Command                  │
                     │  (Entry point)            │
                     └───────────────────────────┘
                                   │
                                   │ Task tool invocation
                                   ▼
                     ┌───────────────────────────┐
                     │  weather                  │
                     │  Agent                    │
                     │  (Orchestrates flow)      │
                     │                           │
                     │  skills:                  │
                     │  - weather-fetcher        │
                     │  - weather-transformer    │
                     └───────────────────────────┘
                                   │
                  ┌────────────────┴────────────────┐
                  │                                 │
                  ▼                                 ▼
    ┌───────────────────────────┐     ┌───────────────────────────┐
    │  weather-fetcher          │     │  weather-transformer      │
    │  Skill                    │     │  Skill                    │
    │  (Preloaded knowledge)    │     │  (Preloaded knowledge)    │
    └───────────────────────────┘     └───────────────────────────┘
                  │                                 │
                  ▼                                 ▼
    ┌───────────────────────────┐     ┌───────────────────────────┐
    │  wttr.in API              │     │  orchestration-workflow/  │
    │  Fetch Temperature        │     │  Read Transform Rules     │
    │  for Karachi              │     └───────────────────────────┘
    └───────────────────────────┘                   │
                  │                                 ▼
                  │ Returns: 26°C     ┌───────────────────────────┐
                  │                   │  Apply Transform          │
                  └──────────────────▶│  26 + 10 = 36°C           │
                                      └───────────────────────────┘
                                                    │
                                                    ▼
                                 ┌─────────────────────────────────────┐
                                 │  orchestration-workflow/output.md   │
                                 │  Write Results                      │
                                 └─────────────────────────────────────┘
                                                    │
                                                    ▼
                                      ┌───────────────────────────┐
                                      │  Display Summary          │
                                      │  to User                  │
                                      └───────────────────────────┘
```

## Component Details

### 1. Command

#### `/weather-orchestrator` (Command)
- **Location**: `.claude/commands/weather-orchestrator.md`
- **Purpose**: Entry point for weather operations
- **Action**: Invokes the weather agent via Task tool
- **Model**: haiku

### 2. Agent with Skills

#### `weather` (Agent)
- **Location**: `.claude/agents/weather.md`
- **Purpose**: Execute the weather workflow using preloaded skills
- **Skills**: `weather-fetcher`, `weather-transformer`
- **Tools Available**: WebFetch, Read, Write
- **Model**: haiku
- **Color**: green

The agent has skills preloaded into its context at startup. It follows the instructions from each skill sequentially.

### 3. Skills

#### `weather-fetcher` (Skill)
- **Location**: `.claude/skills/weather-fetcher/SKILL.md`
- **Purpose**: Instructions for fetching real-time temperature data
- **Data Source**: wttr.in API for Karachi, Pakistan
- **Output**: Temperature in Celsius (numeric value)

#### `weather-transformer` (Skill)
- **Location**: `.claude/skills/weather-transformer/SKILL.md`
- **Purpose**: Instructions for applying mathematical transformations
- **Input Source**: `orchestration-workflow/input.md` (transformation rules)
- **Output Destination**: `orchestration-workflow/output.md` (formatted results)

### 4. Data Files

#### `orchestration-workflow/input.md`
- **Purpose**: Stores transformation rules
- **Format**: Natural language instructions (e.g., "add +10 in the result")
- **Access**: Read by weather agent following weather-transformer skill

#### `orchestration-workflow/output.md`
- **Purpose**: Stores formatted transformation results
- **Format**: Structured markdown with sections:
  - Original Temperature
  - Transformation Applied
  - Final Result
  - Calculation Details

## Execution Flow

1. **User Invocation**: User runs `/weather-orchestrator` command
2. **User Prompt**: Command asks user for preferred temperature unit (Celsius/Fahrenheit)
3. **Agent Invocation**: Command invokes weather agent via Task tool
4. **Skill Execution** (within agent context):
   - **Step 1**: Agent follows `weather-fetcher` skill instructions to fetch temperature from wttr.in
   - **Step 2**: Agent follows `weather-transformer` skill instructions to:
     - Read transformation rules from `orchestration-workflow/input.md`
     - Apply rules to the fetched temperature
     - Write formatted results to `orchestration-workflow/output.md`
5. **Result Display**: Summary shown to user with:
   - Temperature unit requested
   - Original temperature
   - Transformation rule applied
   - Final transformed result

## Example Execution

```
Input: /weather-orchestrator
├─ Asks: Celsius or Fahrenheit?
├─ User: Celsius
├─ Task: weather agent (via Task tool)
│  ├─ Skills Preloaded:
│  │  ├─ weather-fetcher (knowledge)
│  │  └─ weather-transformer (knowledge)
│  ├─ Step 1 (weather-fetcher skill):
│  │  └─ Fetches from wttr.in → 26°C
│  ├─ Step 2 (weather-transformer skill):
│  │  ├─ Reads: orchestration-workflow/input.md ("add +10")
│  │  ├─ Calculates: 26 + 10 = 36°C
│  │  └─ Writes: orchestration-workflow/output.md
│  └─ Returns: Complete report
└─ Output:
   ├─ Unit: Celsius
   ├─ Original: 26°C
   ├─ Transform: Add +10
   └─ Result: 36°C
```

## Key Design Principles

1. **Command → Agent → Skills**: Three-tier architecture for clean separation
2. **Skills as Knowledge**: Skills provide domain knowledge preloaded into agent context
3. **Single Agent**: One agent handles multiple related tasks using its skills
4. **Sequential Execution**: Agent follows skill instructions in order
5. **Configurable Transformations**: Rules stored externally in input files
6. **Structured Output**: Results formatted consistently in output files

## Architecture Pattern: Agent-Skills

This system demonstrates the **agent-skills pattern** where:

```yaml
# In agent definition (.claude/agents/weather.md)
---
name: weather
skills:
  - weather-fetcher
  - weather-transformer
---
```

- **Skills are preloaded**: Full skill content is injected into agent's context at startup
- **Agent uses skill knowledge**: Agent follows instructions from preloaded skills
- **No dynamic invocation**: Skills are not invoked separately; they're reference material
- **Single execution context**: All work happens within one agent's context