repo-docs-skills: keeping agent-written documentation in sync with the code

The problem Repo-Docs targets: understanding that expires between agent sessions

The README frames the failure mode precisely: code changed quickly, but the reason stayed in chat. Files exist, yet no one can explain the real behavior path. README, source, tests, and agent memory drift apart, and the next agent starts by rediscovering the same context. That is a documentation problem, but not the kind a doc generator solves. A file-tree tour or a generated API dump records what exists, not why a particular path is the one that runs. Repo-Docs is aimed at repositories built through vibe coding, where the code may be real but the project understanding is temporary. The intended reader is a coding agent first and a human second: the artifacts exist so that a later session, or a new contributor, can reconstruct behavior without re-reading the whole repository. The README cites two 2026 open-source studies to size the audience, AIDev reporting 932,791 agent-authored pull requests across 116,211 repositories and a multi-method census of 180 million repositories finding that many agent traces are missed by single-signal detection. Whether or not those numbers match your situation, the design assumption is clear: the reasoning layer is worth storing inside the repository rather than in a chat log.

How the Repo-Docs loop works: one real run, then a conservative sync check

The mechanism is a loop rather than a generator. The README's flowchart starts with either a user question or an agent change to the repository, then runs an understanding sync check. That check fans out into four possible updates: the README and walkthrough, the change-log, the modules, glossary and references pages, and AGENTS.md or CLAUDE.md. All four converge on the same outcome, a reader who can see the current project. The important design choice is what the loop refuses to do. The README calls it intentionally conservative and states that a good update touches the page that would otherwise mislead the next reader, not every page that could be polished. That is a real constraint on scope, and it is the difference between this and a documentation build that rewrites everything on each run. The modes table makes the same distinction concrete. Seed mode is for a new repository with little runtime evidence, and it preserves goals, decisions, planned work and unknowns rather than claiming implementation. Build mode produces the first guide. Sync mode responds to a question or a behavior change that may have made docs stale, and preserves the smallest page that would otherwise mislead. Cleanup removes the generated docs package and stale root-agent pointers. Question refinement handles the case where a question exposes a wrong reader model: the page gets corrected first, then the answer links to it.

What a Repo-Docs package actually contains

The artifact table is the clearest statement of scope. repo-docs/README.md orients the reader and points to the first useful path. walkthroughs/one-real-run.md follows one real behavior from observable entry to output, which is the piece a generated reference cannot produce. code-map.md maps in-scope source directories to responsibilities, important code, tests, and likely change points. modules/ explains durable concepts that the walkthrough names, so the walkthrough does not have to teach terminology inline. references/ holds source evidence and an optional quality review. glossary.md translates repeated project terms into plain meaning. change-log.md records meaningful guide work, verification, and sync anchors. AGENTS.md and CLAUDE.md tell future coding agents when and how to keep the docs current, which is what closes the loop without a human remembering to run anything. The README is explicit about what the package is not: not a file-tree tour, not a generated API dump, not a chat transcript. The evidence pages are the part worth scrutinizing. Storing source proof alongside prose means the documentation can be checked against the code, and the validation script described later operates on exactly those locators.

Installing repo-docs-skills and running it on a repository

The README's primary install path is natural language, not a shell command. You give your coding agent an install request naming the repository and the two skills to make available. The README gives this exact text:

Install the repo-docs skill from this project:
https://github.com/YurunChen/repo-docs-skills

Make both repo-docs and repo-docs-zh available in my agent skill directory.

After that, you ask the agent to run the skill against whatever repository you are working in. The README's example request is short:

Use the repo-docs skill to create docs for this repository.

A shell install is documented as an alternative, described as a GitHub raw-file URL that GitHub serves through its raw content host after redirect:

curl -fsSL https://github.com/YurunChen/repo-docs-skills/raw/main/install.sh | bash

From a source checkout, the script takes flags. The README lists --agent all for installing into all known locations (~/.codex/skills, ~/.claude/skills, ~/.agents/skills) and --target for one explicit skills directory:

./install.sh --agent all
./install.sh --target ~/.agents/skills

A Chinese variant exists under the name repo-docs-zh, and the README shows asking for it directly. There is also a mode for explaining an existing subsystem rather than creating a guide: "Explain how this subsystem works using repo-docs and the current source." The README does not document an uninstall command; cleanup is described as a mode the agent runs when the user asks to remove generated docs.

Validation, the quality bar, and where the documentation stops

Repo-Docs ships a validation script rather than trusting the agent's output. The README gives the invocation with two paths, the generated docs directory and the repository root:

python skills/repo-docs/scripts/validate_repo_docs.py /path/to/repo-docs --repo-root /path/to/repo

Two flags change what gets checked. --lite is for small projects. --seed is for repositories that still need status-labeled plans instead of implementation claims, which pairs with Seed mode. --repo-root is the interesting one: the README says it checks source locators and post-anchor drift. In other words, the validation can catch a reference page pointing at source that has since moved. That is a stronger check than most documentation tooling offers, and it is also the main limitation to understand before adopting. The validator depends on locators being present and well-formed; a package written without them, or with locators the script cannot resolve against your layout, will not get the drift check. The README does not document what the script does when a locator fails, whether it exits non-zero, or how it reports partial results. The quality bar section is truncated in the repository README at the principle "Behavior before inv...", so the remaining principles are not visible from the README alone; the skill contract at skills/repo-docs/SKILL.md is where the full contract lives.

Where Repo-Docs is the wrong tool, and how it differs from a docs generator

Repo-Docs is the wrong choice when the repository's behavior is obvious from the source. A small library with a stable public API does not need a walkthrough of one real run, and generating one adds pages that will drift. It is also the wrong tool if what you actually want is an API reference extracted from signatures and docstrings; the README explicitly positions the package as not a generated API dump. And it is a poor fit where there is no runtime evidence at all and no plan either, because the artifacts lean on a real behavior path or on status-labeled plans. The alternative most readers will already have in place is an architecture decision record or a docs-as-code setup such as MkDocs or Sphinx, where a human writes pages and a build step publishes them. The difference in approach is who maintains the reasoning. ADRs record a decision at a point in time and are updated by hand; a Sphinx tree publishes what a human wrote. Repo-Docs instead gives the coding agent an explicit contract for when to update which page, and pairs that with a validator that checks the pages against current source. The trade-off is that you are handing documentation maintenance to the same agent whose changes created the drift in the first place, which is why the conservative update rule and the sync check matter more here than in a hand-written docs tree.

Maintenance, licence and upgrade cost

The repository is not archived. Its last push was on 2026-07-12, which is roughly two months before this writing, so the project is current but the README does not state a release cadence and no releases were retrieved. The install path is a script fetched from the main branch, which means an unpinned install tracks whatever is on main at the time. That is the upgrade cost to plan for: there is no version number in the install commands, so re-running install.sh is how you move forward, and there is no documented rollback. The README does not document a changelog for the skill itself, only change-log.md as an artifact the skill produces inside your repository. On licensing, the repository metadata does not carry a licence identifier, and the README does not name one either. That matters for a tool that writes files into ~/.codex/skills, ~/.claude/skills and ~/.agents/skills and generates documentation inside your repository. If you need a licence grant before adopting, this page cannot supply it, and neither can the README as written.

Editorial conclusion

Adopt Repo-Docs if your repository is written or heavily modified by coding agents and nobody can reconstruct the behavior path from the source alone. Skip it if your project is small enough that a README and inline comments carry the whole story, or if you need a generated API reference rather than a reasoning layer. Before committing, run python skills/repo-docs/scripts/validate_repo_docs.py against your repo-docs directory with --repo-root to see whether the locators and post-anchor drift checks pass on your layout, and confirm what the install script writes into ~/.codex/skills, ~/.claude/skills and ~/.agents/skills.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. YurunChen/repo-docs-skills on GitHub