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
- ★ 427
- Last updated
- 4mo ago
- Primary language
- Python
- FA score
- 45/100 · Major gaps
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
- Website
- yurunchen.github.io/repo-docs-skills ↗ set on GitHub
- Maintenance
- Commits in the last 6 monthslast commit 2026-07-12
- Source review
- 45/100 · Major gaps
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.
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Config files
~/.codex/skills~/.claude/skills~/.agents/skills- Install notes cover
- Windows · macOS · Linux
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 | 45 · Major gaps | Agent plugin / skillFree + model costs | ★ 427 | 4mo ago | Python | Codex · Claude Code |
| Keep the Why | 83 · Good | Agent plugin / skillFree | ★ 240 | 3d ago | JavaScript | Codex · Claude Code |
| VibeSkills — Intelligent Skill Orchestrator | 64 · Some gaps | Agent plugin / skillFree + model costs | ★ 3.8k | 12d ago | Python | Codex · Claude Code |
| Softaworks Agent Skills | 44 · Major gaps | Agent plugin / skillFree + model costs | ★ 2.7k | 8mo ago | Python | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The materials describe generating and updating documentation for a local repository, require grounding durable claims in source, tests, or configuration, and provide installation methods. The excerpts do not explain exactly which paths the installers access or modify, how confirmation is obtained before writes, how sensitive data is handled, how changes can be rolled back, or how dependencies are reviewed, so these areas receive partial credit. Attribution appears only in an acknowledgement naming AI4GC Lab; verified publisher identity and a security maintenance channel are not shown.
The skill directs users to route through topic files, use the bundled validator, and report when validation cannot run; the README also lists validation commands. The README and skill entry are broadly consistent about the artifact set, but the supplied SKILL.md excerpts end mid-file, so full rules, error handling, and script dependencies cannot be checked. Scores are therefore partial.
The stated scenarios include seeding a new repository, building an initial guide, syncing after changes, cleanup, repository questions, and Chinese documentation. The skill distinguishes Seed, Build, Sync, and Cleanup modes and calls for a decision before editing on ordinary questions. The shown rules are reasonably clear, but environment adaptation is thin: the excerpts do not show complete handling of differences among agent environments, platforms, or permissions.
The README provides navigation through installation notes, artifact and mode tables, and a source layout; the skill defines file responsibilities and a consistent document contract. It gives natural-language and command-line installation, usage examples, and validation commands, but the supplied material does not show troubleshooting FAQs or a complete limitations section. License metadata is explicitly unknown, so the license criterion scores 0. Release history and maintenance responsibility or update channels are not established in the excerpts, earning only partial credit.
The product targets a concrete documentation maintenance problem and specifies usable artifacts such as a walkthrough, code map, evidence pages, glossary, and change log. Its rule to update only the smallest page that would otherwise mislead suggests practical value. No execution results or cost data are supplied to establish the balance between maintenance effort and benefit, so cost-benefit receives partial credit.
The skill prioritizes source evidence, exact locators, and inference or unconfirmed labels in Chinese output; it also describes the validator's intended checks. The README and skill provide some corroboration of the workflow and artifacts, but complete implementation, validator source, and independent results are not in the packet. The excerpts are truncated, so stronger conclusions are not justified.
- The supplied SKILL.md excerpts are truncated, so the full instructions, dependencies, installer behavior, and failure handling cannot be confirmed; unseen files are unknown.
- The installation examples execute remote scripts through a shell. Review the corresponding installer and confirm target directories and overwrite behavior before use; those scripts were not included in this review.
- License metadata is unknown; verify the license before use or redistribution.
FAQ
Is Repo-Docs free?
Is Repo-Docs open source?
Is Repo-Docs safe to use?
Is Repo-Docs still maintained?
Who makes Repo-Docs?
What is Repo-Docs's official website?
Thanks — we use this to improve the page.