Repo-Docs
Living project documentation for coding agents: walkthroughs, change logs, code maps, and handoff context that stay current as your repository evolves.
- Source repo
- YurunChen/repo-docs-skills
- Stars
- ★ 468
- Last updated
- 2mo ago
- Primary language
- Python
- FA score
- Insufficient evidence
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers vibe-coding with Claude Code or Codex who want project understanding to survive beyond the chat window.
- Not a fit if
- Repos without skill-install support need manual adaptation the docs don't describe
- Users wanting a generated API dump or file-tree tour
- Source review
- Insufficient evidence
What does this agent do, and when should you use it?
Repo-Docs is an installable skill package developed by the AI4GC Lab at Zhejiang University, built to solve a problem of the vibe-coding era: code now changes faster than project memory. Installed as a Claude/Codex skill, it maintains a structured documentation set inside your repository after real agent runs, including repo-docs/README.md, a single-real-run walkthrough (walkthroughs/one-real-run.md), code-map.md, modules/, references/, glossary.md, change-log.md, and AGENTS.md / CLAUDE.md handoff pointers for future agents. Its core is a deliberately conservative sync loop: when a user question or agent change could make docs stale, only the smallest page that would otherwise mislead the next reader gets patched. The package includes a Chinese overlay skill (repo-docs-zh) and a Python validator, validate_repo_docs.py, that checks source locators and post-anchor drift. Command-line installers (install.sh / install.ps1) are provided, and the quality bar is explicit: behavior before inventory, visible evidence, and surgical patches.
Repo-Docs installs as a skill package (SKILL.md, REFERENCE.md, WRITING.md, PAGE_RULES.md, SCOPE_MODES.md, SYNC_RULES.md, QUALITY_RULES.md, EXAMPLES.md). When run in a repository, it reads source code and runtime evidence and produces eight artifacts: an entry README, a one-real-run walkthrough tracing observable behavior from entry to output, a code-map that maps source directories to responsibilities/tests/change points, modules/ explaining durable concepts, references/ holding source evidence and optional quality review, a glossary, a change-log recording verification and sync anchors, and AGENTS.md / CLAUDE.md files telling future agents how to keep docs current. It operates in five modes: Seed (record goals, decisions, and unknowns for new repos), Build (create the first guide), Sync (patch the smallest stale page), Cleanup (remove generated docs), and Question refinement (correct a wrong reader model). Generated packages can be validated with skills/repo-docs/scripts/validate_repo_docs.py, using --lite, --seed, and --repo-root options to check source locators and anchor drift.
- Developers vibe-coding with Claude Code or Codex who want project understanding to survive beyond the chat window.
- Engineers inheriting an agent-built codebase who need a real behavior walkthrough rather than a file-tree tour.
- Team maintainers who want README, source, tests, and agent memory to stay in sync and avoid documentation drift.
- Project leads needing Chinese-language guides, using the repo-docs-zh overlay to generate a Chinese repo guide.
- Code reviewers who want source evidence and quality audit notes preserved inside the repo's references/ pages.
- Multi-agent workflows where the next agent should start from recorded handoff context instead of rediscovering it.
How do you install or deploy this agent?
Option 1 (recommended): give your coding agent this natural-language request: "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." Option 2 (command line): on Linux/macOS run curl -fsSL https://github.com/YurunChen/repo-docs-skills/raw/main/install.sh | bash; on Windows PowerShell run irm https://github.com/YurunChen/repo-docs-skills/raw/main/install.ps1 | iex; from a source checkout run ./install.sh, with --agent all to install into ~/.codex/skills, ~/.claude/skills, and ~/.agents/skills, or --target ~/.agents/skills for one explicit directory. Runtime requirement: a coding agent host that supports skills (Claude Code / Codex).
How do you use this agent?
After install, invoke it in natural language, e.g.: "Use the repo-docs skill to create docs for this repository." or "Use repo-docs-zh to create a Chinese repo guide for this project." or "Explain how this subsystem works using repo-docs and the current source." Validate output with python skills/repo-docs/scripts/validate_repo_docs.py /path/to/repo-docs --repo-root /path/to/repo (add --lite for small projects, --seed for repos that only have status-labeled plans).
What are this agent's strengths and limitations?
- A clear mode system (Seed/Build/Sync/Cleanup/Question refinement) with deliberately conservative sync rules: only the smallest misleading page gets patched, so doc maintenance never becomes a full rewrite.
- Docs are bound to source evidence: references/ hold source proof, and validate_repo_docs.py machine-checks source locators and post-anchor drift, so staleness is verifiable.
- Native Chinese repo guides via the repo-docs-zh overlay plus a bilingual README, useful for Chinese-speaking teams.
- Artifacts are aimed at future agents (AGENTS.md / CLAUDE.md), remaining useful after the chat ends instead of being a one-off file-tree dump.
- It depends on a skill-capable agent host (Claude Code, Codex); repos without skill installation support require manual adaptation, which the docs do not describe.
- No license is stated in the README (License: unknown), so commercial adoption requires confirming terms with the author.
- Doc quality depends on the host agent's understanding and available runtime evidence; new repos can only run Seed mode with status-labeled plans, not implementation claims.
- The validator needs Python, and command-line installation requires network access to GitHub's raw content host.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Repo-Docs This agent | Insufficient evidence | Agent plugin / skillFree + model costs | ★ 468 | 2mo ago | Python | Codex · Claude Code |
| VibeSkills — Intelligent Skill Orchestrator | 46 · Major gaps | Agent plugin / skillFree + model costs | ★ 3.5k | 26d ago | Python | Codex · Claude Code |
| Softaworks Agent Skills | 51 · Major gaps | Agent plugin / skillFree + model costs | ★ 2.5k | 6mo ago | Python | Claude Code |
| Vibe Coding Chinese Guide | 38 · Major gaps | CLIFree | ★ 16k | today | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
- No license is declared; confirm licensing terms before enterprise use.
- The curl|bash remote install carries supply-chain risk; review install.sh before executing.
- SKILL.md, the validator, and install scripts were not in the reviewed evidence; actual permissions and file-write behavior are unverified—trial in a sandbox first.
- The 2026 arXiv statistics cited in the README are background motivation only, not evidence of this tool's effectiveness.