Skills 多段階プロセス設計

単純なタスクは1つのステップで済みますが、実際のワークフローでは複数の工程が関わることがよくあります。

この記事では、複雑なタスクを明確なステップに分解し、SKILL.md 内で信頼性の高い実行フローとして整理する方法を紹介します。


なぜステップを明示的に定義するのか

Claude は非常に賢いですが、明確なステップの指示がない場合、一部の工程をスキップしたり、一貫性のない順序で実行したりする可能性があります。

明示的なステップの利点:

1つ目は Claude の動作を予測可能にすること、2つ目はユーザーが何が起こっているのかを理解しやすくすること、3つ目はエラー発生時にどのステップで問題が起きたのかを特定しやすくすることです。


ステップ設計の基本原則

原則 説明
各ステップは1つのことだけを行う 1つのステップで複数の無関係な操作を同時に実行することを避ける
ステップ間で明確な入力と出力を持つ 前のステップの出力が次のステップの入力になり、暗黙的な状態に依存しない
各ステップ実行後にフィードバックを返す ユーザーにそのステップで何が完了したか、および次のステップが何かを伝える
途中で中断を許可する ユーザーは任意のステップで一時停止またはパラメータを変更できる

SKILL.md で多ステップフローを定義する

インスタンス

---
name: excel-report-generator
description: >
ユーザーがアップロードした生データに基づいて、フォーマットされた Excel レポートを生成します。データクリーニング、
チャート生成、サマリー統計の3つの工程を含みます。ユーザーがデータレポート、Excel 出力、
自動統計を必要とするときにトリガーされます。
---

# Excel レポート生成器

## 実行フロー

### 第一步:データの読み取りと検証

1. ファイルが存在するか、形式が .csv または .xlsx であるかを確認する
2. ファイルを読み取り、基本情報を出力する:
- 総行数、総列数
- 各列のデータ型
- 空値の数に関する統計
3. 重大な問題(ファイルが空、形式がサポートされていないなど)を発見した場合、停止してユーザーに知らせる

**出力**:データ基本情報レポート(会話内で表示)

---

### 第二步:データクリーニング

実行`scripts/clean_data.py`、以下を実行する:
- 完全に重複する行を削除する
- 数值列の空値を0
- 文字列の先頭と末尾のスペースを除去する

クリーニング後のデータを`/home/claude/cleaned_data.csv`

**出力**:クリーニングレポート(削除した行数、変更した値の数)

---

### 第三步:統計サマリーの生成

実行`scripts/calc_stats.py`、以下を計算する:
- 各数值列の平均値、中央値、標準偏差
- 時間列でグループ化したトレンドデータ(時間列が存在する場合)

に出力`/home/claude/stats.json`

---

### 第四步:Excel レポートの生成

実行`scripts/gen_excel.py`、以下の内容を含む Excel ファイルを生成する:
- Sheet1:クリーニング後の元データ
- Sheet2:統計サマリーテーブル
- Sheet3:折れ線グラフ(時系列データが存在する場合)

最終ファイルをに保存する`/mnt/user-data/outputs/report_YYYYMMDD.xlsx`

**出力**:present_files を呼び出してファイルを表示し、ダウンロードリンクを提供する

---

### エラーハンドリング

任意のステップが失敗した場合:
1. 完全なエラーメッセージを表示する
2. 考えられる原因を説明する
3. ユーザーに現在のステップをスキップするか、パラメータを変更して再試行するかを尋ねる

ステップスクリプトの構成方法

多ステップフローの各ステップは独立したスクリプトファイルに対応させることも、1つのメインスクリプトにまとめることもできます。

方法1:ステップごとに1つのスクリプト(複雑なフローに推奨)

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

方法2:単一のメインスクリプト(シンプルなフローに適する)

インスタンス

# ファイルパス:scripts/pipeline.py
# 単一メインスクリプト、--step パラメータで実行するステップを制御する

import argparse
import sys

def step_clean(input_file: str, output_file: str) -> dict:
    """第二步:データクリーニング"""
    print(f"データをクリーニングしています:{input_file}")
    # 実際のクリーニングロジック...
    return {"status": "success", "removed_rows": 3, "fixed_values": 12}

def step_stats(input_file: str, output_file: str) -> dict:
    """第三步:統計計算"""
    print(f"統計データを計算しています:{input_file}")
    # 実際の統計ロジック...
    return {"status": "success", "columns_analyzed": 5}

def step_excel(data_file: str, stats_file: str, output_file: str) -> dict:
    """第四步:Excel 生成"""
    print(f"Excel レポートを生成しています:{output_file}")
    # 実際の生成ロジック...
    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="実行するステップ:clean / stats / excel")
    parser.add_argument("--input",  required=True, help="入力ファイルパス")
    parser.add_argument("--output", required=True, help="出力ファイルパス")
    args = parser.parse_args()

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

SKILL.md でこのスクリプトを呼び出す:

インスタンス

# 第二步:データクリーニング
python scripts/pipeline.py \
  --step clean \
  --input /mnt/user-data/uploads/サンプル_sales.csv \
  --output /home/claude/cleaned_data.csv

# 第三步:統計計算
python scripts/pipeline.py \
  --step stats \
  --input /home/claude/cleaned_data.csv \
  --output /home/claude/stats.json

ステップ間の依存関係チェック

後続のステップが前のステップの出力ファイルに依存する場合、実行前に依存ファイルが存在するかどうかをチェックする必要があります。

インスタンス

# ファイルパス:scripts/check_deps.py
import os
import sys

def check_step_deps(step_name: str, required_files: list) -> bool:
    """
某ステップの前置ファイルが生成されているかどうかをチェックする

パラメータ:
step_name: 現在のステップ名(エラーメッセージ用)
required_files: 存在する必要があるファイルパスのリスト

戻り値:
True はすべての依存が準備完了、False はファイルが欠落していることを示す
    """

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

    if missing:
        print(f"エラー:{step_name} に前置ファイルがありません:")
        for f in missing:
            print(f"  - {f}")
        print("先に前置ステップを完了してください。")
        return False

    return True

# 使用例:第四步で Excel を生成する前に前置ファイルをチェックする
if __name__ == "__main__":
    deps = [
        "/home/claude/cleaned_data.csv",
        "/home/claude/stats.json"
    ]
    if not check_step_deps("Excel レポートを生成中", deps):
        sys.exit(1)
    print("すべての前置ファイルが準備できました。レポートの生成を開始します...")
错误:生成 Excel 报告 缺少前置文件:
  - /home/claude/stats.json
请先完成前置步骤。

複雑なフローでは、ステップ間の依存関係が見落とされがちです。明確な依存関係チェックにより、エラー発生時に最後のステップで問題が露呈するのではなく、欠落している工程を即座に特定できます。

その他の拡張