Skills コンテキストと状態管理

Claude の各 API 呼び出しはステートレスであり、前回のセッションの内容を自動的に記憶しません。

しかし、1回の連続した会話では、すべての履歴メッセージがコンテキストウィンドウ内にあります。これを理解することで、会話中に安定して動作する Skill を書くのに役立ちます。


Skills の状態はどこに存在するか

状態タイプ 保存場所 有効範囲
会話履歴 コンテキストウィンドウ 現在のセッションのみ、閉じると消える
中間ファイル /home/claude/ 現在のセッション、タスク完了後に削除される可能性がある
出力ファイル /mnt/user-data/outputs/ 永続化され、ユーザーがダウンロード可能
インストール済みの Skill /mnt/skills/ セッションをまたいで永続化

Skills 自体にはデータベースや永続ストレージ機能はありません。セッションをまたいで保存する必要があるデータは、ユーザー自身が保存するか(ファイルのダウンロードなど)、永続化出力ディレクトリに書き込む必要があります。


SKILL.md でマルチターン対話状態を管理する

マルチターン対話が必要な Skill では、SKILL.md で対話状態の遷移ロジックを明確に定義する必要があります。

例

## マルチターン対話フロー

この Skill は3つのフェーズで実行されます:

### フェーズ1: 情報収集
ユーザーに以下の情報の提供を求めます:
1. データファイルのパス
2. 分析対象

すべての情報を取得するまで、分析を実行しません。
収集済みの情報をリスト形式で表示し、何が不足しているかをユーザーに伝えます。

### フェーズ2: 実行確認
収集が完了したら、実行計画を表示し、ユーザーの確認を待ちます:
>これから{ファイル名}に対して{分析対象}を実行します。所要時間は約{時間}秒です。続行しますか?

### フェーズ3: 実行と出力
ユーザーの確認後に実行し、進捗をリアルタイムで知らせ、完了後に結果を出力します。

ユーザーが任意のフェーズで「やり直す」と言った場合、収集済みの情報をクリアしてフェーズ1に戻ります。

ファイルを使用して中間状態を保存する

複雑なマルチステップタスクの場合、中間状態を JSON ファイルに書き込むことで、ステップ間の状態受け渡しを実現できます。

例

# ファイルパス:scripts/state_manager.py
import json
import os
from datetime import datetime

# 状態ファイルの保存先(現在のセッションの作業ディレクトリ)
STATE_FILE = "/home/claude/skill_state.json"

def save_state(state: dict) -> None:
    """現在の実行状態をファイルに保存する"""
    state["updated_at"] = datetime.now().isoformat()
    with open(STATE_FILE, "w", encoding="utf-8") as f:
        json.dump(state, f, ensure_ascii=False, indent=2)
    print(f"状態を保存しました:{STATE_FILE}")

def load_state() -> dict:
    """最後に保存した状態を読み込み、存在しない場合は初期状態を返す"""
    if not os.path.exists(STATE_FILE):
        return {
            "phase":      "collecting",  # 現在のフェーズ: collecting / confirming / executing / done
            "file_path":  None,
            "target":     None,
            "result":     None,
            "created_at": datetime.now().isoformat()
        }
    with open(STATE_FILE, "r", encoding="utf-8") as f:
        return json.load(f)

def clear_state() -> None:
    """状態をクリア(「やり直す」シナリオ用)"""
    if os.path.exists(STATE_FILE):
        os.remove(STATE_FILE)
    print("状態をクリアしました。やり直します")

# 使用例
if __name__ == "__main__":
    # 状態を読み込みまたは初期化
    state = load_state()
    print(f現在のフェーズ:{state['phase']})

    # 状態を更新:収集済みのファイルパス
    state["file_path"] = "/mnt/user-data/uploads/サンプル_data.csv"
    state["phase"]     = "confirming"
    save_state(state)
状态已保存:/home/claude/skill_state.json
当前阶段:collecting
状态已保存:/home/claude/skill_state.json

コンテキスト汚染を防ぐ

ユーザーが同じ会話内で Skill を複数回トリガーすると、履歴内の古いパラメータが新しい実行を「汚染」する可能性があります。

SKILL.md で優先順位を明確に規定することで、このような問題を回避できます。

例

## パラメータ優先順位ルール

同じ会話内に複数のパラメータセットが存在する場合、以下の優先順位で処理します:

1. **ユーザーの最新メッセージで明示的に指定されたパラメータ**→ 最優先、常に使用
2. **今回のリクエストでアップロードされたファイル**→ 高優先
3. **会話履歴で言及されたパラメータ**→ 低優先、現在のメッセージで指定されていない場合のみ使用
4. **Skill で定義されたデフォルト値**→ フォールバック

パラメータの出所に疑問がある場合は、実行前にユーザーに確認します:"サンプル_v2.csv(あなたがアップロードしたファイル)を使用します。以前の サンプル_v1.csv ではなく、正しいですか?"

コンテキストの長さとパフォーマンスの関係

会話が長くなるにつれて、コンテキストウィンドウ内の内容が増え、Claude の処理コストも増加します。

長時間実行されるマルチターン Skill では、以下の最適化戦略に注意する必要があります:

戦略 方法 効果
大きなコンテンツを繰り返し出力しない 以前に出力したファイルパスを参照し、内容を再出力しない コンテキストの占有を減らす
ファイルを使用して中間データを渡す 大きなデータセットをファイルに書き込み、会話ではパスのみを渡す 大きなデータでコンテキストを占有しないようにする
段階的な完了をユーザーに適時知らせる 各フェーズの終了時に「ステップ1完了」と明確に伝える ユーザーに進捗を知らせ、追加の問い合わせを減らす

コンテキストウィンドウは有限なリソースです。Skill で渡すデータ量が大きいほど、推論と生成に残るスペースが少なくなり、応答品質が低下する可能性があります。大きなファイルについては、常にコンテンツではなくファイルパスで渡します。

その他の拡張