履歴からスキルを生成

Claude Code のセッション履歴を解析し、繰り返しパターンを発見して新しい Agent Skills を自動生成するメタスキル。

安全性とプライバシー

• セッション履歴にはシークレットや個人情報が含まれる可能性がある。生のログ内容をそのままスキルに貼り付けてはならない
• 履歴ファイルを読み取る前に、どのファイルを読むかを明示し、ユーザーの明確な承認を得ること
• 生のテキスト出力はユーザーが明示的にオプトインした場合のみ含める
• ~/.claude/history.jsonl はプロンプト本文を含むが、比較的軽量（通常 1MB 未満）。Read で直接読み取る
• CLI コマンド履歴の抽出（ユーザーのターミナル履歴）は、ユーザーが明示的にオプトインした場合のみ行う
• CLI 履歴を使用する場合、コマンド文字列のみを抽出する。stdout/stderr はスキルにコピーしない。コマンド内のシークレット（トークン、パスワード等）は必ずマスクする

ワークフロー概要

以下の6フェーズを順番に実行する。Phase 5 に進む前に必ずユーザーに確認する。

このチェックリストをコピーして進行状況を追跡する:

スキル生成進捗:
- [ ] Phase 1: データ収集（同意取得→history.jsonl 読み取り→フィルタ）
- [ ] Phase 2: タスクパターン抽出（WHAT/HOW/FLOW の三軸抽出）
- [ ] Phase 3: スキル適性評価（スコアリング→ランク付け→候補提示）
- [ ] Phase 4: ユーザー選択（スキル化対象の決定→スコープ確認）
- [ ] Phase 5: スキル生成（SKILL.md + 補助ファイルの作成）
- [ ] Phase 6: 品質検証（ベストプラクティス照合→チェックリスト確認）

Phase 1: データ収集

同意ゲート（必須）

読み取りを開始する前に、ユーザーに以下を伝え、選択してもらう:

• 分析スコープ（現在のプロジェクトのみ or 全プロジェクト横断）
• 時間範囲（過去N日分）
• 読み取るファイル
• CLI コマンド履歴の利用（オプション）: ターミナルの履歴（~/.zsh_history 等）も分析に含めるかを提案する。含める場合、Claude Code セッションとの照合やコマンド頻度分析が可能になることを説明する

その上で明確な承認を得る（例: 「OKなら進めます」）。

データソース（優先順）

1. ~/.claude/history.jsonl（最優先・推奨）

全プロジェクト横断で、ユーザーが入力した全プロンプトを記録するファイル。 パターン分析の第一データソースとして使用する。1ファイルを Read するだけで全セッションの firstPrompt 相当を取得でき、個別 .jsonl を何十件も解析する必要がない。

エントリ構造:

{
  "display": "適切な粒度でコミット",
  "pastedContents": {},
  "timestamp": 1739012345678,
  "project": "/Users/alice/projects/my-app",
  "sessionId": "uuid-string"
}

フィールド説明:

• display — ユーザーが入力したプロンプト本文。改行は \n でエスケープ。スラッシュコマンド（/commit, /review-pr 等）も含まれる
• pastedContents — 貼り付けられたテキスト（番号付き参照形式）。通常は空 {}
• timestamp — Unix タイムスタンプ（ミリ秒）
• project — プロジェクトの絶対パス。プロジェクト別フィルタに使用
• sessionId — セッション UUID。同一セッション内の複数プロンプトをグルーピングするのに使用

活用方法:

• プロジェクト別フィルタ: project フィールドの部分一致で対象プロジェクトを絞る
• 時間範囲フィルタ: timestamp をミリ秒 Unix タイムスタンプとして比較
• セッション単位の集約: sessionId でグルーピングし、エントリ数をメッセージ数の指標とする
• firstPrompt: 各セッションの最初のエントリの display が firstPrompt に相当

2. ~/.claude/projects/{encoded-path}/sessions-index.json（補助）

sessions-index.json は作成されない・更新されないことが多い既知のバグがあり、信頼できるデータソースではない。存在すれば messageCount や summary などの追加情報を得られるが、存在しなくても history.jsonl で十分なパターン分析が可能。

構造: { version, entries: [{ sessionId, fullPath, fileMtime, firstPrompt, messageCount, created, modified, gitBranch, projectPath, isSidechain }] }

3. 個別セッション .jsonl（CLI コマンド履歴用）

~/.claude/projects/{encoded-path}/{sessionId}.jsonl

プロンプト分析には不要。CLI コマンド履歴（Bash ツール使用）の抽出が必要な場合のみ使用する。

パスエンコーディング（個別 .jsonl アクセス時のみ必要）

ディレクトリパスは /, _, . を - に置換してエンコードする。

例: /Users/alice_name/projects/foo → -Users-alice-name-projects-foo

手順

1. スコープを決定する: 現在のプロジェクト（デフォルト）or 全プロジェクト
2. ユーザーに伝える: 「~/.claude/history.jsonl を読み取り、[対象プロジェクト]の過去[N日]分のプロンプト履歴を分析します」
3. 明確な承認を得る
4. ~/.claude/history.jsonl を読み取る。Read ツールでサイズ超過エラー（256KB超）が発生した場合は、同梱の scripts/filter-history.py を Bash で実行する:

   python3 {skill-dir}/scripts/filter-history.py \
     --project "{project-path}" --days {N} --noise-filter
   

   出力が Bash の表示上限を超える場合はファイルにリダイレクトし、Read で読み取る:

   python3 {skill-dir}/scripts/filter-history.py \
     --project "{project-path}" --days {N} --noise-filter > /tmp/history-filtered.txt
   

5. project（部分一致）と timestamp（時間範囲）でフィルタする（スクリプト使用時は自動処理される）
6. sessionId でグルーピングし、セッション単位のデータを得る（firstPrompt = 最初のエントリの display、メッセージ数 = エントリ数）

history.jsonl が存在しない場合のみ、個別 .jsonl のフォールバックに移行する（後述の「フォールバック」セクション参照）。

CLI 履歴モード（オプション）

ユーザーがオプトインした場合、ターミナルのコマンド履歴（~/.zsh_history 等）を抽出する。タイムスタンプが利用可能な場合は history.jsonl と照合してセッション単位でマッピングする。抽出手順の詳細は references/cli-history-mode.md を参照。

Phase 2: タスクパターン抽出

history.jsonl から抽出したプロンプトを分析し、具体的な繰り返しタスクパターンを抽出する。

カテゴリ（UI/UX, Commit Ops 等）ではなく、ユーザーが実際に繰り返し行っている具体的な作業を特定する。

自由度ガイド: このフェーズでは「厳守」と「裁量可」を以下のように区別する:

• 厳守: WHAT/HOW/FLOW の三軸で独立に抽出する。HOW を WHAT に丸めない。抽出時の判断フローに従う
• 裁量可: パターン名の付け方、類似プロンプトのグルーピング判断、ノイズ除外の境界判断

二軸抽出: WHAT と HOW

プロンプトには「何をしたいか（WHAT）」と「どうやるか（HOW）」の2つの情報が含まれる。 両方を独立したパターンとして抽出する。HOW を WHAT に丸めてはならない。

• WHAT パターン: ユーザーが達成したいゴール
  • 例: 「適切な粒度でコミット」「lintエラーを修正」「UI改善点を洗い出す」
• HOW パターン: ゴール達成のためにユーザーが繰り返し指定する手段・ワークフロー
  • 例: 「エージェントチームを組成して並列実行」「ralph-loopで反復実行」「code-simplifyでシンプル化」「git worktreeを作成して別ブランチで実装」

HOW パターンは複数の異なる WHAT に横断的に出現する（例: 「リファクタリング」でも「レビュー指摘対応」でもエージェントチーム組成を要求）。 この横断性こそがスキル化の価値が高い証拠であり、WHAT に吸収させると見えなくなる。

抽出時の判断フロー（厳守）:

1. プロンプトを読み、WHAT（ゴール）を特定する
2. 同じプロンプト内に HOW（手段の指定）が含まれるか確認する
3. HOW が含まれる場合、WHAT パターンと HOW パターンの両方にカウントする
4. HOW が複数の異なる WHAT で繰り返し出現する場合、独立したスキル候補として重視する

具体的な WHAT/HOW 抽出の例は references/pattern-extraction-examples.md を参照。

セッションフロー分析（FLOW パターン）

WHAT と HOW に加え、セッション内のプロンプト連鎖（フロー） を第三の分析軸として扱う。

個々のプロンプトだけを見ると「改善点洗い出し」と「コミット」は別パターンに見えるが、 セッション単位で見ると「洗い出し→対応指示→コミット」という一連のフローが繰り返されていることがわかる。 このフロー自体がスキル化の対象になる。

フローの定義: 同一セッション（sessionId）内で連続するプロンプトが構成する、意味的にまとまった作業の流れ。

フロー抽出の手順:

1. sessionId でグルーピングし、各セッション内のプロンプトを時系列順に並べる
2. 各セッションのプロンプト連鎖を要約する（例: 「洗い出し→対応指示→コミット」）
3. セッション間で類似するフローをグルーピングする
4. 3回以上出現するフローを FLOW パターンとして記録する

FLOW パターンと WHAT/HOW の関係:

• FLOW はWHAT やHOW を時間軸で組み合わせたもの
• 同じ WHAT でも、前後のフローが異なれば別パターンになりうる
• FLOW パターンはスキル化時に「ワークフロー全体」をカバーするスキルの設計に直結する

具体的な FLOW パターンの例は references/pattern-extraction-examples.md を参照。

ノイズの除外: フロー分析の前に、以下のプロンプトをフローから除外する:

• /clear, /resume, /status, /usage などのシステムコマンド単体
• /plugin, /init, /mcp などの設定系コマンド単体
• 空プロンプト
• [Pasted text #N] のみで前後にコンテキストがないもの

これらはフローの「区切り」として扱い、フロー内のステップとしてはカウントしない。 ただし /clear はセッション内の「タスク境界」を示すシグナルとして活用できる。

ペーストテキストの扱い: [Pasted text #N +M lines] は history.jsonl では参照のみで実際の内容が記録されない。

• ペーストテキスト参照の前後に説明テキストがある場合（例: 「すべて修正してください [Pasted text #1 +13 lines]」）、説明テキスト部分から WHAT/HOW を推定する
• ペーストテキスト参照のみのプロンプトは、同一セッション内の前後のプロンプトから文脈を推定する
• フィルタ後のプロンプトの30%以上がペーストテキスト参照のみの場合、代表的なセッション .jsonl を2-3件読んで pastedContents の内容を確認する（個別 .jsonl にはペースト内容が含まれている場合がある）

抽出手順

1. ノイズ除外: システムコマンド単体・空プロンプトを除外する
2. セッションフロー抽出: sessionId でグルーピングし、各セッション内のプロンプト連鎖を要約する
3. FLOW パターン抽出: セッション間で類似するフローをグルーピングし、FLOW パターンを特定する
4. WHAT/HOW 抽出: 個々のプロンプトから WHAT と HOW を抽出し、類似する指示をグルーピングする
5. 各パターンには具体的な名前をつける（動詞 + 対象 の形式）
6. HOW パターンについては、どの WHAT と組み合わせて使われたかも記録する
7. 統合とカウント: FLOW、WHAT、HOW の3軸で抽出結果を整理し、重複や包含関係を確認する

カウントルール（厳守）

二重カウントを防ぎ、ユーザーへの提示時に混乱を避けるため、以下のルールに従う:

• FLOW に内包される WHAT/HOW は FLOW 側でのみカウントする。例: 「レビュー→修正→コミット」フローに含まれる「コミット」は FLOW の出現回数に含め、WHAT「コミット」としてはカウントしない
• 単独で出現する WHAT/HOW のみ、WHAT/HOW としてカウントする。例: セッション内で「コミットして」のみ（他のフローの一部でない）の場合だけ WHAT「コミット」にカウント
• HOW が FLOW 内で使用されている場合でも、HOW の横断性を記録する。例: 「エージェントチーム組成」が FLOW「レビュー対応フロー」内で使われた場合、FLOW の出現回数にカウントしつつ、HOW の「組み合わせ先 WHAT」リストにも記録する

タスクパターンの粒度

判断基準（厳守）: 1つのタスクパターンに含まれるセッションが同じ手順・判断基準で処理できるか？ YES なら適切、NO ならさらに分割する。

粒度の良い例・悪い例は references/pattern-extraction-examples.md を参照。

出力フォーマット

各タスクパターンについて以下を整理:

• パターン名: 動詞 + 対象（例: 「変更を適切な粒度でコミット」）
• 軸: WHAT / HOW / FLOW のいずれか
• 出現回数: このパターンに該当するセッション/プロンプト数
• 代表的なプロンプト: 実際のユーザー指示を2-3件引用
• 共通する手順: セッション横断で共通している作業ステップ
• フローステップ（FLOW のみ）: セッション内のプロンプト連鎖を矢印で表現（例: 「洗い出し→対応指示→コミット」）
• バリエーション: パターン内の差異（除外ファイルの有無、等）
• 組み合わせ（HOW のみ）: どの WHAT パターンと併用されたか
• 内包する WHAT/HOW（FLOW のみ）: このフローに含まれる WHAT/HOW パターンのリスト

CLI 履歴モードが有効な場合は、以下も抽出する:

• 各タスクパターンで共通して実行されるコマンドテンプレート
• コマンドの実行順序（チェイン）

Phase 3: スキル適性評価

ステップ 0: 既存スキルとの照合

パターン評価の前に、ユーザー環境にインストール済みのスキルを列挙し、抽出したパターンとの重複を確認する。

手順:

1. ~/.claude/skills/ と .claude/skills/（プロジェクト固有）配下のスキルを Glob で列挙する
2. 各スキルの SKILL.md のフロントマター（name, description）を読み取る
3. 抽出したパターンと既存スキルを照合し、以下の3分類に振り分ける:
   • 完全カバー済み: 既存スキルがパターンの手順を完全にカバーしている → 候補から除外
   • 部分カバー: 既存スキルが一部のステップをカバーしているが、フロー全体はカバーしていない → 差分（未カバーの部分）のみ候補として残す。提示時に「既存の [スキル名] を含むフロー」と注記する
   • 未カバー: 既存スキルでカバーされていない → そのまま候補として残す

例: 既存に /commit スキルがある場合:

• WHAT「コミットする」→ 完全カバー済み → 除外
• FLOW「レビュー→修正→コミット」→ 部分カバー（コミット部分は既存だが、フロー全体は未カバー）→ 差分で残す

ステップ 1: スコアリング

各タスクパターンのスキル化優先度を以下の指標で評価:

頻度 — 出現回数。多いほど自動化の効果が高い

一貫性 — セッション間で手順がどれだけ共通しているか

• HIGH: 毎回ほぼ同じ手順で実行される（例: コミットフロー）
• MEDIUM: 手順の骨格は共通だが、判断・パラメータが異なる（例: レビュー→修正）
• LOW: 毎回異なるアプローチが必要（例: 未知のバグの調査）

自動化可能なステップ数 — スキルで手順化できるステップの割合

• ワークフローの何割が定型的な手順か
• 人間の判断が必要なステップはどこか

ステップ 2: ランク付け（内部処理）

以下の基準で内部的にランク付けする。この詳細なスコアリング結果はユーザーには見せない。

• FLOW パターンは複数ステップをカバーするため、スキル化時の網羅性が高い
• HOW パターンは横断性が高いほどスキル化の価値が高い
• FLOW が WHAT を内包している場合、FLOW を優先する

内部判断基準:

• スキル化推奨: FLOW で頻度3以上かつ一貫性 MEDIUM 以上 / WHAT で頻度が高く一貫性 HIGH
• スキル化価値あり: 頻度が中程度 or 一貫性 MEDIUM / HOW で横断 WHAT 数が 3 以上
• スキル化不向き: 毎回異なる対応が必要 / 一貫性 LOW で自動化率も低い

ステップ 3: ユーザーへの提示

内部スコアリングの詳細（一貫性、自動化率、スキル向き度等）はユーザーに見せない。 ユーザーにはシンプルなリストで候補を提示する。

提示フォーマット:

スキル化推奨:
1. [パターン名] (N回) — [1行の説明]
2. [パターン名] (N回) — [1行の説明]

スキル化の価値あり:
3. [パターン名] (N回) — [1行の説明]
4. [パターン名] (N回) — [1行の説明]

各候補に対し、必要に応じて代表的なプロンプトを1-2件添えて補足する。 FLOW が WHAT を内包している場合、「[FLOW名] は [WHAT名] を含む」と一言添える。

Phase 4: ユーザー選択

1. ユーザーにどのタスクパターンをスキル化するか選択してもらう（複数選択可）
2. 選択されたパターンについて、history.jsonl から該当セッションのプロンプトを表示
3. 以下を確認:
   • スキルのスコープ（手順のどこからどこまでをカバーするか）
   • バリエーションの扱い（オプションにするか、別スキルにするか）
   • 配置先: グローバル（~/.claude/skills/）or プロジェクト固有（.claude/skills/）
   • トリガーフレーズ
4. 特定セッションの詳細が必要な場合、個別 .jsonl を2-3件読む

CLI 履歴モードが有効な場合:

• 選択されたパターンの代表的なコマンドチェインを表示
• どのコマンドをスキルの手順に含めるか確認

Phase 5: スキル生成

絶対ルール

• 生のセッション内容をそのままスキルに貼り付けてはならない
• YAML フロントマターやスキル本文に山括弧文字を含めてはならない
• 例を引用する場合は言い換えるかサニタイズする（例: < と > を使用、または [ と ] に置換）
• ログからシークレット、トークン、プライベート識別子をスキルに含めてはならない

スキルの手動作成

以下のフォルダ構造で作成する:

{skill-name}/
  SKILL.md          # メインの手順書（必須）
  scripts/          # ヘルパースクリプト（必要な場合）
  references/       # 補足ドキュメント（必要な場合）

SKILL.md の要件:

• YAML フロントマターに name（kebab-case）と description（何を + いつ + トリガーフレーズ）を含める
• 明確な番号付きワークフローステップ
• よくあるエラーへの対処法
• 少なくとも2つの使用例
• 500行以内

分析したセッション情報を活用して:

• 具体的なコマンドシーケンスやパターンを抽出する（言い換え、生のコピーは禁止）
• 共通パラメータとバリエーションを特定する
• 過去の実際のワークフローに基づいたリアルな使用例を書く（サニタイズ済み）
• CLI 履歴モードが有効な場合: 最も頻出のコマンドチェインをベースにするが、パラメータ化されたステップに変換する（ハードコードされた絶対パスは避ける）

配置先

• グローバル: ~/.claude/skills/{skill-name}/
• プロジェクト固有: .claude/skills/{skill-name}/

Phase 6: 品質検証

以下の手順で生成したスキルを検証する:

1. WebFetch で公式ベストプラクティス (https://platform.claude.com/docs/ja/agents-and-tools/agent-skills/best-practices) を取得し、記載されたガイドラインに照合する
2. references/quality-checklist.md の全項目を確認する
3. 不合格の項目があれば修正して再検証する
4. 最終結果をユーザーに報告する（不合格項目がなければ簡潔に「全項目パス」と伝える）

評価シナリオ

スキルの動作検証やモデル変更時の回帰テストには references/evaluations.md を参照。8つのシナリオで基本フロー・フォールバック・安全性・CLI照合・サイズ超過・既存スキル重複・ペーストテキスト・HOW横断検出をカバーしている。

使用例

例 1: 現在のプロジェクトを分析

ユーザー: 「履歴を分析して」
実行内容:
1) 同意を得て ~/.claude/history.jsonl を読み取る
2) 現在のプロジェクトでフィルタし、タスクパターンを抽出
3) シンプルなリストで提示:
   スキル化推奨:
   1. 変更を適切な粒度でコミット (18回) — 除外パターン付きの定型コミットフロー
   2. レビュー指摘→修正→コミット (12回) — PR指摘の一括修正からコミットまで
   スキル化の価値あり:
   3. エージェントチーム組成で並列実行 (6回) — リファクタリング/レビュー対応等で横断的に使用
4) ユーザーが上位2つを選択
5) 2つのスキルを生成

その他の使用例（全プロジェクト横断、時間範囲指定、CLI履歴分析）は references/examples.md を参照。

例 2: HOW パターンの検出

ユーザー: 「履歴を分析して」
実行内容:
1) 同意を得て ~/.claude/history.jsonl を読み取る
2) WHAT/HOW/FLOW の三軸で抽出・内部スコアリング
3) シンプルなリストで提示:
   スキル化推奨:
   1. 変更を適切な粒度でコミット (18回) — 除外パターン付きの定型コミットフロー
   2. レビュー指摘→修正→コミット (12回) — PR指摘の一括修正からコミットまで
   スキル化の価値あり:
   3. エージェントチーム組成で並列実行 (6回) — リファクタリング/レビュー対応/UI共通化で横断的に使用
   4. code-simplify で変更後コードをシンプル化 (3回) — レビュー後や機能実装後に繰り返し使用
4) ユーザーが「エージェントチーム組成で並列実行」を選択
5) チームオーケストレーションスキルを生成

例 3: FLOW パターンの検出（セッションフロー分析）

ユーザー: 「履歴を分析して」
実行内容:
1) 同意を得て ~/.claude/history.jsonl を読み取る
2) セッション単位のフロー分析 + WHAT/HOW 抽出 → 内部スコアリング
3) シンプルなリストで提示:
   スキル化推奨:
   1. UI/UX改善洗い出し→一括対応→コミット (4回) — 洗い出しから対応・コミットまでの一連フロー
      ※「UI改善点洗い出し」「コミット」を含む
   2. レビュー指摘修正→検証→コミット→PR (3回) — PRレビュー指摘の修正フロー全体
   スキル化の価値あり:
   3. 変更を適切な粒度でコミット (18回) — 単独でも頻出する定型コミットフロー
4) ユーザーが「UI/UX改善フロー」を選択
5) 洗い出し基準・対応テンプレート・完了コミットまでを一貫カバーするスキルを生成

注意事項

• ~/.claude/history.jsonl を第一データソースとして使用する。1ファイルで全プロジェクト・全セッションのプロンプトを取得できる
• 個別セッション .jsonl は特定セッションの詳細分析が必要な場合のみ読む
• sessions-index.json は既知のバグにより信頼性が低い。存在すれば補助情報として使うが、依存しない
• ユーザーの使用言語に合わせて応答する（日本語で会話している場合は全て日本語で）
• 生成するスキルに scripts/ を含めてもよいが、このスキル自体はスクリプトを実行しない

フォールバック: history.jsonl が存在しない場合

~/.claude/history.jsonl が存在しない場合のみ、個別セッション .jsonl から firstPrompt を抽出するフォールバック手順に移行する。詳細は references/fallback-guide.md を参照。

よくある問題

history.jsonl が見つからない

~/.claude/history.jsonl が存在しない場合、references/fallback-guide.md のフォールバック手順に移行する。

history.jsonl が大きすぎる（Read ツールの 256KB 制限超過）

通常は 1MB 未満だが、長期間使用で Read ツールのサイズ制限（256KB）を超える場合がある:

• 推奨: 同梱の scripts/filter-history.py を Bash で実行する（Phase 1 手順 4 を参照）
• 代替: Read ツールの offset/limit パラメータで末尾（最新エントリ）から読む
• スクリプトの出力が Bash の表示上限（30KB）を超える場合は、ファイルにリダイレクトして Read で読み取る

JSON パースエラーまたは不正なコンテンツ

• 処理を中断し、ユーザーにスコープを縮小するか時間範囲を変更するか確認する

指定範囲にセッションがない

• ユーザーに時間範囲の拡大または全プロジェクトの選択を提案する