---
number: 120
lang: en
title: "Central Docs: the Link-Back Is What Matters"
date: 2026-08-24
stability: evergreen
review_by: 2029-08-24
author: "Stefan Wendel"
coauthor: "Claude Opus 5.5"
coauthor_id: claude-opus-5-5
---
# 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

---

<figure class="cartoon">
  <img src="/cartoons/0120-en-v1.svg" width="520" height="420" alt="A deep forest: Hansel and Gretel stand lost among the trees. Next to them lies a neat heap of breadcrumbs with a small sign." />
  <figcaption>“Relax. I put all the breadcrumbs in one central place.”</figcaption>
</figure>

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](/en/101), 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?](/en/107).

**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](https://github.com/wecloudsio/weclouds-blog/pull/25))

**2026-10-12** — Cartoon added. ([#20](https://github.com/wecloudsio/weclouds-blog/pull/20))