name: repo-docs description: Build and maintain a Markdown guide that helps humans understand a repository through real behavior, concepts, and evidence. Use when a user asks to understand a repo, generate or update repo-docs, answer repo-architecture/onboarding questions, seed docs for a new project, sync docs after code changes, or delete generated repo docs.

Repo-Docs

Mission

repo-docs explains a repository to a human reader.

Do not make a tree tour. Build a reader model: what problem the repo solves, one real behavior it performs, the concepts behind that behavior, where source truth lives, and how to verify the understanding.

Load Order

1. Read this file first.
2. Open REFERENCE.md for task routing when detailed rules are needed.
3. Open only the topic file the router points to.
4. Open EXAMPLES.md only for finished-page tone or output-shape examples.
5. Prefer bundled scripts over rewriting deterministic checks.

Keep the routing narrow. SKILL.md defines the contract; topic files carry the detailed rules. If a detail appears in two places, keep it in the topic file and leave a pointer here.

Document Contract

First Principles

• Behavior before inventory: teach one real workflow, request, task, failure, or data path first.
• Reader handles before locators: the handle explains; the exact path, function, field, command, or artifact proves.
• Direct source links by default: link one claim to one source with readable text. Create references/source-map.md only when repeated grouped locators would clutter pages.
• One durable fact, one home: concepts in modules/, exact lookup material in references/, term disambiguation in glossary.md, guide history in change-log.md.
• Evidence stays visible but quiet: current source, tests, config, data, command output, and artifacts outrank old docs, memory, and chat.

Output Contract

Use the smallest package that teaches the repo honestly.

• Standard: README.md, walkthroughs/one-real-run.md, modules/, references/, glossary.md, change-log.md.
• Lite: README.md, walkthroughs/one-real-run.md, change-log.md; use for small repos with little durable terminology.
• Seed: README.md, change-log.md, glossary.md, references/decisions.md; label facts as Confirmed, Planned, or Unknown.

Page Ownership

Build Workflow

1. Read project instructions, README, entrypoints, scripts, tests, schemas, config, data, artifacts, and existing docs.
2. Choose one representative real behavior that reveals the repo shape.
3. Write README.md and walkthroughs/one-real-run.md first.
4. Add modules only for concepts the walkthrough cannot explain cleanly inline.
5. Add references only for exact names or catalogs that would clutter narrative pages.
6. Add glossary.md and change-log.md.
7. Wire the guide into the project's agent instruction Markdown. Search for existing files such as AGENTS.md, AGENTS.override.md, CLAUDE.md, GEMINI.md, or .cursor/rules/*.md; patch the ones that clearly govern coding agents for this repo. If none exists, create AGENTS.md. The rule must say that future repo questions and behavior-changing edits should check repo-docs/, patch stale guide pages in the same turn when needed, and record meaningful guide work in repo-docs/change-log.md.
8. Run the validator and fix structure, link, and evidence problems.

For large repos or monorepos, scope the guide to one subsystem or workflow and say what is not covered.

Build is not finished until the next coding agent can maintain the guide without rediscovering the policy. The project agent instruction Markdown is the handoff point: it should point to repo-docs/README.md, name the main walkthrough, and tell future agents to run an Understanding Sync check when repo questions or behavior-changing edits appear.

Root Agent File Contract

When Build creates or updates repo-docs/, search the project for agent instruction Markdown before creating anything new. Look for common project files such as AGENTS.md, AGENTS.override.md, CLAUDE.md, GEMINI.md, and .cursor/rules/*.md, plus any nearby Markdown file whose filename or heading clearly says it is for coding agents.

Patch existing agent instruction files that already govern the repo or the package being documented. Do not create extra tool-specific files just to mirror the rule. If no such file exists, create AGENTS.md at the project root.

For nested packages, patch the nearest project agent instruction Markdown that governs the generated repo-docs/ package. If the guide is created at the repository root, use the root file.

The rule should say:

• The living guide is in repo-docs/; start with repo-docs/README.md.
• The main behavior trace lives in repo-docs/walkthroughs/one-real-run.md when that file exists.
• Before answering architecture, onboarding, or "how does this work" questions, read the relevant guide pages and inspect the current source behind the answer.
• If the guide is missing, stale, or wrong for current source, patch the smallest owning page in the same turn before answering.
• When code, config, data, scripts, tests, or behavior change, run an Understanding Sync check before finishing unless the user asked not to touch docs.
• Record meaningful guide updates in repo-docs/change-log.md with verification and Synced through <sha> when git is available.

Default block to write:

## Repo docs

The living project guide is in `repo-docs/`. Start with `repo-docs/README.md`; when `repo-docs/walkthroughs/one-real-run.md` exists, use it as the main behavior trace.

Before answering repo architecture, onboarding, or "how does this work" questions, read the relevant guide pages and inspect the current source behind the answer. If the guide is missing, stale, or wrong, update the smallest owning page in the same turn before answering.

When code, config, data, scripts, tests, or behavior changes, run an Understanding Sync check before finishing. Patch only the guide pages that would otherwise mislead the next reader. Record meaningful guide updates in `repo-docs/change-log.md` with verification and `Synced through <sha>` when git is available.

Keep this root rule short. Do not copy the guide into AGENTS.md or CLAUDE.md; those files route future agents back to repo-docs/.

Modes

repo-docs/ is maintained during the user ↔ coding agent conversation, not in a separate offline pass. Except Build, Seed, and Cleanup, run Understanding Sync each turn when repo-docs/ exists. Modes name common situations—not detached jobs. Detail: SCOPE_MODES.md, SYNC_RULES.md.

Understanding Sync

When repo-docs/ exists, ask: what would a new reader misunderstand if they read the guide today?

Patch the smallest owning page when this turn changed behavior-bearing source, data, config, scripts, or tests; a user correction revealed a stable understanding gap; or validator warnings show stale links, missing sync anchors, or likely drift.

Do not patch for one-off debug state, local environment quirks, or personal preference unless the user asks to preserve it.

Every material sync updates repo-docs/change-log.md with the trigger, changed pages, verification, and Synced through <sha> when git is available.

Use this loop during coding-agent interaction:

1. Read the current guide page that should already answer the question or describe the changed behavior.
2. Inspect the source, config, data, tests, command output, or artifact that proves the current behavior.
3. Decide whether the gap is durable. Durable means a future reader would likely misunderstand the repo, not merely miss a one-off debugging detail.
4. Patch the owning page:
   • behavior path changed -> walkthrough
   • concept changed or became clearer -> module
   • exact field, command, config, schema, metric, or artifact changed -> reference
   • term meaning changed -> glossary
   • material guide sync happened -> change log
   • root agent routing is missing or stale -> AGENTS.md / CLAUDE.md
5. Run the smallest useful check: validator, link check, relevant test, command, or source inspection.
6. Answer the user from the updated guide or from the inspected source, and mention what changed if docs were patched.

Writing Rules

Use WRITING.md for voice and explanation rules. The short version:

• Start with the situation a reader can recognize, then explain the reason, mechanism, check, and caveat.
• Keep README and walkthrough openings low in code names.
• Never let a path, function, field, or metric carry the explanation.
• Use flowcharts only for phase handoffs, branching paths, or state changes.
• Put page-level evidence status at the end of narrative pages: Evidence status: Confirmed unless noted.

Finish Checklist

Before delivery, confirm:

• The reader can start from repo-docs/README.md and reach the main walkthrough.
• walkthroughs/one-real-run.md follows one real behavior with numbered steps.
• Module pages use Plain model, Code model, and Read next when they exist.
• Exact fields, commands, schemas, metrics, and artifacts live in references/, not in the main narrative.
• Project agent instruction Markdown contains the Repo docs sync rule, or AGENTS.md was created.
• change-log.md records meaningful guide work and includes Synced through <sha> when git is available.
• The validator ran, or the reason it could not run is stated.

Verification

Before finishing, check structure, local links, source links, narrative flow, module ownership, and reference-page lookup behavior.

Run:

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

Delivery

First build: tell the user what the reader can now do, where to start, the key pages, scope, validator result, and root agent-file status. Keep durable history in change-log.md, not in chat.

Cleanup: if the user asks to remove repo docs, delete the generated docs package and stale root-agent pointers. Do not recreate docs in the same turn unless explicitly asked.

Widened sync closeout: when the user explicitly asks to sync, tidy, hand off, or repair stale docs, follow SYNC_RULES.md and summarize by changed layer—not a substitute for per-turn Understanding sync.

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

Repo-Docs starts with one thing the repo really does. It follows that behavior end to end, names the few ideas that matter, then points to the code and checks that prove the path. A reader should understand the behavior before memorizing paths.

The explanation stays in the tree. Docs land in repo-docs/ as plain Markdown: a walkthrough, concept pages, a glossary, and lookup tables. The next person should be able to open the repo cold and keep going.

Docs move with the code. When the repo shifts, or a question shows the write-up is behind reality, the skill patches the smallest page that fixes the misunderstanding in the same conversation.

Questions improve the guide. If the answer is not in the docs yet, the skill reads source, updates the right page, and replies with the page that now owns that understanding. For Chinese-first teams or personal projects, repo-docs-zh writes a more Chinese-native guide: Chinese carries the explanation, while source terms stay as lookup anchors.

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 the source repository root, copy the skill files into your agent skill directory:

mkdir -p ~/.agents/skills/repo-docs/scripts
cp SKILL.md REFERENCE.md WRITING.md PAGE_RULES.md SCOPE_MODES.md SYNC_RULES.md QUALITY_RULES.md EXAMPLES.md ~/.agents/skills/repo-docs/
cp scripts/validate_repo_docs.py ~/.agents/skills/repo-docs/scripts/
cp validate_repo_docs.py ~/.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.

Validation

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

Use --lite or --seed for smaller shapes. --repo-root checks source locators and post-anchor drift.

Modes

Except Build, Seed, and Cleanup, the default is an Understanding sync check each turn when repo-docs/ exists.

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. When repo-docs/ exists, the agent runs an understanding sync check each turn—patching the guide in the same thread when code changes or a question shows a stale reader model. Explicit sync, tidy, or handoff requests widen scope per SYNC_RULES.md.

What It Produces

Standard (default for non-Seed repos):

repo-docs/
  README.md
  walkthroughs/
    one-real-run.md
  modules/
  references/
  glossary.md
  change-log.md

Lite (small repos with little durable terminology):

repo-docs/
  README.md
  walkthroughs/
    one-real-run.md
  change-log.md

Seed (until real runtime evidence exists):

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

Triggered when a reader problem needs them: additional walkthroughs, flows.md (relationship map only—not a retelling of one-real-run.md), evidence-ledger.md.

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 generated or fast-changing code
• apps, libraries, tools, data pipelines, research repos, and benchmarks
• 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

<skills-dir>/
├── repo-docs/
│   ├── README.md
│   ├── README_CN.md
│   ├── SKILL.md
│   ├── REFERENCE.md
│   ├── WRITING.md
│   ├── PAGE_RULES.md
│   ├── SCOPE_MODES.md
│   ├── SYNC_RULES.md
│   ├── QUALITY_RULES.md
│   ├── EXAMPLES.md
│   ├── validate_repo_docs.py
│   └── scripts/
│       └── validate_repo_docs.py
└── repo-docs-zh/
    └── SKILL.md

File roles: Document Contract.

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.

Mark confidence quietly: one page-level note at the end of narrative pages (Evidence status: Confirmed unless noted.). Use Confirmed, Inferred, Planned, and Unknown only where confidence differs.

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.