Conception de workflow multi-étapes pour les compétences

Les tâches simples ne nécessitent qu'une seule étape, mais les workflows réels comportent souvent plusieurs phases.

Cet article présente comment décomposer des tâches complexes en étapes claires et les organiser en un workflow d'exécution fiable dans SKILL.md.


Pourquoi définir explicitement les étapes

Claude est très intelligent, mais sans indications explicites étape par étape, il peut sauter certaines phases ou les exécuter dans un ordre incohérent.

Avantages des étapes explicites :

Premièrement, cela rend le comportement de Claude prévisible ; deuxièmement, cela aide les utilisateurs à comprendre ce qui se passe ; troisièmement, lorsque des erreurs surviennent, il est facile d'identifier l'étape qui a mal tourné.


Principes de base de la conception des étapes

Principe Description
Chaque étape ne fait qu'une seule chose Éviter qu'une étape accomplisse plusieurs opérations sans rapport en même temps
Entrées et sorties claires entre les étapes La sortie de l'étape précédente est l'entrée de l'étape suivante, sans dépendre d'un état implicite
Fournir un retour après l'exécution de chaque étape Indiquer à l'utilisateur ce que cette étape a accompli et quelle est l'étape suivante
Permettre une interruption en cours de route Les utilisateurs peuvent mettre en pause ou modifier les paramètres à n'importe quelle étape

Définition de workflows à plusieurs étapes dans SKILL.md

Exemple

---
name: excel-report-generator
description : >
Générer un rapport Excel formaté à partir des données brutes téléversées par l'utilisateur, y compris le nettoyage des données,
la génération de graphiques et les statistiques récapitulatives. Se déclenche lorsque l'utilisateur a besoin d'un rapport de données, d'une sortie Excel,
ou de statistiques automatisées.
---

# Générateur de rapports Excel

## Workflow d'exécution

### Étape 1 : Lire et valider les données

1. Vérifier si le fichier existe et si le format est .csv ou .xlsx
2. Lire le fichier et afficher les informations de base :
- Nombre total de lignes, nombre total de colonnes
- Type de données de chaque colonne
- Nombre de valeurs nulles
3. Si des problèmes graves sont détectés (par exemple, le fichier est vide ou le format n'est pas pris en charge), arrêtez et informez l'utilisateur

**Sortie**: Rapport d'informations de base sur les données (affiché dans la conversation)

---

### Étape 2 : Nettoyage des données

Exécutez`scripts/clean_data.py`, qui effectue :
- Supprimer les lignes entièrement dupliquées
- Remplir les valeurs nulles dans les colonnes numériques avec0
- Supprimer les espaces de début et de fin dans les chaînes de caractères

Écrire les données nettoyées dans`/home/claude/cleaned_data.csv`

**Sortie**: Rapport de nettoyage (combien de lignes ont été supprimées, combien de valeurs ont été modifiées)

---

### Étape 3 : Générer un résumé statistique

Exécutez`scripts/calc_stats.py`, qui calcule :
- Moyenne, médiane et écart-type de chaque colonne numérique
- Données de tendance regroupées par la colonne temporelle (si une colonne temporelle existe)

Sortie vers`/home/claude/stats.json`

---

### Étape 4 : Générer un rapport Excel

Exécutez`scripts/gen_excel.py`, générez un fichier Excel contenant les éléments suivants :
- Sheet1 : données brutes nettoyées
- Sheet2 : tableau récapitulatif statistique
- Sheet3 : graphique en courbes (si des données de séries temporelles existent)

Enregistrez le fichier final dans`/mnt/user-data/outputs/report_YYYYMMDD.xlsx`

**Sortie**: Appelez present_files pour afficher le fichier et fournir un lien de téléchargement

---

### Gestion des erreurs

Lorsqu'une étape échoue :
1. Afficher le message d'erreur complet
2. Expliquer les causes possibles
3. Demander à l'utilisateur s'il souhaite ignorer l'étape en cours ou réessayer après avoir modifié les paramètres

Comment organiser les scripts d'étapes

Chaque étape d'un flux de travail en plusieurs étapes peut correspondre à un fichier de script indépendant, ou être fusionnée dans un seul script principal.

Option 1 : Un script par étape (recommandé pour les flux de travail complexes)

excel-report-generator/
├── SKILL.md
└── scripts/
    ├── clean_data.py      # 第二步:数据清洗
    ├── calc_stats.py      # 第三步:统计计算
    └── gen_excel.py       # 第四步:生成报告

Option 2 : Un script principal unique (adapté aux flux de travail simples)

Exemple

# Chemin du fichier : scripts/pipeline.py
# Script principal unique ; utilisez le paramètre --step pour contrôler quelle étape s'exécute

import argparse
import sys

def step_clean(input_file: str, output_file: str) -> dict:
    """Étape 2 : Nettoyage des données"""
    print(f"Nettoyage des données : {input_file}")
    # Logique de nettoyage réelle...
    return {"status": "success", "removed_rows": 3, "fixed_values": 12}

def step_stats(input_file: str, output_file: str) -> dict:
    """Étape 3 : Calcul statistique"""
    print(f"Calcul des statistiques : {input_file}")
    # Logique statistique réelle...
    return {"status": "success", "columns_analyzed": 5}

def step_excel(data_file: str, stats_file: str, output_file: str) -> dict:
    """Étape 4 : Génération d'Excel"""
    print(f"Génération du rapport Excel : {output_file}")
    # Logique de génération réelle...
    return {"status": "success", "output": output_file}

STEPS = {
    "clean": step_clean,
    "stats": step_stats,
    "excel": step_excel,
}

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--step",   required=True, choices=STEPS.keys(),
                        help="Étape à exécuter : clean / stats / excel")
    parser.add_argument("--input",  required=True, help="Chemin du fichier d'entrée")
    parser.add_argument("--output", required=True, help="Chemin du fichier de sortie")
    args = parser.parse_args()

    import json
    result = STEPS[args.step](args.input, args.output)
    print(json.dumps(result, ensure_ascii=False, indent=2))

Appel de ce script dans SKILL.md :

Exemple

# Étape 2 : Nettoyage des données
python scripts/pipeline.py \
  --step clean \
  --input /mnt/user-data/uploads/example_sales.csv \
  --output /home/claude/cleaned_data.csv

# Étape 3 : Calcul statistique
python scripts/pipeline.py \
  --step stats \
  --input /home/claude/cleaned_data.csv \
  --output /home/claude/stats.json

Vérifications des dépendances entre les étapes

Lorsqu'une étape ultérieure dépend des fichiers de sortie des étapes précédentes, vérifiez que les fichiers dépendants existent avant l'exécution.

Exemple

# Chemin du fichier : scripts/check_deps.py
import os
import sys

def check_step_deps(step_name: str, required_files: list) -> bool:
    """
Vérifier si les fichiers prérequis d'une étape ont été générés

Paramètres :
step_name: Nom de l'étape actuelle (utilisé pour les messages d'erreur)
required_files: Liste des chemins de fichiers qui doivent exister

Retourne :
True signifie que toutes les dépendances sont prêtes, False signifie que certains fichiers sont manquants
    """

    missing = [f for f in required_files if not os.path.exists(f)]

    if missing:
        print(f"Erreur : {step_name} a des fichiers prérequis manquants :")
        for f in missing:
            print(f"  - {f}")
        print("Veuillez d'abord effectuer les étapes préalables.")
        return False

    return True

# Exemple d'utilisation : vérifier les fichiers prérequis avant de générer le rapport Excel à l'étape 4
if __name__ == "__main__":
    deps = [
        "/home/claude/cleaned_data.csv",
        "/home/claude/stats.json"
    ]
    if not check_step_deps("Générer le rapport Excel", deps):
        sys.exit(1)
    print("Tous les fichiers prérequis sont prêts, début de la génération du rapport...")
错误:生成 Excel 报告 缺少前置文件:
  - /home/claude/stats.json
请先完成前置步骤。

Dans les flux de travail complexes, les dépendances entre les étapes sont facilement négligées. Des vérifications explicites des dépendances permettent de localiser immédiatement l'étape manquante lorsqu'une erreur se produit, plutôt que de n'exposer le problème qu'à la dernière étape.

Autres extensions