レンダリング済みハンドブックをドリフト検出付きの SKILL パッケージに変換し、コーディングエージェントに組み込みます。

handbook skill --handbook <rendered-dir> --out <skill-dir> --name <slug> [options]
handbook validate --skill <skill-dir> --source <repo>

どちらも決定的です。LLM は使いません。

ビルドする

handbook skill \
  --handbook work/api/handbook \
  --out skills/api \
  --name api \
  --project "Payments API" \
  --work work/api \
  --source ~/code/api \
  --agent-dir work/api/handbook/agent

フラグ	使う理由
`--work` + `--source`	ファイルごとのコンテンツハッシュを持つ `coverage.json` を生成します — ドリフトのシグナルです
`--agent-dir`	エージェントインデックスとその事実テーブルを同梱し、ルーティングプロトコルに grep レシピを与えます
`--project`	本文で使われる人間向けの名前。デフォルトは `--name` です
`--lang zh`	中国語の本文。frontmatter は英語のままです — 後述

得られるもの

skills/api/
  SKILL.md                    the routing guide
  corrections.jsonl           agent-written feedback (created by the agent, never the build)
  references/
    overview.md               the system's shape
    index.md                  every subsystem → its files
    registers.md              cross-stage state
    stages/<id>.md            one page per stage
    agent/index.md            lookup recipes, stage table, registers, coverage
    agent/symbols.tsv         name → path:startLine-endLine
    agent/files.tsv           path → stage, role, purpose
    agent/calls.tsv           call edges (callee located, or boundary:<specifier>)
    agent/stages/<id>.md      second hop per stage
    coverage.json             file → stage + sha256

パッケージは 自己完結していて共有可能 であり、ソースコードを埋め込むことは決してありません。同梱するのは地図であって、土地そのものではありません。

読み手は 2 種類、パッケージは 1 つ。 references/ は人間向けのハンドブックです — 説明します。references/agent/ は位置を示します: 「sendPayment はどこで定義されているか」に grep 1 回で答えます。どれだけ文章を積んでも、これはできません。両者は同じテキストを 2 通りにレンダリングしたものではなく、エージェント側が文章側をコピーすることもなくなりました。エージェントに説明が必要なときは、ステージページがそこへリンクします。 --agent-dir が同梱の経路として存在する前は、インデックス全体が生成されたまま一度も届けられていませんでした — いまはプロダクトの主要な経路を通ります。

SKILL.md の契約

---
name: api-handbook
description: Navigate the Payments API codebase by behavior and source location. Use when
  planning, implementing, debugging, or reviewing Payments API work that is unfamiliar,
  spans multiple files, or may affect cross-cutting state. Do not use for tasks unrelated
  to Payments API or isolated edits where the exact file is already known and no
  cross-cutting impact is plausible.
---

--lang zh を指定しても frontmatter は英語のままです

エージェントランタイムは description テキストとのマッチングでスキルを選択し、検証済みの「Use when … / Do not use …」契約はそのルーティング面の一部です。これを翻訳すると選択が静かに壊れます。本文は翻訳されますが、ルーティング面は翻訳されません。

本文は番号付きのプロトコルです:

references/overview.md を読んでシステムの形を把握する。
references/index.md を通じてルーティングする — ステージインデックスがすべてのサブシステムをそのファイル群に対応付けます。
関係のある references/stages/<id>.md ページだけを開く。
横断的な状態は references/registers.md で確認する — 広範囲に波及する変更では非常に有用です。
(--agent-dir 使用時) 推測せず、事実テーブルを grep する: symbols.tsv は名前を path:startLine-endLine に変え、calls.tsv はそれを呼び出し元に変えます。別のパッケージにある呼び出し元も含まれ、それらは boundary:<specifier> の行として現れます。レシピの一覧は references/agent/index.md にあります。
変更を提案・実施する前に、引用されたすべてのパスの実際のソースを read_file で読む。

そして最初の行に、最も重要なことが書かれています:

このハンドブックはコードベースの ロケーションインデックス であって、コードの説明ではありません。

ドリフト検出

references/coverage.json

{
  "schemaVersion": 1,
  "summary": { "eligibleFiles": 412, "stages": { "stage-1": 37, "stage-2": 54 } },
  "files": [{ "path": "src/upload.py", "stage": "stage-3", "sha256": "9f2c…" }]
}

handbook validate --skill skills/api --source ~/code/api

は、生きているソースを再ハッシュし、内容が変わったすべてのファイルについて警告します。失敗時は 終了コード 2 なので、そのまま CI に入れられます:

- run: handbook validate --skill skills/api --source .
  continue-on-error: true # a warning, not a build break — then schedule a resync

修正ループ

ハンドブックの記述が実際のソースと矛盾する場合、エージェントは スキルルート の corrections.jsonl に 1 行追記します:

{
  "file": "src/engine.py",
  "page": "references/stages/stage-2.md",
  "claim": "spin() is defined in src/main.py",
  "actual": "spin() is defined in src/engine.py",
  "notedAt": "2026-08-08T12:00:00Z"
}

必須なのは file だけです。このファイルはルートに置かれ、決して references/ の下には置かれません。プランナーはそのツリーを読み取り専用でマウントするからです。

handbook resync --case cases/x --work work/api --corrections skills/api/corrections.jsonl

指名されたファイルは、バイト列が一切変わっていなくても リフレッシュ対象に加わります — ソースと矛盾する記述があること自体が、そのファイルを再記述する十分な理由だからです。消費された修正ファイルはタイムスタンプ付きでアーカイブされるため、同じ修正が二度適用されることはありません。

リビルドは、クリーン処理をまたいで未処理の修正を保持します。

エージェントへの組み込み

Claude Code

mkdir -p .claude/skills
cp -R skills/api .claude/skills/api-handbook

エージェントは frontmatter の description によってこれを拾い上げます。

ファイルシステムを持つ任意のエージェント

ディレクトリを指し示し、まず SKILL.md を読むように伝えてください。中のプロトコルは自己記述的で、特定のランタイムには依存しません。

プランナー

handbook plan --source ~/code/api --handbook skills/api/references \
  --request "Retry failed uploads three times" --out plan.md

--handbook には references/ ディレクトリを渡します。これはプランナーのサンドボックス内で __handbook__/ に読み取り専用でマウントされます。

ビルドが強制する拒否

--out はハンドブックディレクトリやその祖先であってはなりません。 ビルドは最初に --out を消去します。それを許すと、パッケージ化しようとしているものそれ自体を削除し、黙って空のスキルを生成してしまいます。
エージェントインデックスとその事実テーブルは、一式で同梱されるか、まったく同梱されないかのどちらかです。 SKILL.md が存在しないファイルへルーティングすることは決してあってはならないので、index.md、symbols.tsv、files.tsv、calls.tsv のいずれかを欠いた references/agent/ は、中途半端に同梱されるのではなく拒否されます。
状態レジスタのページは常に存在します。 レジスタが 1 つもないハンドブックでも同様です。安定した参照レイアウトは契約の一部だからです。

鮮度を保つ

handbook resync --case cases/latest --work work/api    # roll the handbook forward
handbook skill  --handbook work/api/handbook --out skills/api --name api \
                --work work/api --source ~/code/api --agent-dir work/api/handbook/agent
handbook validate --skill skills/api --source ~/code/api

再同期はインクリメンタルで、skill と validate は無料です。この一連の流れは、スケジュール実行できるほど安価です。

エージェント向けのパッケージング