Documentation Inversion
Replace rotting human wikis with CLAUDE.md, navigation skills, and plugins so agents load current, machine-readable docs from the repo.
Overview
Documentation inversion is a journey-wide agent skill that keeps documentation current by structuring CLAUDE.md, skills, and plugins for agents to navigate code—not separate human wikis.
Install
npx skills add https://github.com/juliusbrussee/cavekit --skill documentation-inversionWhat is this skill?
- Inverts code→wiki-for-humans into code→CLAUDE.md→skills-for-agents
- Assigns each module a machine-readable CLAUDE.md with explicit entry points
- Uses navigation skills so agents explore libraries programmatically, not by browsing prose
- Packages capabilities as plugins for on-demand skill loading
- Targets hierarchical, cross-referenced structure over linear human reading
Adoption & trust: 16 installs on skills.sh; 1k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your wiki and README narrative rot because they sit outside the codebase while agents need hierarchical, up-to-date entry points inside the repo.
Who is it for?
Solo builders running agents daily on a growing monorepo or multi-module app who want docs that agents can follow programmatically.
Skip if: Teams that only need a one-page marketing site or PDF handbooks with no agent-driven development workflow.
When should I use this skill?
Use when triggers mention documentation inversion, skills as docs, living documentation, docs for agents, machine-readable docs, or agent-first documentation.
What do I get? / Deliverables
You get agent-consumable documentation—module CLAUDE.md files, navigation skills, and packaged plugins—so each session loads current guidance without manual wiki upkeep.
- Per-module CLAUDE.md structure
- Navigation skills for library exploration
- Plugin-packaged skills for on-demand doc loading
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Sketch how future modules will expose CLAUDE.md entry points before the codebase grows unwieldy.
Replace a stale wiki with per-module CLAUDE.md and cross-links agents can traverse.
Package exploration and domain skills as plugins for on-demand loading in the agent.
Point review agents at inverted docs so they verify behavior against in-repo guidance, not an outdated Notion page.
Onboard an agent to a legacy folder using navigation skills instead of re-explaining architecture each session.
How it compares
Use instead of Confluence-style wikis when your primary reader is the coding agent, not a human browsing paragraphs.
Common Questions / FAQ
Who is documentation inversion for?
Solo and indie developers who rely on coding agents to explore large codebases and want documentation that stays synchronized because it is structured for machine navigation in-repo.
When should I use documentation inversion?
In Build docs when scaffolding CLAUDE.md and skills; in Build agent-tooling when packaging plugins; in Ship review when agents need accurate module maps; in Operate iterate when onboarding agents to legacy areas—whenever you want living, agent-first documentation.
Is documentation inversion safe to install?
It describes documentation structure and skill packaging; confirm repo access and plugin sources via the Security Audits panel on this Prism page before install.
SKILL.md
READMESKILL.md - Documentation Inversion
# Documentation Inversion Traditional documentation drifts out of sync because it lives separately from the code. Documentation inversion places guidance directly in the codebase, structured for agent consumption, so that AI can explore the source and find current information on demand. ## Core Principle > **Structure documentation for programmatic navigation -- hierarchical, cross-referenced, with > explicit entry points -- so that AI agents can find what they need without human guidance.** Traditional documentation assumes a human reader who will browse, search, and interpret context. Agent-first documentation assumes a machine reader that needs: explicit entry points, structured hierarchies, cross-references it can follow programmatically, and guidance on what to explore next. --- ## The Problem: Traditional Documentation Rots ### Traditional Flow ``` Developer ships a feature → Writes a wiki article explaining it ↓ Weeks or months elapse ↓ Another developer refactors the feature ↓ The wiki article is never revised ↓ A third developer (or an agent) follows the stale article ↓ Incorrect assumptions, wasted effort, subtle bugs ``` **Why it rots:** - Documentation is a second-class artifact -- the incentive is to ship code, not update docs - The audience (humans) may not notice staleness until they hit a problem - There is no automated validation that docs match code - Docs live in a separate system (wiki, Notion) disconnected from the codebase - Nobody owns documentation maintenance as a primary responsibility ### The Cost of Rot - New team members learn wrong patterns from stale docs - AI agents given stale docs produce code based on outdated assumptions - Time spent debugging issues caused by following outdated guidance - Tribal knowledge accumulates in chat, not in any durable format --- ## The Solution: Inverted Documentation Flow ### Inverted Flow ``` Developer modifies a module → Updates the co-located CLAUDE.md in the same PR ↓ Navigation skill describes HOW to explore, not WHAT exists ↓ Plugin bundles skills so agents can load them on demand ↓ Agent enters the module → loads skill → reads live source code ↓ Guidance stays accurate because the source itself is the authority ``` **Why it stays current:** - CLAUDE.md files live *in the codebase*, next to the code they describe - They are loaded automatically by AI agents when entering a directory - Skills teach agents *how to explore*, not *what the code currently does* -- so they stay accurate even as implementation details change - The agent reads current source code, guided by the skill -- the sourc