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

# Workflow d'orchestration

Ce document décrit le workflow d'orchestration **Commande → Agent (avec skill) → Skill**, démontré à travers un système de récupération de données météo et de rendu SVG.

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

## Vue d'ensemble du système

Le système météo démontre deux patterns de skills distincts dans un seul workflow d'orchestration :
- **Agent Skills** (préchargés) : `weather-fetcher` est injecté dans `weather-agent` au démarrage comme connaissance de domaine
- **Skills** (indépendants) : `weather-svg-creator` est invoqué directement par la commande via l'outil Skill

Cela illustre le pattern d'architecture **Commande → Agent → Skill**, où :
- Une commande orchestre le workflow et gère l'interaction utilisateur
- Un agent récupère les données avec son skill préchargé
- Un skill crée la sortie visuelle de manière indépendante

## Résumé des composants

| Composant | Rôle | Exemple |
|-----------|------|---------|
| **Commande** | Point d'entrée, interaction utilisateur | [`/weather-orchestrator`](../.claude/commands/weather-orchestrator.md) |
| **Agent** | Récupère les données avec un skill préchargé (agent skill) | [`weather-agent`](../.claude/agents/weather-agent.md) avec [`weather-fetcher`](../.claude/skills/weather-fetcher/SKILL.md) |
| **Skill** | Crée la sortie indépendamment (skill) | [`weather-svg-creator`](../.claude/skills/weather-svg-creator/SKILL.md) |

## Diagramme de flux

```
╔══════════════════════════════════════════════════════════════════╗
║              WORKFLOW D'ORCHESTRATION                            ║
║           Commande  →  Agent  →  Skill                           ║
╚══════════════════════════════════════════════════════════════════╝

                         ┌──────────────────────┐
                         │ Interaction utilisateur│
                         └─────────┬────────────┘
                                   │
                                   ▼
         ┌─────────────────────────────────────────────────────┐
         │  /weather-orchestrator — Commande (point d'entrée) │
         └─────────────────────────┬───────────────────────────┘
                                   │
                              Étape 1
                                   │
                                   ▼
                      ┌────────────────────────┐
                      │  AskUser — C° ou F° ?  │
                      └────────────┬───────────┘
                                   │
                         Étape 2 — outil Agent
                                   │
                                   ▼
         ┌─────────────────────────────────────────────────────┐
         │  weather-agent — Agent ● skill: weather-fetcher     │
         └─────────────────────────┬───────────────────────────┘
                                   │
                          Retourne : temp + unité
                                   │
                         Étape 3 — outil Skill
                                   │
                                   ▼
         ┌─────────────────────────────────────────────────────┐
         │  weather-svg-creator — Skill ● carte SVG + sortie   │
         └─────────────────────────┬───────────────────────────┘
                                   │
                          ┌────────┴────────┐
                          │                 │
                          ▼                 ▼
                   ┌────────────┐    ┌────────────┐
                   │weather.svg │    │ output.md  │
                   └────────────┘    └────────────┘
```

## Détails des composants

### 1. Commande

#### `/weather-orchestrator` (commande)
- **Emplacement** : `.claude/commands/weather-orchestrator.md`
- **Objectif** : point d'entrée — orchestre le workflow et gère l'interaction utilisateur
- **Actions** :
  1. Demande à l'utilisateur sa préférence d'unité de température (Celsius/Fahrenheit)
  2. Invoque weather-agent via l'outil Agent
  3. Invoque weather-svg-creator via l'outil Skill
- **Modèle** : haiku

### 2. Agent avec skill préchargé (agent skill)

#### `weather-agent` (agent)
- **Emplacement** : `.claude/agents/weather-agent.md`
- **Objectif** : récupérer les données météo avec son skill préchargé
- **Skills** : `weather-fetcher` (préchargé comme connaissance de domaine)
- **Outils disponibles** : Read, Skill
- **Modèle** : sonnet
- **Couleur** : green
- **Mémoire** : project

L'agent a `weather-fetcher` préchargé dans son contexte au démarrage. Il suit les instructions du skill pour récupérer la température et retourne la valeur à la commande.

### 3. Skill

#### `weather-svg-creator` (skill)
- **Emplacement** : `.claude/skills/weather-svg-creator/SKILL.md`
- **Objectif** : créer une carte météo SVG visuelle et écrire les fichiers de sortie
- **Invocation** : via l'outil Skill depuis la commande (non préchargé dans un agent)
- **Sorties** :
  - `orchestration-workflow/weather.svg` — carte météo SVG
  - `orchestration-workflow/output.md` — résumé météo

### 4. Skill préchargé

#### `weather-fetcher` (skill)
- **Emplacement** : `.claude/skills/weather-fetcher/SKILL.md`
- **Objectif** : instructions pour récupérer les données de température en temps réel
- **Source de données** : API Open-Meteo pour Dubaï, Émirats arabes unis
- **Sortie** : valeur de température et unité (Celsius ou Fahrenheit)
- **Note** : c'est un agent skill — préchargé dans `weather-agent`, pas invoqué directement

## Flux d'exécution

1. **Invocation utilisateur** : l'utilisateur lance la commande `/weather-orchestrator`
2. **Prompt utilisateur** : la commande demande l'unité de température préférée (Celsius/Fahrenheit)
3. **Invocation de l'agent** : la commande invoque `weather-agent` via l'outil Agent
4. **Exécution du skill** (dans le contexte de l'agent) :
   - L'agent suit les instructions du skill `weather-fetcher` pour récupérer la température depuis Open-Meteo
   - L'agent retourne la valeur de température et l'unité à la commande
5. **Création SVG** : la commande invoque `weather-svg-creator` via l'outil Skill
   - Le skill crée la carte météo SVG dans `orchestration-workflow/weather.svg`
   - Le skill écrit le résumé dans `orchestration-workflow/output.md`
6. **Affichage du résultat** : résumé affiché à l'utilisateur avec :
   - Unité de température demandée
   - Température récupérée
   - Emplacement de la carte SVG
   - Emplacement du fichier de sortie

## Exemple d'exécution

```
Input: /weather-orchestrator
├─ Étape 1 : demande : Celsius ou Fahrenheit ?
│  └─ User: Celsius
├─ Étape 2 : outil Agent → weather-agent
│  ├─ Skill préchargé :
│  │  └─ weather-fetcher (connaissance de domaine)
│  ├─ Récupère depuis Open-Meteo → 26°C
│  └─ Retourne : temperature=26, unit=Celsius
├─ Étape 3 : outil Skill → /weather-svg-creator
│  ├─ Crée : orchestration-workflow/weather.svg
│  └─ Écrit : orchestration-workflow/output.md
└─ Sortie :
   ├─ Unité : Celsius
   ├─ Température : 26°C
   ├─ SVG : orchestration-workflow/weather.svg
   └─ Résumé : orchestration-workflow/output.md
```

## Principes clés de design

1. **Deux patterns de skills** : démontre à la fois les agent skills (préchargés) et les skills (invoqués directement)
2. **Commande comme orchestrateur** : la commande gère l'interaction utilisateur et coordonne le workflow
3. **Agent pour la récupération de données** : l'agent utilise son skill préchargé pour récupérer les données, puis les retourne
4. **Skill pour la sortie** : le créateur SVG s'exécute indépendamment, recevant les données depuis le contexte de la commande
5. **Séparation claire** : Fetch (agent) → Render (skill) — chaque composant a une seule responsabilité

## Patterns d'architecture

### Agent Skill (préchargé)

```yaml
# Dans la définition de l'agent (.claude/agents/weather-agent.md)
---
name: weather-agent
skills:
  - weather-fetcher    # Préchargé dans le contexte de l'agent au démarrage
---
```

- **Les skills sont préchargés** : le contenu complet du skill est injecté dans le contexte de l'agent au démarrage
- **L'agent utilise la connaissance du skill** : l'agent suit les instructions des skills préchargés
- **Pas d'invocation dynamique** : les skills sont du matériel de référence, pas invoqués séparément

### Skill (invocation directe)

```yaml
# Dans la définition du skill (.claude/skills/weather-svg-creator/SKILL.md)
---
name: weather-svg-creator
description: Creates an SVG weather card...
---
```

- **Invoqué via l'outil Skill** : la commande appelle `Skill(skill: "weather-svg-creator")`
- **Exécution indépendante** : s'exécute dans le contexte de la commande, pas dans un agent
- **Reçoit les données depuis le contexte** : utilise les données de température déjà disponibles dans la conversation