Convierte un handbook renderizado en un paquete SKILL con detección de deriva, y conéctalo a un agente de código.

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

Ambos son deterministas. Sin LLM.

Constrúyelo

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

Flag	Por qué te interesa
`--work` + `--source`	Genera `coverage.json` con un hash de contenido por archivo — la señal de deriva
`--agent-dir`	Incluye el índice para agentes y sus tablas de hechos, y le da al protocolo de enrutamiento sus recetas de grep
`--project`	El nombre humano usado en la prosa. Por defecto toma el valor de `--name`
`--lang zh`	Cuerpo en chino. El frontmatter permanece en inglés — ver más abajo

Qué obtienes

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

El paquete es autocontenido y compartible, y nunca incrusta código fuente. Entrega el mapa, no el territorio.

Dos públicos, un paquete. references/ es el handbook humano — explica. references/agent/ ubica: responde a "dónde está definido sendPayment" con un solo grep, cosa que ninguna cantidad de prosa consigue. No son dos renderizados del mismo texto, y el lado del agente ya no copia el lado de la prosa; donde un agente necesita la explicación, la página de etapa enlaza a ella. Antes de que --agent-dir existiera como vía de entrega, el índice entero se generaba y luego no se entregaba nunca — ahora sale por el canal principal del producto.

El contrato de 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.
---

El frontmatter permanece en inglés incluso con --lang zh

Los runtimes de agentes seleccionan las skills comparando contra el texto de la descripción, y el contrato validado "Use when … / Do not use …" forma parte de esa superficie de enrutamiento. Traducirlo rompería la selección de forma silenciosa. El cuerpo se traduce; la superficie de enrutamiento, no.

El cuerpo es un protocolo numerado:

Lee references/overview.md para conocer la forma del sistema.
Enruta a través de references/index.md — el índice de etapas asigna cada subsistema a sus archivos.
Abre solo las páginas references/stages/<id>.md relevantes.
Consulta references/registers.md para el estado transversal — inestimable para cambios en abanico.
(con --agent-dir) Haz grep de las tablas de hechos en vez de adivinar: symbols.tsv convierte un nombre en path:startLine-endLine, y calls.tsv lo convierte en quienes lo llaman — incluidos los de otros paquetes, que aparecen como filas boundary:<specifier>. references/agent/index.md lista todas las recetas.
Aplica read_file al código fuente real en cada ruta citada antes de proponer o hacer cambios.

Y su primera línea dice lo que más importa:

Este handbook es un índice de ubicaciones del código base, no una descripción del código.

Detección de deriva

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

vuelve a calcular los hashes del código fuente vivo y avisa por cada archivo cuyo contenido cambió. Código de salida 2 en caso de fallo, así que esto encaja directamente en CI:

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

El ciclo de correcciones

Cuando una afirmación del handbook contradice el código fuente real, el agente añade una línea a corrections.jsonl en la raíz de la 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"
}

Solo file es obligatorio. Vive en la raíz, nunca bajo references/, porque los planificadores montan ese árbol en modo de solo lectura.

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

Los archivos nombrados se suman al conjunto de refresco aunque sus bytes nunca hayan cambiado — una afirmación que el código fuente contradice es razón suficiente para volver a describir ese archivo. El archivo consumido se archiva después con una marca de tiempo, de modo que la misma corrección no pueda aplicarse dos veces.

Una reconstrucción preserva las correcciones pendientes a través de la limpieza.

Conectarlo a un agente

Claude Code

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

El agente la detecta a partir de la descripción de su frontmatter.

Cualquier agente con sistema de archivos

Apúntalo al directorio y dile que lea primero SKILL.md. El protocolo interno es autodescriptivo y no depende de ningún runtime en particular.

El planificador

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

--handbook recibe el directorio references/, que se monta en modo de solo lectura en __handbook__/ dentro del sandbox del planificador.

Rechazos que la construcción impone

--out no debe ser el directorio del handbook, ni un ancestro suyo. La construcción comienza vaciando --out; eso borraría justo lo que se está empaquetando y luego produciría en silencio una skill vacía.
El índice para agentes y sus tablas de hechos se incluyen como conjunto o no se incluyen. SKILL.md nunca debe enrutar hacia un archivo que no existe, así que un references/agent/ al que le falte alguno de index.md, symbols.tsv, files.tsv o calls.tsv se rechaza en lugar de entregarse a medio construir.
La página de registros siempre existe, incluso para un handbook con cero registros, porque una estructura de referencia estable es parte del contrato.

Mantenerlo al día

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

El resync es incremental, y skill + validate son gratuitos. Toda esta secuencia es lo bastante barata como para ejecutarse de forma programada.

Empaquetado para tu agente