Für Ihren Agenten paketieren

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

Beide sind deterministisch. Kein LLM.

Bauen

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

Was Sie bekommen

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

Das Paket ist in sich geschlossen und teilbar, und es bettet niemals Quellcode ein. Es liefert die Landkarte, nicht das Gelände.

Zwei Zielgruppen, ein Paket. references/ ist das Handbuch für Menschen — es erklärt. references/agent/ verortet: Es beantwortet mit einem einzigen grep, wo sendPayment definiert ist, was keine Menge Prosa schafft. Es sind nicht zwei Darstellungen desselben Textes, und die Agentenseite kopiert die Prosaseite nicht mehr; wo ein Agent die Erklärung braucht, verlinkt die Etappenseite sie. Bevor es --agent-dir als Auslieferungsweg gab, wurde der ganze Index erzeugt und dann nie ausgeliefert — jetzt geht er durch den primären Kanal des Produkts.

Der SKILL.md-Vertrag

---
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.
---

Der Textkörper ist ein nummeriertes Protokoll:

1. Lesen Sie references/overview.md für die Gestalt des Systems.
2. Routen Sie über references/index.md — der Etappenindex bildet jedes Subsystem auf seine Dateien ab.
3. Öffnen Sie nur die relevanten references/stages/<id>.md-Seiten.
4. Prüfen Sie references/registers.md auf Querschnitts-Zustand — unbezahlbar bei Fan-out-Änderungen.
5. (mit --agent-dir) Greppen Sie die Faktentabellen, statt zu raten: symbols.tsv macht aus einem Namen path:startLine-endLine, calls.tsv macht daraus seine Aufrufer — auch die in anderen Paketen, die als boundary:<specifier>-Zeilen erscheinen. references/agent/index.md listet jedes Rezept auf.
6. Lesen Sie mit read_file die tatsächliche Quelle an jedem zitierten Pfad, bevor Sie Änderungen vorschlagen oder vornehmen.

Und seine erste Zeile sagt das Wichtigste:

Dieses Handbook ist ein Ortsindex für die Codebasis, keine Codebeschreibung.

Drift-Erkennung

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

hasht die lebende Quelle erneut und warnt bei jeder Datei, deren Inhalt sich bewegt hat. Exit-Code 2 bei Fehlschlag, damit fällt das direkt in die CI:

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

Die Korrekturschleife

Wenn eine Behauptung des Handbook der echten Quelle widerspricht, hängt der Agent eine Zeile an corrections.jsonl in der Skill-Wurzel an:

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

Nur file ist erforderlich. Die Datei liegt in der Wurzel, nie unter references/, weil Planer diesen Baum schreibgeschützt einhängen.

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

Die genannten Dateien kommen in die Refresh-Menge, selbst wenn sich ihre Bytes nie geändert haben — eine Behauptung, der die Quelle widerspricht, ist Grund genug, diese Datei neu zu beschreiben. Die verbrauchte Datei wird anschließend mit Zeitstempel archiviert, sodass dieselbe Korrektur nicht zweimal angewendet werden kann.

Ein Rebuild bewahrt ausstehende Korrekturen über das Aufräumen hinweg.

Einbindung in einen Agenten

Claude Code

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

Der Agent findet den Skill über die Beschreibung im Frontmatter.

Jeder Agent mit einem Dateisystem

Zeigen Sie ihn auf das Verzeichnis und weisen Sie ihn an, zuerst SKILL.md zu lesen. Das Protokoll darin ist selbstbeschreibend und hängt an keiner bestimmten Laufzeitumgebung.

Der Planer

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

--handbook nimmt das Verzeichnis references/ entgegen, das schreibgeschützt unter __handbook__/ in der Sandbox des Planers eingehängt wird.

Verweigerungen, die der Build erzwingt

• --out darf nicht das Handbook-Verzeichnis sein, und auch kein Vorfahre davon. Der Build beginnt damit, --out zu leeren; das würde genau das löschen, was paketiert werden soll, und dann stillschweigend einen leeren Skill erzeugen.
• Der Agenten-Index und seine Faktentabellen werden als Satz ausgeliefert oder gar nicht. SKILL.md darf niemals zu einer Datei routen, die nicht da ist — ein references/agent/, dem index.md, symbols.tsv, files.tsv oder calls.tsv fehlt, wird deshalb abgelehnt statt halb fertig ausgeliefert.
• Die Register-Seite existiert immer, selbst für ein Handbook mit null Registern, weil ein stabiles Referenzlayout Teil des Vertrags ist.

Frisch halten

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 ist inkrementell, und skill + validate sind kostenlos. Diese gesamte Sequenz ist billig genug, um sie nach Zeitplan laufen zu lassen.