Central Docs: the Link-Back Is What Matters
A runbook no repo points to practically doesn’t exist.
2026-08-24 · Stefan Wendel · Claude Opus 5.5
First, the setup: we work with five working repos that hold the code, and one docs repo with specifications, prototypes and runbooks.
The docs repo held nine good runbooks: prod promotion, rollback, credential rotation, incident response. References to them from the five working repos: zero.
We noticed when an agent was asked to promote a version to production. It did it right, but reconstructed the whole procedure from the GitHub workflows. It never saw the runbook that describes exactly that.
This is the point of #0101 Shift Into, and it matters enough to say it again here: docs become part of the code. Docs the code doesn’t point to don’t exist for an agent.
The agent didn’t have the wrong tool. It was missing the pointer. A repo’s CLAUDE.md is the one document an agent is guaranteed to read before it acts. Two lines there are enough: “Operational procedures live in <docs-repo>/runbooks/. Check there before touching prod.”
What else helps:
- A “when do I reach for it” column in the catalogue, phrased as a symptom. At 2 a.m. you know your problem, not the name of its fix.
- “Last verified” on every runbook. Whoever uses it, stamps it.
- The alert links the runbook that fixes it.
Measuring takes a minute: grep for the docs directory in every CLAUDE.md. If it says zero, your docs are invisible.
Alternatively: an agent skill for the runbook
For exactly this kind of procedure there is a second answer: the runbook becomes a skill. A skill tells the agent step by step how to do a recurring task, and the agent loads it on its own as soon as the task fits. “Read up on prod promotion” becomes “run prod promotion”.
The catch is the same: the skill has to live where the agent finds it, in the repo or in its environment. How skill, MCP and API differ is in #0107 MCP, API, or Skill?.
The lesson: Whoever moves docs to a central place adds the link back into every repo in the same commit.
Changelog
2026-10-13 — Added the repo setup, the link to #0101 and the section on skills. (#25)
2026-10-12 — Cartoon added. (#20)