extract

スキルの抽出

通常は SessionStart フックによって自動実行されます。

前回のセッションから保留中の学習事項の抽出を処理します。

仕組み

SessionStart フックは次を実行します。

ao extract

これにより、キューに登録された抽出項目を確認し、Claude が処理するためのプロンプトを出力します。

手動実行

/extract が指定された場合：

ステップ 1：保留中の抽出項目を確認する

ao extract 2>/dev/null

または、保留中のキューを確認します。

cat .agents/ao/pending.jsonl 2>/dev/null | head -5

ステップ 1.5：ao CLI がない場合 — 手動で抽出する

ao CLI が利用できない場合は、保留中のキューを手動で処理します。

if ! command -v ao &>/dev/null; then
  echo "ao CLI not available — running manual extraction"

  # Check for pending queue
  if [ -f .agents/ao/pending.jsonl ] && [ -s .agents/ao/pending.jsonl ]; then
    echo "Found pending extractions:"
    cat .agents/ao/pending.jsonl

    # For each pending entry, check for corresponding forge output
    # Forge outputs live in .agents/forge/
    for forge_file in .agents/forge/*.md; do
      [ -f "$forge_file" ] || continue
      echo "Processing: $forge_file"
    done
  else
    echo "No pending extractions found."
  fi

  # After processing, check .agents/forge/ for unprocessed candidates
  FORGE_COUNT=$(ls .agents/forge/*.md 2>/dev/null | wc -l | tr -d ' ')
  if [ "$FORGE_COUNT" -gt 0 ]; then
    echo "$FORGE_COUNT forge candidates found — review and extract learnings manually."
    echo "For each candidate in .agents/forge/:"
    echo "  1. Read the candidate file"
    echo "  2. Extract actionable learnings using the template in Step 3"
    echo "  3. Write to .agents/learnings/YYYY-MM-DD-<topic>.md"
    echo "  4. High-confidence items (>= 0.7) can be promoted directly"
  fi
fi

各 forge 候補について、このスキルのステップ 3 で定義されているのと同じテンプレート形式で学習事項を抽出します。結果は .agents/learnings/ に書き込みます。処理後、保留中のキューを空にします。

# Clear processed entries
> .agents/ao/pending.jsonl
echo "Pending queue cleared"

ステップ 2：保留中の各項目を処理する

キューに登録された各セッションについて：

1. セッションの概要を読む
2. 実行可能な学習事項を抽出する
3. .agents/learnings/ に書き込む

ステップ 3：学習事項を書き込む

書き込み先： .agents/learnings/YYYY-MM-DD-<session-id>.md

# Learning: <Short Title>

**ID**: L1
**Category**: <debugging|architecture|process|testing|security>
**Confidence**: <high|medium|low>

## What We Learned

<1-2 sentences describing the insight>

## Why It Matters

<1 sentence on impact/value>

## Source

Session: <session-id>

ステップ 3.5：学習事項を検証する

学習ファイルを書き込んだ後、それぞれに必須フィールドがあることを検証します。

1. 新しく書き込んだファイルをスキャンします。

ls -t .agents/learnings/YYYY-MM-DD-*.md 2>/dev/null | head -5

2. 各ファイルの必須フィールドを確認します。

   • 見出し： ファイルは # Learning: <title>（空でないタイトル）で始まる必要があります
   • カテゴリ： **Category**: <value> を含み、値は debugging、architecture、process、testing、security のいずれかである必要があります
   • 信頼度： **Confidence**: <value> を含み、値は high、medium、low のいずれかである必要があります
   • 内容： ## What We Learned セクションを含み、その見出しの後に空でない行が少なくとも 1 行ある必要があります

3. 検証結果を報告します。

   • 有効な学習事項ごとに「✓ : valid」
   • 無効な学習事項ごとに「⚠ : missing 」（不足しているフィールドをそれぞれ列挙）

4. 無効な学習事項を削除したり、再試行したりしないでください。 警告を記録して処理を続けます。無効な学習事項でも、何もないよりは有益です。この警告により、抽出品質の問題を長期的に特定しやすくなります。

ステップ 4：キューを空にする

ao extract --clear 2>/dev/null

ステップ 5：完了を報告する

ユーザーに次の内容を伝えます。

• 抽出した学習事項の数
• 主な知見
• 学習ファイルの保存場所

ナレッジループ

Session N ends:
  → ao forge --last-session --queue
  → Session queued in pending.jsonl

Session N+1 starts:
  → ao extract (this skill)
  → Claude processes the queue
  → Writes to .agents/learnings/
  → Validates required fields
  → Loop closed

主なルール

• 自動実行されます — 通常はフック経由です
• キューを処理します — 抽出項目を保留のままにしないでください
• 具体的に記述します — 曖昧な所見ではなく、実行可能な学習事項を記述します
• ループを完了させます — 抽出によってナレッジサイクルが完了します

例

SessionStart フックの呼び出し

フックのトリガー： セッション開始時に session-start.sh が実行されます

処理内容：

1. フックが ao extract 2>/dev/null を呼び出します
2. CLI がキューに登録されたセッション ID とプロンプトを出力します
3. エージェントが保留中の各抽出項目を処理します
4. エージェントが学習事項を .agents/learnings/<date>-<session>.md に書き込みます
5. エージェントが必須フィールドを検証し、結果を報告します
6. フックが ao extract --clear を呼び出してキューを空にします

結果： ユーザーが操作しなくても、前回のセッションの知識がセッション開始時に自動で抽出されます。

手動での抽出の開始

ユーザーの発言： /extract または「前回のセッションから学習事項を抽出して」

処理内容：

1. エージェントが ao extract で保留中のキューを確認します
2. エージェントがキュー内のセッション概要を読みます
3. エージェントが判断、学習事項、失敗を抽出します
4. エージェントが適切な構成で .agents/learnings/ に書き込みます
5. エージェントがフィールド（カテゴリ、信頼度、内容）を検証します
6. エージェントがキューを空にし、完了を報告します

結果： 保留中の抽出項目が手動で処理され、キューが空になり、学習事項がインデックス化されます。

トラブルシューティング

問題	原因	解決策
保留中の抽出が見つかりません	キューが空か、ao CLI を利用できません	.agents/ao/pending.jsonl が存在することを確認し、ao CLI がインストールされていることを確認してください
学習内容が無効という警告	カテゴリ、信頼度、コンテンツが不足しています	学習ファイルを確認し、不足しているフィールドを追加してください。削除しないでください
extraction --clear が失敗します	CLI を利用できないか、権限エラーが発生しています	フォールバックとして、.agents/ao/pending.jsonl を手動で空にしてください
抽出内容が重複します	処理後にキューがクリアされていません	学習内容を書き込んだ後は、必ず ao extract --clear を実行してください