अपने एजेंट के लिए पैकेजिंग

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

दोनों deterministic हैं। कोई 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

यह पैकेज आत्मनिर्भर और साझा करने योग्य है, और इसमें कभी source code नहीं जोड़ा जाता। यह नक्शा भेजता है, इलाक़ा नहीं।

दो श्रोता, एक पैकेज। references/ मानवीय handbook है — वह समझाता है। references/agent/ पता बताता है: वह एक ही grep में जवाब दे देता है कि sendPayment कहाँ परिभाषित है, जो कितना भी गद्य नहीं कर पाता। ये एक ही पाठ के दो रूप नहीं हैं, और agent वाला पक्ष अब गद्य वाले की नक़ल नहीं करता; जहाँ किसी agent को व्याख्या चाहिए, stage पृष्ठ उससे जोड़ देता है। --agent-dir के भेजने का रास्ता बनने से पहले पूरा index बनता तो था, पर कभी पहुँचता नहीं था — अब वह product के प्राथमिक channel से जाता है।

SKILL.md का contract

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

body एक क्रमांकित protocol है:

1. सिस्टम की संरचना के लिए references/overview.md पढ़ें।
2. references/index.md से route करें — stage index हर subsystem को उसकी files से जोड़ता है।
3. केवल प्रासंगिक references/stages/<id>.md पेज खोलें।
4. cross-cutting state के लिए references/registers.md देखें — fan-out बदलावों के लिए अमूल्य।
5. (--agent-dir के साथ) अंदाज़ा लगाने के बजाय fact तालिकाओं को grep करें: symbols.tsv किसी नाम को path:startLine-endLine में बदल देता है, calls.tsv उसे उसके callers में — उन callers सहित जो दूसरे packages में हैं और boundary:<specifier> rows के रूप में आते हैं। हर नुस्ख़ा references/agent/index.md में सूचीबद्ध है।
6. कोई भी बदलाव प्रस्तावित करने या करने से पहले हर उद्धृत path पर वास्तविक source को read_file करें।

और इसकी पहली पंक्ति ही वह बात कहती है जो सबसे अधिक मायने रखती है:

यह handbook कोडबेस के लिए एक location index है, कोड का विवरण नहीं।

Drift की पहचान

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

यह लाइव source को फिर से hash करता है और हर उस फ़ाइल के लिए चेतावनी देता है जिसकी सामग्री बदल चुकी है। विफलता पर exit code 2, इसलिए यह सीधे CI में बैठ जाता है:

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

Corrections का चक्र

जब handbook का कोई दावा वास्तविक source का खंडन करता है, तो एजेंट skill root पर 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 अनिवार्य है। यह root पर रहती है, कभी references/ के नीचे नहीं, क्योंकि planner उस tree को read-only mount करते हैं।

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

नामित files refresh सेट में शामिल हो जाती हैं, भले ही उनके bytes कभी न बदले हों — जिस दावे का source खंडन करता है, वही उस फ़ाइल का फिर से वर्णन करने के लिए पर्याप्त कारण है। उपयोग हो चुकी फ़ाइल को फिर timestamp के साथ archive कर दिया जाता है, ताकि एक ही correction दो बार लागू न हो सके।

rebuild, clean के बावजूद लंबित corrections को सुरक्षित रखता है।

इसे एजेंट से जोड़ना

Claude Code

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

एजेंट इसे इसके frontmatter description के आधार पर चुन लेता है।

फ़ाइलसिस्टम वाला कोई भी एजेंट

उसे इस directory की ओर इंगित करें और पहले SKILL.md पढ़ने को कहें। अंदर का protocol स्वयं-व्याख्यायी है और किसी विशेष runtime पर निर्भर नहीं करता।

Planner

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

--handbook को references/ directory दी जाती है, जो planner के sandbox के अंदर __handbook__/ पर read-only mount होती है।

Build जिन बातों से इनकार करता है

• --out handbook directory या उसका कोई ancestor नहीं होना चाहिए। build की शुरुआत --out को मिटाने से होती है; ऐसा होने पर वही चीज़ मिट जाती जो package की जा रही है, और फिर चुपचाप एक खाली skill बन जाती।
• Agent index और उसकी fact तालिकाएँ या तो एक सेट के रूप में जाती हैं या बिल्कुल नहीं। SKILL.md को कभी ऐसी फ़ाइल की ओर route नहीं करना चाहिए जो मौजूद ही न हो, इसलिए ऐसा references/agent/ जिसमें index.md, symbols.tsv, files.tsv या calls.tsv में से कोई भी न हो, अधबना भेजे जाने के बजाय अस्वीकार कर दिया जाता है।
• Register पेज हमेशा मौजूद रहता है, शून्य registers वाले handbook के लिए भी, क्योंकि एक स्थिर reference layout contract का हिस्सा है।

इसे ताज़ा रखना

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 incremental है, और skill + validate मुफ़्त हैं। यह पूरा क्रम इतना सस्ता है कि इसे नियमित schedule पर चलाया जा सकता है।