Empacotando para o seu agente

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

Ambos são determinísticos. Sem LLM.

Construa o pacote

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

O que você recebe

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

O pacote é autocontido e compartilhável, e nunca embute código-fonte. Ele entrega o mapa, não o território.

Dois públicos, um pacote. O references/ é o handbook humano — ele explica. O references/agent/ localiza: responde "onde sendPayment está definido" com um único grep, coisa que nenhuma quantidade de prosa faz. Não são duas renderizações do mesmo texto, e o lado do agente não copia mais o lado da prosa; onde um agente precisa da explicação, a página de etapa liga para ela. Antes de --agent-dir existir como rota de entrega, o índice inteiro era gerado e nunca chegava a ser entregue — agora ele passa pelo canal principal do produto.

O contrato do 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.
---

O corpo é um protocolo numerado:

1. Leia references/overview.md para conhecer a forma do sistema.
2. Roteie por references/index.md — o índice de etapas mapeia cada subsistema para seus arquivos.
3. Abra apenas as páginas references/stages/<id>.md relevantes.
4. Consulte references/registers.md para o estado transversal — inestimável em mudanças com fan-out.
5. (com --agent-dir) Faça grep nas tabelas de fatos em vez de adivinhar: o symbols.tsv transforma um nome em path:startLine-endLine, o calls.tsv o transforma em quem o chama — incluindo os de outros pacotes, que aparecem como linhas boundary:<specifier>. O references/agent/index.md lista todas as receitas.
6. Faça read_file do código-fonte real em cada caminho citado antes de propor ou fazer mudanças.

E sua primeira linha diz o que mais importa:

Este handbook é um índice de localização da base de código, não uma descrição do código.

Detecção de deriva

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

recalcula os hashes do código-fonte atual e avisa para cada arquivo cujo conteúdo mudou. Código de saída 2 em caso de falha, então isso se encaixa direto no CI:

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

O loop de correções

Quando uma afirmação do handbook contradiz o código-fonte real, o agente acrescenta uma linha ao corrections.jsonl na raiz da skill:

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

Apenas file é obrigatório. Ele fica na raiz, nunca sob references/, porque os planejadores montam essa árvore como somente leitura.

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

Os arquivos nomeados entram no conjunto de atualização mesmo que seus bytes nunca tenham mudado — uma afirmação que o código-fonte contradiz é motivo suficiente para redescrever aquele arquivo. O arquivo consumido é então arquivado com um timestamp, para que a mesma correção não possa ser aplicada duas vezes.

Uma reconstrução preserva as correções pendentes através da limpeza.

Conectando a um agente

Claude Code

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

O agente a encontra pela descrição do frontmatter.

Qualquer agente com um sistema de arquivos

Aponte-o para o diretório e diga a ele para ler o SKILL.md primeiro. O protocolo lá dentro é autodescritivo e não depende de nenhum runtime específico.

O planejador

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

--handbook recebe o diretório references/, que é montado como somente leitura em __handbook__/ dentro do sandbox do planejador.

Recusas que o build impõe

• --out não pode ser o diretório do handbook, nem um ancestral dele. O build começa apagando --out; isso apagaria justamente o que está sendo empacotado e então produziria silenciosamente uma skill vazia.
• O índice para agentes e suas tabelas de fatos são incluídos como um conjunto ou não são incluídos. O SKILL.md nunca deve rotear para um arquivo que não está lá, então um references/agent/ a que falte qualquer um de index.md, symbols.tsv, files.tsv ou calls.tsv é recusado em vez de entregue pela metade.
• A página de registradores sempre existe, mesmo para um handbook com zero registradores, porque um layout de referência estável faz parte do contrato.

Mantendo o pacote atualizado

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

O resync é incremental, e skill + validate são gratuitos. Essa sequência inteira é barata o suficiente para rodar de forma agendada.