Упаковка для вашего агента

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

Что вы получаете

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

Пакет самодостаточен и пригоден для передачи, и он никогда не содержит исходный код. Он поставляет карту, а не территорию.

Две аудитории, один пакет. references/ — это handbook для человека, он объясняет. references/agent/ указывает местоположение: он одним grep отвечает на вопрос «где определён sendPayment», чего никакая проза не делает. Это не два рендеринга одного текста, и агентская сторона больше не копирует прозаическую; там, где агенту нужно объяснение, страница этапа на него ссылается. Пока --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.
---

Тело — это нумерованный протокол:

1. Прочитать references/overview.md, чтобы понять форму системы.
2. Маршрутизироваться через references/index.md — индекс этапов сопоставляет каждой подсистеме её файлы.
3. Открывать только релевантные страницы references/stages/<id>.md.
4. Проверить references/registers.md на сквозное состояние — бесценно для изменений с широким разлётом.
5. (с --agent-dir) Вместо догадок искать через grep в таблицах фактов: symbols.tsv превращает имя в path:startLine-endLine, calls.tsv — в список вызывающих, включая тех, кто находится в других пакетах: они приходят строками boundary:<specifier>. references/agent/index.md перечисляет все рецепты.
6. Выполнить read_file реального исходника по каждому процитированному пути, прежде чем предлагать или вносить изменения.

А первая строка тела говорит самое важное:

Этот handbook — индекс местоположений для кодовой базы, а не описание кода.

Обнаружение дрейфа

{
  "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

Цикл исправлений

Когда утверждение handbook противоречит реальному исходнику, агент дописывает одну строку в corrections.jsonl в корне скилла:

{
  "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

Агент подхватывает скилл по описанию во фронтматтере.

Любой агент с файловой системой

Укажите ему каталог и попросите сначала прочитать SKILL.md. Протокол внутри самоописателен и не зависит от конкретной среды выполнения.

Планировщик

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

--handbook принимает каталог references/, который монтируется только для чтения в __handbook__/ внутри песочницы планировщика.

Отказы, которые обеспечивает сборка

• --out не должен быть каталогом handbook или его предком. Сборка начинается с очистки --out; иначе она удалила бы то самое, что упаковывается, а затем тихо произвела бы пустой скилл.
• Индекс для агента и его таблицы фактов поставляются комплектом или не поставляются вовсе. SKILL.md никогда не должен маршрутизировать к файлу, которого нет, поэтому references/agent/, в котором не хватает index.md, symbols.tsv, files.tsv или calls.tsv, отвергается, а не поставляется недособранным.
• Страница регистров существует всегда, даже для handbook без единого регистра, потому что стабильная раскладка справочных материалов — часть контракта.

Поддержание свежести

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

Resync инкрементален, а skill + validate бесплатны. Вся эта последовательность достаточно дешева, чтобы выполнять её по расписанию.