Living documentation: a Claude Skill that updates itself
We've all seen this: a new developer joins the project, opens the documentation for the most critical component in the system, and discovers it is 18 months out of date.
On a recent engagement, a strategic business component evolved every sprint. The documentation never kept up. The problem was never the team's willingness, it was the cost of updating it by hand: nobody had time to redo it after every change, and redoing it at the end of the sprint always arrived too late, once the context had already been forgotten.
Building a living documentation skill
I built a Claude living documentation Skill: documentation generated and
refreshed automatically from the actual code. To build it, I used
Anthropic's skill-creator, a skill dedicated to creating other skills.
The approach took four steps.
1. Define the need
On every significant change to the component, regenerate documentation that describes the business rules, the flows, the API contracts, and the invariants, in plain language. The goal wasn't to document the code line by line, but to capture the business intent that the code alone doesn't always make visible.
2. Run skill-creator
By describing the workflow (what, when to trigger, what output is expected),
skill-creator guides the generation of the full structure: a SKILL.md
file with instructions and triggers, a scripts folder for code extraction, a
references folder for the team's documentation standards.
3. Refine the SKILL.md
This is where the business knowledge gets encoded: the domain vocabulary (DDD ubiquitous language), the rules that must always be documented, the expected format (diagrams, decision tables, examples). This step took several iterations: the first versions produced documentation that was technically correct but hard to read for business analysts, who were actually the primary intended audience.
A simplified excerpt of the resulting SKILL.md looks like this:
---
name: living-documentation
description: Regenerates a component's business documentation from the actual code
---
## When to trigger
On explicit request: "update the living documentation for <component>"
## Steps
1. Read the component's source code and its recent history (git log)
2. Identify business rules, invariants, and API contracts
3. Compare against the existing documentation in docs/<component>.md
4. Propose sections to add, change, or remove
5. Never document in technical jargon: the audience is the business analyst
4. Use it day to day
After every significant change, a simple prompt, "update the living documentation for component X", is enough. Claude re-reads the code, detects gaps with the existing documentation, and proposes an update using this skill. The team reviews, approves, commits. The marginal cost of an update went from several hours to a few minutes of review.
Before and after the skill
| Manual documentation | Living documentation skill | |
|---|---|---|
| Trigger | A conscious decision to "make the time" | A prompt after every significant change |
| Cost per update | Several hours, often postponed | A few minutes of review |
| Detecting code/doc drift | None, short of a full manual re-read | Automatic, on every regeneration |
| Actual intended audience | Often developers, by default | Business analyst, explicitly constrained in the SKILL.md |
That last row is the one that took the most iterations: nothing in a skill guarantees by default that the output targets the right audience, it remains an instruction that must be stated as explicitly as the rest of the workflow.
What this changes
The result: documentation aligned with the code, faster onboarding, and business analysts who finally understand what the component actually does, without having to interrupt a developer to get it explained out loud every time.
An unexpected side effect: simply regenerating the documentation sometimes surfaces inconsistencies in the code itself, cases where actual behavior had drifted from intended behavior without anyone noticing. Living documentation isn't just a communication tool, it becomes a tool for detecting silent debt.
The lesson: living documentation is no longer a burden. With skills, it becomes a concrete, reproducible workflow, within reach of any team. Whether you're a junior developer or a seasoned architect, pick a critical component and try it: the return on investment shows up as early as the first sprint.