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
# 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
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
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 请先完成前置步骤。
Autres extensionsDans 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.