firelive/agent-skills

ソース / 上流

• 上流: https://github.com/kangarooking/cangjie-skill
• ライセンス: MIT
• ベンダー先: Moi/Codex共有インストール用として .agents/skills/book-to-skill-distill/SKILL.md
• 注: 完全なパイプラインを使用するには、上流リポジトリの methodology/ と extractors/ も必要です。

このファイルはベンダーコピーまたは簡易ポインタの場合があります。アセット、スクリプト、AGPL義務が含まれる場合は、上流リポジトリをインストール/クローンすることを推奨します。

cangjie-skill — 本を実行可能なスキルセットに蒸留するメタスキル

使命

本に凝縮された方法論を原子化され、エージェントが実際のシナリオで呼び出せる能力に分解し、ユーザーの目的に応じて適切な数のスキルにコンパイルすることで、読者が本当に活用できるようにします。

用語の定義: このドキュメント、methodology/、extractors/ 内の「本」とは、蒸留の対象となるあらゆる長文コンテンツ（書籍、長編動画の文字起こし、ポッドキャストの原稿、コース、インタビュー、長文記事、資料集）を指します。

境界線:

• ✅ 対象: 方法論 / 意思決定フレームワーク / 操作手順 / 計算ルール / トラブルシューティング / チェックリスト / 原則の蒸留。概念体系は参考情報としてサポートします。
• ❌ 非対象: 書抜き / 読書感想文 / 著者のペルソナロールプレイ（これらは nuwa-skill を使用してください）

中核方法論: RIA-TV++（v2.5 Bundle版）

5フェーズ + 並列抽出 + トリプル検証 + プロモーションゲート + darwin互換テストで構成されるパイプラインです。詳細は methodology/00-overview.md を参照してください。

フェーズ 0:   Adler 全体理解            → BOOK_OVERVIEW.md
フェーズ 1:   5エージェント並列抽出       → 候補方法論ユニットプール
フェーズ 1.5: トリプル検証（知識検証）    → 通過ユニット（ユーザー軽確認）
フェーズ 1.6: 独立スキルプロモーションゲート（製品化検証）→ promoted / router 行き先
フェーズ 2:   RIA++ 能力カード構築       → .cangjie/capabilities/cards/<slug>.md
フェーズ 3:   Zettelkasten リンク        → verified.yaml の also_read + GLOSSARY
フェーズ 4:   ストレステスト (darwin 互換) → 評価テストケース + 差し戻し廃棄
フェーズ 5:   コンパイルと納品            → cangjie.py compile（single/pack）+ DIGEST.md + インストール

v2.5 の主要変更点（ADR-002）: フェーズ 2～4 では、各ユニットを個別の最終スキルディレクトリとして書き出す代わりに、Capability Bundle（books/<slug>/.cangjie/capabilities/verified.yaml + cards/*.md）を生成します。single と pack はどちらも、この同一の Bundle から scripts/cangjie.py compile によって決定的にコンパイルされ、安定した capability_id を参照します。古い one-to-one 出力もサポートされています（legacy-pack、docs/migrations/2026-08-25-v2.0-to-v2.1.md を参照）。

このスキルを呼び出すタイミング

ユーザーが以下のようなリクエストをした場合:

• 「『プア・チャーリーの宝庫』を分解して」
• 「毛沢東選集をスキルに蒸留して」
• 「このB站動画/ポッドキャスト/コースをスキルに蒸留して」
• 「この本をスキルに蒸留して: <パス>」
• 「この本の方法論を使えるスキルにしたい」

入力要件

開始する前に、ユーザーから必ず以下の情報を確認してください:

スクリプト依存関係: 決定的スクリプト（scripts/）には Python 3.10+ と PyYAML（python3 -m pip install pyyaml）が必要です。PyYAML がない場合は、先に python3 scripts/cangjie.py doctor を実行してセルフチェックを行い、インストール手順を表示します。

1. コンテンツテキストソース: PDF / EPUB / TXT / 字幕ファイル / 文字起こしファイルのパス、またはアクセス可能なプレーンテキスト。「記憶だけ」で蒸留しないでください — 必要な場合はユーザーに問い合わせてください。（動画/ポッドキャストの場合は、まず video-downloader 系ツールで文字起こしテキストを取得することを推奨します）
2. コンテンツメタ情報: 書籍の場合は「タイトル + 著者 + 出版年」；動画/ポッドキャスト/コースの場合は「タイトル + 作成者（UP主/ホスト/講師）+ 公開日」。ディレクトリ名や監査に使用します。
3. 利用目的（出力モードの推奨を決定するため）: 学習/参照目的 → single を推奨；日常のワークフローに組み込む、複数コンテンツを横断して使用する → pack を推奨。不明な場合は、single-first の原則で single を推奨します。
4. 初回トライアルかどうか: ユーザーが cangjie-skill を初めて使用する場合は、最初に1つのコンテンツでプロセスを検証してから、バッチ処理を進めることを推奨します。

非書籍コンテンツのフィールドマッピング: 章に相当するフィールドには、動画の場合はタイムスタンプまたは分割番号、ポッドキャストの場合はエピソード番号、コースの場合は講義番号を入力します。トレーサビリティが確保されていれば問題ありません。

出力構造

books/<book-slug>/
├── PIPELINE_STATE.md          # パイプライン状態: 現在のフェーズ + 進捗（再開用）
├── BOOK_OVERVIEW.md           # フェーズ 0 の成果物: 主旨/骨子/用語/批評
├── verified.md                # フェーズ 1.5 の成果物: トリプル検証通過ユニット + 判定理由
├── coverage-audit.md          # 原書の主要タスク → 候補 → 判定 → 実際の納品先
├── references.md              # 根拠はあるが実行しない参考コンテンツと納品先マッピング
├── needs-review.md            # 出典/条件/テストのギャップ；アクティブな能力としてコンパイルしない
├── GLOSSARY.md                # フェーズ 3 の成果物: 全コンテンツ共通の用語集
├── DIGEST.md                  # フェーズ 5 の成果物: 読者向けの精選された要約記事
├── candidates/                # フェーズ 1 の成果物: 生の候補プール（監査用）
├── rejected/                  # フェーズ 1.5 で廃棄されたユニット + 理由（監査用）
└── .cangjie/                  # v2.5 サイドカー層（コンパイルの事実ソース + 実行記録）
    ├── capabilities/
    │   ├── verified.yaml      # Capability Bundle（唯一のコンパイル事実ソース, capability-bundle.schema.json）
    │   ├── cards/<slug>.md    # RIA 能力カード（R/I/A1/A2/E/B, フェーズ 2 の成果物）
    │   ├── resources/         # 能力が明示的に宣言する UTF-8 スクリプト、CSV/JSON/Markdown テンプレート（オプション）
    │   ├── destinations.json  # プロモーション/ルーティング先マッピング（フェーズ 1.6 の成果物）
    │   └── book/{overview.md,glossary.md}
    ├── runs/<run-id>/         # 各コンパイル/更新の決定レポートと検証ログ
    └── snapshots/             # リリース前のスナップショット（ロールバック用）

最終成果物は scripts/cangjie.py compile によって Bundle からコンパイルされます（--output single で 1 エントリ + 能力カード；--output pack で 1 つのソースルーティングエントリ + 少数のプロモーション済みスキル）。

実行フロー（厳守順序）

再開可能: 開始する前に books/<slug>/PIPELINE_STATE.md が存在するか確認してください。存在する場合は、記録されたフェーズから再開し、最初からやり直さないでください。各フェーズが完了するたびに、このファイルを更新します。

フェーズ 0 — 全体理解

1. ユーザーから提供されたコンテンツテキストを読み込みます。大きなファイルはチャンクに分割して読みます。
2. methodology/01-stage0-adler.md の Adler 4ステップ（構造化 / 解釈 / 批評 / 応用）を実行します。
3. templates/BOOK_OVERVIEW.md.template に従って埋め込み、books/<slug>/BOOK_OVERVIEW.md に書き出します。
4. 成果物をユーザーに提示して確認を取ります：「骨子の理解はこれで正しいですか？重点的に強調したい方向性はありますか？」確認が取れたらフェーズ 1 に進みます。

フェーズ 1 — 5つのサブエージェントによる並列抽出

並列で 5 つの Task サブエージェントを spawn します（Agent ツールを使用し、1回の呼び出しで 5 つ起動）:

サブエージェント	読み込むプロンプト	コンテキスト戦略	成果物
フレームワーク抽出器	extractors/framework-extractor.md	全量スキャン（章をまたがるものと単一箇所で完結するメカニズムの両方を考慮）	意思決定フレームワーク / 思考モデル / プロセス / トラブルシューティング
原則抽出器	extractors/principle-extractor.md	全量スキャン（数式、表、脚注を含む）	原則 / チェックリスト / ルール / 計算式
事例抽出器	extractors/case-extractor.md	検索式でチャンク取得（部分一致型）	本書の具体例、パラフレーズ事例、練習問題、タイプを明記
反例抽出器	extractors/counter-example-extractor.md	検索式でチャンク取得（部分一致型）	本書で警告されている失敗パターン
用語抽出器	extractors/glossary-extractor.md	検索式でチャンク取得 + スクリプト事前フィルタリング	キーコンセプト用語集

各サブエージェントは独立して判断し、books/<slug>/candidates/<type>.md に独立して出力します。

• 長いテキスト: 単一のサブエージェントのコンテキストに収まらないコンテンツは、methodology/02-stage1-parallel-extract.md の分割戦略に従って処理します。コンテンツインデックス（.cangjie/index/）が既に存在する場合、検索式抽出器はインデックスを使って関連チャンクを取得します。
• カバレッジハードゲート: 全量スキャン候補とフェーズ 0 の原書主要タスクリストを同時に照合し、旧バージョンの通過項目のみをチェックしないでください。主要タスクには候補と明確な行き先が必要です。説明のつかない欠落がある場合は、もう一度読み直すか全量スキャンに戻し、ゼロ欠落を虚偽報告しないでください。
• ダウングレードオプション: 現在の環境が並列サブエージェントをサポートしていない場合は、同じ 5 つの抽出器プロンプトを直列で実行し、出力フォーマットは変えません。

フェーズ 1.5 — トリプル検証（知識検証）

methodology/03-stage1.5-triple-verify.md を読み込み、各候補ユニットに対して以下を実行:

• V1 出典の十分性: 限定された範囲のプラクティスをサポートするのに十分な原文が特定できますか？完全なメカニズムが一箇所で説明されていれば合格です。
• V2 実行可能性: 正当な新しい入力を使ってタスクを完了し、結果を検証できますか？分野をまたがる外挿は必須ではありません。
• V3 タスクへの貢献度: 見落としを減らし、口径を統一し、安定した納品を実現できますか？著者のオリジナリティは必須ではありません。

verified / reference / needs_review / rejected に分流し、根拠とギャップを記録します。参考コンテンツは実際に納品される overview/glossary にマッピングする必要があり、不合格項目すべてを廃棄するわけではありません。coverage-audit.md を更新します。

ユーザー軽確認 ★: 実行可能候補、参考、要確認、廃棄の4つのカテゴリと重要なギャップをユーザーに提示し、確認を取ってからフェーズ 1.6 に進みます。確認は出典検証の代替にはなりません。

フェーズ 1.6 — 独立スキルプロモーションゲート（製品化検証）

methodology/03b-stage1.6-promotion-gate.md を読み込みます。知識検証に合格したからといって、独立したスキルとしての価値があるとは限りません。各ユニットに対して5つの判定基準（独立した意図/独立した契約/独立した実行/独立した再利用/独立した評価、上位3基準は必須、下位2基準は少なくとも1つを満たすこと）を審査し、行き先を Bundle の promotion.destination（promoted / router）に書き込みます。プロモーションされなかったユニットは廃棄されず、ソースルーティングエントリ内の能力カードとして保持されます。発見用のエントリソフトバジェットはデフォルトで 8（ソースルーティングエントリ1つを含む）です。

フェーズ 2 — RIA++ 能力カード構築

合格した各ユニットに対して、methodology/04-stage2-ria-plus.md に従って R / I / A1 / A2 / E / B の6セクションからなる能力カードを構築します:

• カード本文は books/<slug>/.cangjie/capabilities/cards/<slug>.md に書き込みます（frontmatter なし、frontmatter データは Bundle に記録されます）;
• 同時に、verified.yaml にこの能力を登録します: 安定した capability_id、intents、keywords、one_liner、importance（根拠付き）、frontmatter.description（A2 の要約版）。
• A1 は原書の事例と明示的にマークされた合成練習問題を区別します。E は入力、出力、分岐、完了条件を明確にします。必要に応じて、resources を通じて付随するテキストリソースを明示的に宣言します（フェーズ 2 の説明を参照）。

フェーズ 3 — Zettelkasten リンク

methodology/05-stage3-zettelkasten.md に従います:

1. 能力間の参照関係を特定し、Bundle 内の各能力の also_read に書き込み、A2 の「隣接する能力との区別」もバックフィルします。
2. candidates/glossary.md を整理して books/<slug>/GLOSSARY.md を作成し、.cangjie/capabilities/book/glossary.md にコピーします。
3. INDEX/ルーティングテーブルはコンパイラが Bundle から生成するため、手書きは不要です。
4. references.md に保持が必要なコンテンツを Bundle の book/overview.md または book/glossary.md にマージし、カバレッジ監査に実際のパスを記録します。確認待ちコンテンツを実行可能な方法として偽装しないでください。

フェーズ 4 — ストレステスト (darwin 互換)

methodology/06-stage4-pressure-test.md に従い、プロモーションされた能力はトリガーをテストし、ルーター能力は到達可能性をテストします。両方とも実際に代表的なタスクを完了し、出力を照合する必要があります。「呼び出せる」ことを「正しくできる」ことの代替にしてはいけません。出力がない場合は評価の分母にカウントされ、未完了の場合は合格を宣言できません。不合格の場合はフェーズ 2 に差し戻します。

フェーズ 5 — コンパイルと納品

methodology/07-stage5-deliver.md に従います:

1. books/<slug>/DIGEST.md — 読者向けの精選された要約記事を生成します。
2. python3 scripts/cangjie.py compile --bundle books/<slug>/.cangjie/capabilities --out <ターゲットディレクトリ> --output auto を実行し、決定レポートをユーザーに提示して軽確認を取ります（推奨 / single に変更 / pack に変更）。
3. ユーザーにインストール場所を尋ね、コンパイル成果物をコピーまたはシンボリックリンクを作成します。
4. ユーザーに通知します：「完了しました。darwin-skill にそのまま渡して自動進化させることができます。」

品質レッドライン（違反した場合は出力をブロック）

1. 各能力はすべてのトリプル検証を通過する必要があります。
2. 各能力カードには R / I / A1 / A2 / E / B の完全な6セクションが必要です。A1 に原書の事例がない場合は正直に明記し、合成練習問題を書中の事実として偽装しないでください。
3. 原文引用は 150 字/段落以内（英語の場合は 100 語/段落以内）。
4. 各アクティブ能力は destinations.json 内にちょうど1つの行き先（promoted_to または served_by）を持ちます。プロモーションされなかった能力は、ソースルーティングエントリ経由で到達可能でなければなりません。
5. プロモーションされたスキルの description はトリガー条件を明確にし、ソースルーティングエントリと互いに近隣の負例を持つ必要があります。
6. コンパイル成果物は scripts/validate_skill_pack.py（フォーマット/相対参照/frontmatter 100%）を通過する必要があります。
7. 生成ディレクトリは読み取り専用として扱います。ローカルで手動変更が検出された場合、サイレントに上書きしてはなりません（コンパイラは3つのオプションから強制的に選択させます）。
8. 主要タスクのカバレッジにはトレーサブルな行き先が必要です。実際の出力評価と出典確認はそれぞれ別に記録します。重要なギャップがある場合、明確に範囲を明記したドラフトのみを納品でき、完全な合格を宣言してはいけません。

nuwa-skill / darwin-skill とのエコシステム上の位置づけ

• nuwa-skill: 人を蒸留する（思考様式 / 表現の DNA）
• cangjie-skill（本スキル）: 本を蒸留する（方法論 / フレームワーク / 原則）
• darwin-skill: 任意のスキルを進化させる

3つは連動しています。本スキルが出力する評価テストケースは darwin-skill のフォーマットに準拠しているため、生成されたスキルをそのまま darwin に渡して自動進化させることが可能です。

呼び出しルール

• 常に最初に1つをトライアルする — ユーザーが明示的に「バッチで」と言わない限り。
• フェーズ間で積極的に進捗を報告する — サイレントに全て実行してから結果を dump しない。
• 記憶だけで本を分解しない — テキストがなければ立ち止まって尋ねる。
• 監査証跡を保持する — candidates/ と rejected/ は必ず残す。
• いつでも再開可能 — 各フェーズが完了するたびに PIPELINE_STATE.md を更新し、中断後は状態ファイルから復元する。
• 出力戦略は永続化する — update/repair はデフォルトで元の出力モードを引き継ぎ、新しいマテリアルが追加されてもサイレントに成果物の形態を変更しない。