Vibe coding makes projects grow quickly. Repo-Docs keeps the explanation, decisions, progress, and next steps close to the code.

Latest Updates · What is Repo-Docs? · Demonstration · Quick Start · Quality Bar

English · 中文 README

Latest Updates

New: walkthrough-first repo docs, root-level repo-docs/ output, Chinese
docs support, and Seed mode for empty repos. If Repo-Docs helps you keep up
with an agent-built project, a GitHub star 🌟 helps more builders find it.

• 2026-06-23: Added Chinese overlay support through repo-docs-zh.
• 2026-06-23: Added walkthrough-first docs through
  repo-docs/walkthroughs/one-real-run.md.
• 2026-06-23: Published the first README structure, repo-docs contract,
  reference standard, and example prompt.

What is Repo-Docs?

Vibe coding makes code appear quickly. Files change, decisions move, and the
reason behind a design can stay behind in chat. After a few sessions, the repo
may still run, but the user can no longer see the full shape of what was built.

repo-docs is a small agent skill for reducing that gap. It asks the coding
agent to keep living repo docs as work happens, starting from one real
walkthrough: what the user can observe, how the code/data/state move, what
changed, why it changed, what is decided, what is only planned, and what still
needs verification.

What It Does

You understand the repo before you memorize paths.
Pick one real thing it does and follow it end to end. Name the few ideas that actually matter. Then show where that behavior lives in code—and how you'd check you got it right. No directory tour. No pretending you've read everything.

The explanation stays in the tree.
Docs land in repo-docs/ as plain Markdown: a walkthrough, concept pages, a glossary, lookup tables. Not slides. Not a dump of every file. Something your future self—or the next agent—can open cold and still follow.

Docs move with the code.
You don't pause the session to "write documentation." When the repo shifts, or a question shows the write-up is behind reality, the skill patches the smallest page that fixes the misunderstanding—same thread, same conversation.

Questions improve the guide.
Ask how something works. If the answer isn't in the docs yet, the skill reads source, updates the right page, and replies with a link to where that understanding now lives.

Demonstration

A normal coding-agent session becomes a documentation loop:

flowchart LR
  A["User asks or agent changes repo"] --> B["Understanding sync check"]
  B --> C["Update README and walkthrough"]
  B --> D["Update change-log"]
  B --> E["Patch modules / glossary / references"]
  B --> F["Update AGENTS.md / CLAUDE.md"]
  C --> G["User can read the current project"]
  D --> G
  E --> G
  F --> G

After a milestone, Repo-Docs leaves the repo easier to continue:

Quick Start

There are two common ways to install the skill.

Natural-language install

Give this project link to your coding agent:

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.

Command install

From this project directory, copy the skill files into your agent skill
directory:

mkdir -p ~/.agents/skills/repo-docs
cp SKILL.md REFERENCE.md EXAMPLES.md ~/.agents/skills/repo-docs/
mkdir -p ~/.agents/skills/repo-docs-zh
cp repo-docs-zh/SKILL.md ~/.agents/skills/repo-docs-zh/SKILL.md

Then invoke it naturally:

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

Modes

Example Prompt

Use this once when a project needs its first repo docs:

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

After that, keep working naturally. During normal conversations, the agent
should decide when code changes, architecture questions, stale explanations, or
milestone handoffs require updating repo-docs/, change-log.md, and repo
agent instructions.

What It Produces

The default output is a Markdown docs package under the generated repo-docs/
directory:

repo-docs/
  README.md
  walkthroughs/
    one-real-run.md      # required for non-Seed repos
  glossary.md
  flows.md              # optional cross-workflow/state map
  change-log.md
  modules/
  references/

For seed projects, the generated docs stay smaller:

repo-docs/
  README.md
  change-log.md
  glossary.md                 # optional
  references/
    decisions.md              # optional

Built For

• people who want to stay in control while using coding agents
• projects that change faster than they can be explained in chat
• users who want to review and steer agent-built code
• benchmark, eval, experiment, and prompt-heavy repos
• new repos that need a memory baseline before code exists
• maintainers who want the repo to explain itself

Documentation Sync Model

repo-docs keeps three project-knowledge layers in sync during normal work:

Docs become the authority for current project understanding. Memory stays thin
and pointer-oriented.

What's Included

repo-docs/
├── README.md
├── README_CN.md
├── SKILL.md
├── REFERENCE.md
├── EXAMPLES.md
└── repo-docs-zh/
    └── SKILL.md

Quality Bar

A good repo-docs/ docs package is useful after the chat ends. A newcomer should be
able to read it and explain the repo in their own words, trace one real
workflow from observable entry to output, identify the important contracts, and
verify that understanding with a named test or command.

Important claims should be marked by confidence:

• Confirmed: backed by code, tests, config, data, docs, or artifacts
• Inferred: reasoned from nearby evidence and named as inference
• Unknown / 未确认: awaiting verification

For seed projects, planned work must stay visibly separate from implemented
facts.

Acknowledgements

• codebase-to-course
• neat-freak

Support

If Repo-Docs helps you keep up with the code your agents create, a GitHub star 🌟
helps others find it.

Repo-Docs: Keep up with the code your agents write.

Thanks for visiting Repo-Docs.