repo-docs-skills documents one real run, not the file tree

Three things it refuses to be

The positioning is stated as a list of exclusions, which is a faster way to understand a documentation tool than a feature list.

Repo-Docs is not a file-tree tour. It is not a generated API dump. And it is not a chat transcript. Each of those is something you can produce automatically, and each is something that goes stale the moment the code changes without producing any warning.

What it produces instead is described as a small project guide that tells a reader four things: what the repository does, how the behaviour moves, where the proof lives, and how to keep that understanding fresh.

The problem it addresses is listed in the same shape. Code changed quickly but the reason stayed in chat. Files exist, yet nobody can explain the real behaviour path. The README, the source, the tests and the agent's own memory drift apart. And the next agent starts by rediscovering the same context that was already paid for once.

That last item is the one that matters for a team running agents. The cost is not the first discovery, it is paying for it again on every new session.

The project states its reason for existing in scale terms, citing two 2026 studies: one reporting 932,791 agent-authored pull requests across 116,211 GitHub repositories, and a census of 180 million repositories finding that many agent traces are missed by single-signal detection.

One real run beats an inventory

The artifact list is eight entries, and the first one is not the important one.

`repo-docs/README.md` orients a reader and points at the first useful path. `code-map.md` maps in-scope source directories to responsibilities, important code, tests and likely change points. Those two are conventional.

The load-bearing artifact is `walkthroughs/one-real-run.md`, which follows one real behaviour from an observable entry to its output. The quality bar spells out why: teach one real workflow before listing files. A reader who has followed one path end to end can navigate; a reader handed a directory listing cannot.

The rest follow the same logic of place. `modules/` holds the durable concepts the walkthrough names, so the idea is explained once rather than inline in every page that touches it. `references/` holds source evidence and optional quality review. `glossary.md` translates repeated project terms into plain meaning. `change-log.md` records meaningful guide work, verification and sync anchors.

Two rules govern where content is allowed to live. One durable fact, one home: concepts and needed details in modules, evidence and quality audit in references, history in the change log. And reader handles before locators: explain the concept, then link to the exact path, function, field or command. The second rule is the reason a reader can understand something without already knowing the filename.

The sync rule is deliberately conservative

The loop the skill runs is drawn as a small flowchart, and its design intent is stated in one sentence: it is intentionally conservative.

The trigger is a user question or an agent change to the repository. That goes to an understanding sync check, which then routes to one of four kinds of edit: updating the README and walkthrough, updating the change log, patching modules, the glossary or references, or updating `AGENTS.md` and `CLAUDE.md`. All four converge on the same outcome, a reader who can read the current project.

The rule for how much to change is the sentence that matters: a good update touches the page that would otherwise mislead the next reader, not every page that could be polished.

That is a constraint, and it is the one most likely to be dropped in practice. Any documentation skill that touches everything on every run produces a diff nobody can review, and the pages that mattered get buried in the polish. Restricting the edit to the page that would produce a wrong answer keeps the diff small enough to check.

The agent-facing files are part of the loop rather than an afterthought. `AGENTS.md` and `CLAUDE.md` are listed as artifacts whose job is to tell future coding agents when and how to keep docs current, which is how the rule survives after the session that created it ends.

Five modes, and Seed refuses to claim what does not exist yet

Five modes are defined, and each names what it preserves rather than what it produces. That framing matters more than it first appears.

Seed is for a repository that is new or has little runtime evidence. What it preserves is goals, decisions, planned work and unknowns. Build is for a repository that needs its first guide and produces the walkthrough, concepts, references, glossary and sync rule. Sync is the mode for when a question or a change may have made documentation stale, and its output is the smallest page that would otherwise mislead.

Cleanup handles the request to remove generated docs, taking out the docs package and stale pointers in the root agent files. Question refinement is the interesting one: when a question exposes a wrong reader model, the output is the corrected page followed by an answer linked to it. That ordering is the point, since an answer given before the correction will be wrong in the same way next time.

The Seed mode has a validation counterpart too. The validator takes a `--seed` flag for repositories that still need status-labeled plans instead of implementation claims.

That is a small concept with a large effect on trust. A documentation skill that writes confident descriptions of unbuilt features teaches the next agent to trust text it should verify.

The validator checks locators and post-anchor drift

Documentation that points at source is only as good as the pointers, and this project ships a script to check them.

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

Two arguments carry the weight. The first is the path to the generated docs package. The second, `--repo-root`, turns on the checks that need the source tree: it verifies source locators, meaning the paths, functions and fields the docs point at, and it checks for post-anchor drift, which is the case where a document recorded something about the state after a point in the source and the source has since moved past it.

Two more flags adjust the strictness. `--lite` is for small projects. `--seed` is for repositories that still need status-labeled plans rather than implementation claims.

That last pair of features is the practical way to run this in a real repository. Seed mode exists because a new project has no runtime evidence, and the quality bar says evidence stays visible: current source, tests, config, data, commands and artifacts outrank memory or stale documentation. A validator that rejected a repository for not yet having evidence would push people to write evidence they do not have.

The validator is a script inside the skill directory rather than a separate tool, so it travels with the install.

One install script, three skill directories, two languages

Installation is a shell script, and it is the least interesting part of a project whose interesting parts are all editorial.

The natural-language route is the primary one. You give your coding agent a request to install the skill from the repository URL and to make both the English and Chinese versions available in the agent's skill directory. Then you ask it to run the skill in any repository.

The shell route exists for people who prefer it:

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

From a checkout there are two useful variants. `./install.sh --agent all` writes into every known location, which the README names as the Codex, Claude and generic agents skill directories under the home folder. `./install.sh --target` writes into one directory you name.

There is a PowerShell script alongside the shell one for Windows, invoked the same way.

Two details are worth noting. First, both the English skill and a Chinese version are installed, and the usage examples show them used differently: one to create a docs package, the other to create a Chinese repo guide. A repository documentation skill that only writes English is less useful to a team that does not.

Second, the repository root already contains an `AGENTS.md`. The tool ships the file it tells you to produce.

Editorial conclusion

Adopt repo-docs-skills if your repository is being changed by agents faster than anyone can write documentation, and you want the reasoning kept in files rather than in chat history. Do not adopt it as an API reference generator, because the project explicitly rules out file-tree tours, generated API dumps and transcripts. Verify two things first. Run the validator script against a package before you trust it, since the locators and anchor checks are the only mechanism holding the docs to the code. Then read the Seed mode, because for a repository with no runtime evidence yet it deliberately preserves unknowns and planned work instead of writing implementation claims.

Frequently asked questions

Official sources

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