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に戻ります。
この 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)
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 ではなく、正しいですか?"
同じ会話内に複数のパラメータセットが存在する場合、以下の優先順位で処理します:
1. **ユーザーの最新メッセージで明示的に指定されたパラメータ**→ 最優先、常に使用
2. **今回のリクエストでアップロードされたファイル**→ 高優先
3. **会話履歴で言及されたパラメータ**→ 低優先、現在のメッセージで指定されていない場合のみ使用
4. **Skill で定義されたデフォルト値**→ フォールバック
パラメータの出所に疑問がある場合は、実行前にユーザーに確認します:"サンプル_v2.csv(あなたがアップロードしたファイル)を使用します。以前の サンプル_v1.csv ではなく、正しいですか?"
コンテキストの長さとパフォーマンスの関係
会話が長くなるにつれて、コンテキストウィンドウ内の内容が増え、Claude の処理コストも増加します。
長時間実行されるマルチターン Skill では、以下の最適化戦略に注意する必要があります:
| 戦略 | 方法 | 効果 |
|---|---|---|
| 大きなコンテンツを繰り返し出力しない | 以前に出力したファイルパスを参照し、内容を再出力しない | コンテキストの占有を減らす |
| ファイルを使用して中間データを渡す | 大きなデータセットをファイルに書き込み、会話ではパスのみを渡す | 大きなデータでコンテキストを占有しないようにする |
| 段階的な完了をユーザーに適時知らせる | 各フェーズの終了時に「ステップ1完了」と明確に伝える | ユーザーに進捗を知らせ、追加の問い合わせを減らす |
その他の拡張コンテキストウィンドウは有限なリソースです。Skill で渡すデータ量が大きいほど、推論と生成に残るスペースが少なくなり、応答品質が低下する可能性があります。大きなファイルについては、常にコンテンツではなくファイルパスで渡します。