cangjie-skill

cangjie-skill — 一冊の本を、実行可能な一連のスキルに蒸留するメタスキル

使命

一冊の本に蓄積された方法論を、原子化され、エージェントが実際の状況で呼び出せる能力に分解し、ユーザーの目的に合わせた適切な数のスキルにコンパイルすることで、読者が実際に活用できるようにします。

用語の定義: 本ドキュメントおよび methodology/、extractors/ における「本」は、蒸留対象となるあらゆる長文コンテンツを指します。書籍、長時間の動画の書き起こし、ポッドキャストの文字起こし、講座、インタビュー、長文記事、資料集などが含まれます。

対象範囲:

• ✅ 行うこと: 方法論／意思決定のフレームワーク／操作手順／計算ルール／トラブルシューティング／チェックリスト／原則を蒸留し、概念体系は参考資料として扱います
• ❌ 行わないこと: 書籍からの抜粋／読後感／著者の人物像を演じるロールプレイ（後者には nuwa-skill を使用してください）

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

5 段階のパイプラインに、並列抽出、三重検証、昇格ゲート、darwin 互換テストを組み合わせたものです。詳しくは methodology/00-overview.md を参照してください。

阶段 0:   Adler 整书理解        → BOOK_OVERVIEW.md
阶段 1:   5 个 agent 并行提取    → 候选方法论单元池
阶段 1.5: 三重验证筛选（知识验证） → 通过的单元 (用户轻确认)
阶段 1.6: 独立 Skill 晋级门（产品化验证）→ 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 では、各ユニットを独立した最終 Skill ディレクトリに直接書き出す方式をやめ、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 件蒸留してワークフローを検証することを推奨します。

書籍以外のコンテンツにおける項目の対応付け: 章に相当する項目は、動画ではタイムスタンプまたは分 P、ポッドキャストではエピソード番号、講座では講義番号を記入します。追跡できることが重要です。

出力構造

books/<book-slug>/
├── PIPELINE_STATE.md          # 流水线状态: 当前阶段 + 进度 (断点续跑用)
├── BOOK_OVERVIEW.md           # 阶段 0 产出: 主旨/骨架/术语/批判
├── verified.md                # 阶段 1.5 产出: 通过三重验证的单元 + 判定理由
├── coverage-audit.md          # 原书关键任务 → 候选 → 判定 → 实际交付去向
├── references.md              # 有依据但不执行的参考内容及交付映射
├── needs-review.md            # 来源/条件/测试缺口；不编译为 active 能力
├── 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/             # 发布前快照（rollback 用）

最終成果物は scripts/cangjie.py compile によって Bundle からコンパイルされます（--output single は 1 つのエントリーポイント + 能力カード、--output pack は 1 つのソースルーティング用エントリーポイント + 少数の昇格済み Skill を生成します）。

実行フロー（順番を厳守）

中断箇所からの再開: 開始前に 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 つの sub-agent による並列抽出

5 つの Task sub-agents を並列で起動します（Agent ツールを使用し、1 回の呼び出しで 5 つを起動します）。

sub-agent	読み込む prompt	コンテキスト方針	成果物
フレームワーク抽出器	extractors/framework-extractor.md	全体をスキャン（章をまたぐ仕組みと、一箇所で完結している仕組みの両方を対象）	意思決定のフレームワーク／思考モデル／プロセス／トラブルシューティング
原則抽出器	extractors/principle-extractor.md	全体をスキャン（数式、表、脚注を含む）	原則／チェックリスト／ルール／計算基準
事例抽出器	extractors/case-extractor.md	検索ベースのブロック取得（局所的な該当箇所を対象）	書籍内の事例、再話されたケース、例題。種類を明記
反例抽出器	extractors/counter-example-extractor.md	検索ベースのブロック取得（局所的な該当箇所を対象）	書籍で警告されている失敗パターン
用語抽出器	extractors/glossary-extractor.md	検索ベースのブロック取得 + スクリプトによる事前フィルタリング	重要概念の用語集

各 sub-agent は独立して判断し、books/<slug>/candidates/<type>.md に出力します。

• 長文: 内容が単一の sub-agent のコンテキストに収まらない場合は、methodology/02-stage1-parallel-extract.md の分割方針に従って処理します。内容インデックス（.cangjie/index/）がすでにある場合、検索ベースの extractor はインデックスから関連ブロックを取得します。
• 網羅率の必須ゲート: 全体スキャンで得た候補とフェーズ 0 の原書における重要タスクリストを同時に照合し、旧版で合格した項目だけを確認するのではなく、重要なタスクには候補と明確な振り分け先が必要です。説明されていない見落としがあれば、該当箇所を追加で読み込むか、全体スキャンに戻します。見落としがないと偽ってはいけません。
• フォールバック: 現在の環境で sub-agent の並列実行がサポートされていない場合は、同じ 5 つの extractor prompt を順番に実行します。出力形式は変わりません。

フェーズ 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 — 独立 Skill への昇格ゲート（プロダクト化の検証）

methodology/03b-stage1.6-promotion-gate.md を読みます。知識検証に合格しても、独立した Skill にする価値があるとは限りません。各ユニットについて 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 六段能力卡:

• 卡片正文写入 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，晋级能力测触发，router 能力测可达；两类都要实际完成代表任务并核对输出，不能用“会调用”替代“做得对”。缺失输出计入评测分母，未完成不得声明通过。未过的回炉重做阶段 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. 询问用户安装位置,把编译产物复制或 symlink 过去
4. 告知用户: "已完成,可一键喂给 darwin-skill 自动进化"

质量红线 (违反则阻止输出)

1. 每个能力必须通过全部三重验证
2. 每张能力卡必须有完整的 R / I / A1 / A2 / E / B 六段；A1 无原书案例时如实标注，合成演练不冒充书中事实
3. 原文引用 ≤150 字/段 (英文 ≤100 词/段)
4. 每个 active 能力在 destinations.json 中恰好一个去向（promoted_to 或 served_by）;未晋级能力必须可经来源路由入口到达
5. 晋级 Skill 的 description 必须明确 trigger 条件,并与来源路由入口互有近邻负例
6. 编译产物必须通过 scripts/validate_skill_pack.py（格式/相对引用/frontmatter 100%）
7. 生成目录只读:检测到本地手改时不得静默覆盖（编译器强制三选一）
8. 关键任务覆盖有可追溯去向；实际输出评测与来源核查分别记录。存在重要缺口只能交付明确标注范围的草稿，不能宣称完整通过

与 nuwa-skill / darwin-skill 的生态定位

• nuwa-skill: 蒸馏人 (思维方式 / 表达 DNA)
• cangjie-skill (本 skill): 蒸馏书 (方法论 / 框架 / 原则)
• darwin-skill: 进化任意 skill

三者咬合: 本 skill 输出的评测用例遵循 darwin-skill 格式,以便产出的 skill 可直接接入 darwin 做自动进化。

调用惯例

• 永远先试点 1 本 — 除非用户明确说"批量"
• 阶段之间主动汇报进度 — 不要静默跑完再 dump 结果
• 不凭记忆拆书 — 没文本就停下来问
• 保留审计轨迹 — candidates/ 和 rejected/ 都要留
• 随时可续跑 — 每完成一个阶段就更新 PIPELINE_STATE.md,中断后从状态文件恢复
• 输出策略持久化 — update/repair 默认沿用原输出模式,不因新增材料静默改变产物形态