Skills: Mehrstufiges Workflow-Design

Einfache Aufgaben benötigen nur einen Schritt, doch Workflows aus der Praxis umfassen oft mehrere Phasen.

Dieser Artikel zeigt, wie man komplexe Aufgaben in klare Schritte zerlegt und sie in einen zuverlässigen Ausführungs-Workflow in SKILL.md organisiert.


Warum Schritte explizit definieren

Claude ist sehr intelligent, aber ohne explizite Schritt-für-Schritt-Anleitung kann Claude bestimmte Phasen überspringen oder sie in einer inkonsistenten Reihenfolge ausführen.

Vorteile expliziter Schritte:

Erstens macht es das Verhalten von Claude vorhersehbar; zweitens hilft es Benutzern zu verstehen, was passiert; drittens ist es bei Fehlern leicht festzustellen, welcher Schritt schiefgelaufen ist.


Grundprinzipien der Schrittgestaltung

Prinzip Beschreibung
Jeder Schritt erledigt nur eine Sache Vermeiden Sie, dass ein Schritt mehrere nicht zusammenhängende Operationen gleichzeitig abschließt
Klare Ein- und Ausgaben zwischen Schritten Die Ausgabe des vorherigen Schritts ist die Eingabe des nächsten Schritts, ohne sich auf impliziten Zustand zu verlassen
Nach der Ausführung jedes Schritts Feedback geben Teilen Sie dem Benutzer mit, was dieser Schritt abgeschlossen hat und was der nächste Schritt ist
Eine Unterbrechung mittendrin zulassen Benutzer können bei jedem Schritt pausieren oder Parameter ändern

Mehrstufige Workflows in SKILL.md definieren

Beispiel

---
name: excel-report-generator
description: >
Erzeugen Sie einen formatierten Excel-Bericht basierend auf den vom Benutzer hochgeladenen Rohdaten, einschließlich Datenbereinigung,
Diagrammerstellung und zusammenfassende Statistiken. Auslösen, wenn der Benutzer einen Datenbericht, eine Excel-Ausgabe,
oder automatisierte Statistiken benötigt.
---

# Excel-Berichtsgenerator

## Ausführungsworkflow

### Schritt 1: Daten lesen und validieren

1. Überprüfen Sie, ob die Datei vorhanden ist und ob das Format .csv oder .xlsx ist
2. Lesen Sie die Datei und geben Sie grundlegende Informationen aus:
- Gesamtzeilen, Gesamtspalten
- Datentyp jeder Spalte
- Anzahl der Nullwerte
3. Wenn schwerwiegende Probleme festgestellt werden (z. B. die Datei ist leer oder das Format wird nicht unterstützt), brechen Sie ab und informieren Sie den Benutzer

**Ausgabe**: Grundlegender Dateninformationsbericht (in der Konversation angezeigt)

---

### Schritt 2: Datenbereinigung

Führe`scripts/clean_data.py`aus, was Folgendes ausführt:
- Vollständig doppelte Zeilen entfernen
- Nullwerte in numerischen Spalten füllen mit0
- Führende und nachfolgende Leerzeichen aus Zeichenfolgen entfernen

Gib die bereinigten Daten nach`/home/claude/cleaned_data.csv aus`

**Ausgabe**: Bereinigungsbericht (wie viele Zeilen entfernt wurden, wie viele Werte geändert wurden)

---

### Schritt 3: Statistische Zusammenfassung generieren

Führen Sie`scripts/calc_stats.py`aus, wodurch Folgendes berechnet wird:
- Mittelwert, Median und Standardabweichung jeder numerischen Spalte
- Trenddaten gruppiert nach der Zeitspalte (falls eine Zeitspalte vorhanden ist)

Ausgabe nach`/home/claude/stats.json`

---

### Schritt 4: Excel-Bericht generieren

Führen Sie`scripts/gen_excel.py`aus, um eine Excel-Datei mit folgendem Inhalt zu generieren:
- Sheet1: bereinigte Rohdaten
- Sheet2: statistische Übersichtstabelle
- Sheet3: Liniendiagramm (falls Zeitreihendaten vorhanden sind)

Speichern Sie die endgültige Datei unter`/mnt/user-data/outputs/report_YYYYMMDD.xlsx`

**Ausgabe**: Rufen Sie present_files auf, um die Datei anzuzeigen und einen Download-Link bereitzustellen

---

### Fehlerbehandlung

Wenn ein beliebiger Schritt fehlschlägt:
1. Die vollständige Fehlermeldung anzeigen
2. Mögliche Ursachen erklären
3. Den Benutzer fragen, ob er den aktuellen Schritt überspringen oder nach Änderung der Parameter erneut versuchen möchte

Wie man Schritt-Skripte organisiert

Jeder Schritt eines mehrstufigen Workflows kann einer unabhängigen Skriptdatei entsprechen oder in ein einziges Hauptskript zusammengeführt werden.

Option 1: Ein Skript pro Schritt (empfohlen für komplexe Workflows)

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

Option 2: Ein einziges Hauptskript (geeignet für einfache Workflows)

Beispiel

# Dateipfad: scripts/pipeline.py
# Ein einziges Hauptskript; verwenden Sie den Parameter --step, um zu steuern, welcher Schritt ausgeführt wird

import argparse
import sys

def step_clean(input_file: str, output_file: str) -> dict:
    """Schritt 2: Datenbereinigung"""
    print(f"Daten werden bereinigt: {input_file}")
    # Tatsächliche Bereinigungslogik...
    return {"status": "success", "removed_rows": 3, "fixed_values": 12}

def step_stats(input_file: str, output_file: str) -> dict:
    """Schritt 3: Statistische Berechnung"""
    print(f"Statistiken werden berechnet: {input_file}")
    # Tatsächliche Statistiklogik...
    return {"status": "success", "columns_analyzed": 5}

def step_excel(data_file: str, stats_file: str, output_file: str) -> dict:
    """Schritt 4: Excel generieren"""
    print(f"Excel-Bericht wird generiert: {output_file}")
    # Tatsächliche Generierungslogik...
    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="Auszuführender Schritt: clean / stats / excel")
    parser.add_argument("--input",  required=True, help="Pfad zur Eingabedatei")
    parser.add_argument("--output", required=True, help="Pfad der Ausgabedatei")
    args = parser.parse_args()

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

Aufruf dieses Skripts in SKILL.md:

Beispiel

# Schritt 2: Datenbereinigung
python scripts/pipeline.py \
  --step clean \
  --input /mnt/user-data/uploads/example_sales.csv \
  --output /home/claude/cleaned_data.csv

# Schritt 3: Statistische Berechnung
python scripts/pipeline.py \
  --step stats \
  --input /home/claude/cleaned_data.csv \
  --output /home/claude/stats.json

Abhängigkeitsprüfungen zwischen Schritten

Wenn ein späterer Schritt von den Ausgabedateien vorheriger Schritte abhängt, prüfe vor der Ausführung, dass die abhängigen Dateien vorhanden sind.

Beispiel

# Dateipfad: scripts/check_deps.py
import os
import sys

def check_step_deps(step_name: str, required_files: list) -> bool:
    """
Prüfen, ob die erforderlichen Dateien eines Schritts generiert wurden

Parameter:
step_name: Name des aktuellen Schritts (wird für Fehlermeldungen verwendet)
required_files: Liste der Dateipfade, die vorhanden sein müssen

Rückgabe:
True bedeutet, dass alle Abhängigkeiten bereit sind, False bedeutet, dass einige Dateien fehlen
    """

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

    if missing:
        print(f"Fehler: Für {step_name} fehlen erforderliche Dateien:")
        for f in missing:
            print(f"  - {f}")
        print("Bitte schließen Sie zuerst die erforderlichen Schritte ab.")
        return False

    return True

# Anwendungsbeispiel: Voraussetzungsdateien prüfen, bevor in Schritt 4 Excel generiert wird
if __name__ == "__main__":
    deps = [
        "/home/claude/cleaned_data.csv",
        "/home/claude/stats.json"
    ]
    if not check_step_deps("Excel-Bericht generieren", deps):
        sys.exit(1)
    print("Alle Voraussetzungsdateien sind bereit, die Berichterstellung wird gestartet...")
错误:生成 Excel 报告 缺少前置文件:
  - /home/claude/stats.json
请先完成前置步骤。

In komplexen Workflows werden Abhängigkeiten zwischen Schritten leicht übersehen. Explizite Abhängigkeitsprüfungen können bei einem Fehler sofort die fehlende Stufe lokalisieren, anstatt das Problem erst im letzten Schritt aufzudecken.

Weitere Erweiterungen