Run a project's documentation as a living system — not a write-once artifact that rots.
Living Docs is an AI agent skill for documentation-as-code that keeps a codebase's docs in sync with its code. It works with Claude Code, Cursor, GitHub Copilot, OpenCode, Codex, and Pi — any agent that loads markdown "skills" / instruction files. It is stack-agnostic: it governs how docs are organized and maintained (Architecture Decision Records, Behavior Decision Records, PRDs, a constitution, a glossary, living Mermaid diagrams), never what technology a project uses.
The whole discipline collapses to one spine:
Every piece of knowledge has exactly one home, that home is indexed, and nothing structural ships without its doc.
Everything else — the constitution, ADRs, BDRs, PRDs, issues, research notes, architecture diagrams, and the semantic context index — hangs off that spine.
Most documentation rots because there is no contract keeping it honest. Living Docs adds five governance invariants that an agent (or a human) can re-derive every action from:
- Docs-first. Author the body in the repo (
docs/…) before publishing to any tracker or wiki. The repo file is the source of truth; the external copy is a mirror. - One home per fact. Each concept, decision, or requirement lives in exactly one file. Cross-reference instead of copying — duplicated prose is drift waiting to happen.
- Indexed or it doesn't exist. Every doc is reachable from an
index.md. No orphan files. - Supersede, never rewrite history. Decisions and requirements are append-only. When something changes, mark the old record superseded and write a new one — never silently edit the past.
- No structural change without its doc. New module, moved files, schema change, new data flow → update the relevant doc and its diagram in the same change. No "I'll document it later."
These invariants are carried in YAML frontmatter as a fact contract and wired
to a deterministic checker (skills/living-docs/scripts/lint-docs.sh). The pitch is not novelty —
arc42 + ADR + C4 + docs-as-code is a well-trodden stack — it is the explicit,
agent-enforceable packaging of it. See Provenance.
Every change follows one chain, from the foundational source of truth down to code:
flowchart LR
C[constitution] --> P[PRD]
P --> A[ADR]
P --> B[BDR]
A --> I[issues]
B --> I
I --> K[code]
| Artifact | Role |
|---|---|
| constitution | Foundational source of truth: what the product is, core data model, non-negotiables. |
| PRD | What the system must do and why — feature/product requirement spec. |
| ADR | How the system is structured — architectural/implementation decision and rationale. |
| BDR | What the system must observably do — inputs, outputs, side effects, Given/When/Then scenarios. |
| issues | Execution slices — discrete units of work that trace back to ADRs/BDRs. |
| code | Implementation — every behavior, structure, and interface specified above, realized. |
This repo bundles the Living Docs skill together with its two composition dependencies and the prior-art research that backs its honesty claims:
| Path | What it is |
|---|---|
skills/living-docs/ |
The skill: the five invariants, the doc trail, per-doc-type conventions (rules/) and starter templates (templates/). |
skills/okf-knowledge-format/ |
The format standard the docs use — Open Knowledge Format (OKF): markdown + YAML frontmatter, required type, reserved index.md/log.md, bundle-relative links. The OKF spec is vendored verbatim from Google Cloud Platform. |
skills/research-artifacts/ |
The research-note format and source discipline that feeds ADRs/PRDs (the docs/research/ half of the trail). |
references/prior-art-landscape.md |
The sourced prior-art analysis — every part of Living Docs (the doc trail, the OKF format, the diagrams, the governance invariants) mapped to its established originator, so every "credit, not invention" claim has a checkable citation. |
skills/living-docs/scripts/lint-docs.sh |
The deterministic checker for the mechanical invariants — frontmatter/type, indexing + reachability, link resolution, supersede integrity. Ships inside the skill; delegates parsing to mature tools (lychee for links, yq v4 for frontmatter, jq for JSON) rather than hand-rolling it. A constraint without an instrument is a vibe; this is the instrument. Wire it into CI. No host tools? make lint-docker bundles lychee+yq+jq in an image and lints with zero local installs. |
examples/linkly/ |
A worked, lint-clean end-to-end corpus (constitution → PRD → ADR + BDR → issue) for a fictional URL shortener — the discipline shown, not just described, and the fixture CI runs lint-docs against. |
Each skill is self-describing — open its SKILL.md for the full operational
detail. Living Docs and OKF compose but do not overlap: Living Docs governs
which docs exist and the no-drift discipline; OKF governs how a knowledge
bundle's markdown and frontmatter are shaped.
The skill is plain markdown instruction files — nothing to compile or install to use it. The one piece with dependencies is the optional lint-docs checker (it uses lychee, yq v4 and jq to parse links and YAML correctly instead of approximately) — and even that needs nothing on your host if you run it via Docker: make lint-docker.
Installing Living Docs always means the same thing: put the three skills/
directories (or a generated rule file) where your tool discovers instructions,
then start a fresh session. A cross-platform installer and a Makefile do this
for every supported tool. Clone once:
git clone https://github.com/ejklock/living-docs-skill.git
cd living-docs-skill./install.sh # Claude Code, global (~/.claude/skills) — the default
./install.sh cursor # Cursor rule in the current project
./install.sh copilot # GitHub Copilot instruction in the current project
./install.sh opencode # OpenCode (~/.config/opencode/skills)
./install.sh codex # Codex (~/.codex/skills)
./install.sh pi # Pi (~/.pi/agent/skills + AGENTS.md)
./install.sh all # every supported harness at onceUseful flags: --project (install into the current repo instead of the global
user dir), --dir <path> (custom skills directory), --uninstall, --dry-run,
--help. The same targets are available via make:
make help # list every target
make install # Claude Code, global
make install-cursor # or install-copilot / install-opencode / install-codex / install-pi / install-all
make project-claude # install into the current project
make uninstall-all # remove from every harness
make check # full gate: version sync · lint the example · hostile parser
# fixtures · bash -n all scripts · dry-run every harness
make lint-docs # run the checker against examples/linkly/docs
make test-fixtures # run the hostile/negative fixtures guarding the parsers
make lint-docker # lint via Docker — bundles lychee+yq+jq, no host tools needed| Tool | Mechanism | Default location (global · --project) |
|---|---|---|
| Claude Code | native SKILL.md skills |
~/.claude/skills · .claude/skills |
| OpenCode | native SKILL.md skills (also reads .claude/skills) |
~/.config/opencode/skills · .opencode/skills |
| Codex | native SKILL.md skills |
~/.codex/skills · .codex/skills |
| Cursor | project rule | .cursor/rules/living-docs.mdc (project-scoped) |
| GitHub Copilot | path-scoped instruction | .github/instructions/living-docs.instructions.md (project-scoped) |
| Pi | skills dir + AGENTS.md pointer |
~/.pi/agent/skills · .pi/skills |
Claude Code, OpenCode, and Codex share the same model: they
auto-discover folders of SKILL.md files from their skills directory, so the
installer just copies the three skills there (OpenCode additionally reads
.claude/skills, so a Claude install already covers it). For Cursor and
Copilot the installer generates the rule/instruction file with the right
frontmatter header (globs / applyTo scoped to docs/** and **/*.md) from
living-docs/SKILL.md. Pi has no native skills directory — after the skills
are copied, reference them once from your AGENTS.md:
## Living Docs
Follow the documentation discipline in skills/living-docs/SKILL.md,
skills/okf-knowledge-format/SKILL.md, and skills/research-artifacts/SKILL.md.Then restart the session so the tool picks up the skills.
Copy skills/living-docs/, skills/okf-knowledge-format/, and
skills/research-artifacts/ into wherever that tool loads instructions from, or
just read the SKILL.md files — they are plain markdown meant to be read by
humans and agents alike.
Living Docs composes with but does not bundle Matt Pocock's skills. His
grill-me (design interview before a load-bearing decision) pairs directly with
Living Docs, and his to-prd / to-issues are kindred to the PRD/issues
workflow here. They are best installed straight from the source so they stay
canonical and up to date — his repo is MIT-licensed, so cloning and using it is
permitted (keep his LICENSE notice if you copy files):
./install.sh pocock # git clones his repo (default ~/.matt-pocock-skills)
# or by hand:
git clone https://github.com/mattpocock/skills.git
# his repo ships a `setup-matt-pocock-skills` skill that wires them upSee ATTRIBUTION.md for how Living Docs relates to his work.
- Standing up documentation for a project (
docs/structure, the docs index, ADR/issue/BDR/constitution directories). - Writing or editing an ADR, PRD, BDR, constitution, or
issue → load the matching
rules/+templates/file. - Recording research → the
research-artifactsskill. - Drawing or updating an architecture / data-flow / sequence diagram (living Mermaid, in-repo text that must match the code).
- Defining a term or acronym → the glossary, one home per term.
- A doc grew too large or mixes concerns → split into a semantic index.
- Enforcing the no-drift maintenance rule after any structural change.
Living Docs is deliberately small and composes with the rest of your toolchain
rather than absorbing it: design grilling before a load-bearing ADR, an
architecture-improvement pass that reads the context index and ADRs, a
deep-research step that gathers the evidence research-artifacts then formats,
and an implementation-review step that checks code honors the ADRs/BDRs. See the
"Composition with other skills" section in
skills/living-docs/SKILL.md for the full map.
The design-grilling step composes with
grill-meby Matt Pocock (github.com/mattpocock/skills) — referenced, not bundled here. SeeATTRIBUTION.md.
This work instrumentalizes established practices; it does not invent them. "Living documentation" is Cyrille Martraire's named methodology; ADRs are Michael Nygard's (supersede-don't-delete is the adr-tools convention); BDRs wrap Specification by Example / BDD (Adzic; North); the file format is Google Cloud Platform's OKF, vendored verbatim; the architecture diagrams are Mermaid (Knut Sveidqvist & the mermaid-js community). None of the doc types are invented here. What is original is modest and concrete: the composition + the governance invariants carried in frontmatter as a fact contract and enforced by a checker — the enforcement, not the invention.
Full credits and the per-source links are in
ATTRIBUTION.md and
references/prior-art-landscape.md.
Issues and PRs welcome — the project dogfoods its own rules. See
CONTRIBUTING.md for the repo layout, the invariants it holds
itself to, how to refresh the vendored OKF spec, and how to validate a change —
make check runs the full gate: version sync, the docs linter, the hostile parser
fixtures, bash -n on every script, and a dry-run of every installer.
What is an "agent skill"?
A skill is a folder of markdown instructions (a SKILL.md plus optional rules/
and templates/) that an AI coding agent loads and follows. Living Docs is a
skill that teaches the agent how to keep documentation in sync with code.
Which tools does Living Docs work with?
Claude Code, OpenCode, and Codex (native SKILL.md skills), Cursor
(.cursor/rules), GitHub Copilot (.github/instructions), and Pi (AGENTS.md).
Because the skill is plain markdown, any agent that reads instruction files can
use it. See Installation.
How is this different from a documentation generator or a wiki?
Living Docs is not a generator and not a hosting tool. It is a discipline — five
no-drift governance invariants plus a doc trail (constitution → PRD → ADR + BDR →
issues → code). The agent follows the discipline as it works; a deterministic
checker (lint-docs) verifies the mechanical half when you wire it into CI or
the agent's loop. Prompt-level guidance plus a machine check — not one pretending
to be the other. Your docs live in the repo, in Git, next to the code.
What is an ADR / BDR / PRD?
An ADR (Architecture Decision Record) captures how the system is structured
and why. A BDR (Behavior Decision Record) captures what the system must
observably do (Given/When/Then). A PRD captures the product/feature
requirements. Each has a convention file and a starter template under
skills/living-docs/.
What is OKF (Open Knowledge Format)?
A vendor-neutral format from Google Cloud Platform — markdown with YAML
frontmatter, a required type, reserved index.md/log.md, and bundle-relative
links. Living Docs stores every doc as an OKF concept so the corpus stays
portable and agent-parseable. The spec is vendored under
skills/okf-knowledge-format/.
What does the lint-docs checker catch — and not catch?
It is a deterministic checker over a documented input shape, not a general markdown/YAML validator, and its three fragile parsers (link extraction, link resolution, frontmatter reading) are guarded by hostile/negative fixtures (make test-fixtures). One known limit: the structural-graph checks — directory-index membership and index reachability — read only inline links in index.md, so a file indexed solely via a reference-style link ([x][ref]) is not yet detected there and would be reported as a false-positive orphan. Link validity itself is delegated to lychee, which does handle every link form (inline, titled, angle-bracket, and reference-style).
Is it tied to a specific language or framework? No. Living Docs is stack-agnostic — it governs documentation organization and lifecycle, not your tech stack.
Did you invent this?
No, and the repo says so. Living Docs composes established practices (Martraire's
living documentation, Nygard's ADRs, Specification by Example for BDRs, Google's
OKF). Full, sourced credits in ATTRIBUTION.md and
references/prior-art-landscape.md.
MIT © 2026 Evaldo Klock.
Vendored third-party content under reference/ directories remains subject to
its own upstream license — see ATTRIBUTION.md.
Keywords: living documentation · documentation as code · docs-as-code · AI agent skill · Claude Code skill · Cursor rules · GitHub Copilot instructions · OpenCode · Codex · Pi · Architecture Decision Records (ADR) · Behavior Decision Records (BDR) · PRD · project constitution · glossary · Mermaid architecture diagrams · semantic index · Open Knowledge Format (OKF) · knowledge management · technical writing · software architecture · markdown documentation · no-drift docs.