A source-backed guide for agent-built code.

Keep up with the code your agents write.

When code moves quickly, context is easy to leave behind. Repo-Docs helps you turn one real run into a few clear pages that live with the source: walkthroughs, concepts, references, and sync notes.

Start with understanding, then follow the paths.

repo-docs install prompt

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.

See generated docs GitHub Contribute

Works with

Cursor
Claude Code
Codex
Copilot
Windsurf

Fast-moving code needs a place for context.

Repo-Docs is not a file-tree tour or a chat archive. It keeps a modest project guide beside the source, so the next person can see why things work instead of piecing it together from old messages.

When context stays in chat

The code changed, but the reason is hard to find later.
There are many files, yet the real behavior path is still unclear.
README, source, tests, and agent notes slowly drift apart.
The next reader has to rediscover the same context again.

When context lives with source

A walkthrough follows one real run from entry to output.
Short concept pages name the ideas worth remembering.
Reference pages keep commands, fields, schemas, and evidence easy to check.
A sync note tells future agents when a page needs a small update.

Start from a run Follow one real behavior before making a file inventory.

Keep the evidence close Commands, contracts, and source links stay with the explanation.

Update gently When something changes, patch the page that owns it.

GitHub examples

A few real repositories, with the generated docs visible.

These examples come from public GitHub repositories that are not skill projects. Each panel shows the files Repo-Docs generated, and each file opens the Markdown content written from inspected source.

Aider-AI/aider repo-docs/ terminal edit run Open full case

repo-docs/

walkthroughs/

modules/

references/

walkthroughs/terminal-edit-run.md

Loading generated file...

Evidence loop

Keep the guide close to what the code actually does.

Start with one behavior you can observe, name the concepts that help explain it, and keep the exact source evidence nearby. When the code changes, update the smallest page that needs it.

Observe Follow a behavior through source, tests, data, or UI.

Name Give stable concepts their own small module pages.

Anchor Keep exact lookup details in references with source evidence.

Repair When code changes, update the page that owns that knowledge.

Generated artifacts

What Repo-Docs generates

The output is intentionally small. Instead of one long README, Repo-Docs creates a few pages with clear jobs, so reading and lookup both stay manageable.

Walkthroughs

Walk through one behavior from entry point to output.

Depth: Route
Proof: High

Module pages

Explain the concepts and ownership boundaries worth keeping.

Scope: Concept
Drift: Low

References

Keep commands, schemas, fields, and exact links easy to check.

Lookup: Exact
Links: Source

Sync rules

Tell future agents how to keep the pages current.

Trigger: Drift
Patch: Minimal

Skill modes

Use the mode that matches where the repo is.

You can use Repo-Docs when a repo is new, when docs drift, or when a plan needs a clearer starting point. In each case, the work starts by checking what is actually true.

What are you trying to do?

Build

Start a useful guide for a repo that already exists.

Sync

Refresh the pages affected by code, config, data, or test changes.

Seed

Separate planned work, open questions, and confirmed facts before code exists.

Refine

Improve the guide when a real question shows what readers still need.

Sync loop

A practical loop for keeping docs current.

Read

Open the page that should help answer the question.

Inspect

Check the current source, command, artifact, config, or data.

Patch

Update the page only when the gap is likely to matter again.

Answer

Answer from evidence and leave the repo a little easier to continue.

Open source

Help make Repo-Docs easier to trust and maintain.

Repo-Docs is open source. If it misses something in a real workflow, issues and PRs are welcome. Small fixes, examples, and clearer docs all help.

GitHub Open source contribution

GitHub Issues Open issue Pull Requests Send PR