repo-docs-skills

The Problem

Repo-Docs is not a file-tree tour, a generated API dump, or a chat transcript. It is a small project guide that tells a reader what the repo does, how the behavior moves, where the proof lives, and how to keep that understanding fresh.

Why This Exists Now

AI coding is no longer a niche workflow. Two 2026 open-source studies make the scale visible: AIDev reports 932,791 agent-authored pull requests across 116,211 GitHub repositories, while a multi-method census of 180 million repositories shows that many agent traces are missed by single-signal detection.

That growth creates a new maintenance problem: the code may be real, but the project understanding is often temporary. Repo-Docs gives coding agents a repeatable way to preserve the reasoning layer inside the repository itself.

The Repo-Docs 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

The loop is intentionally conservative. A good update touches the page that would otherwise mislead the next reader, not every page that could be polished.

What It Builds

Install In 30 Seconds

Give this natural-language install request 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.

Then ask it to run the skill in any repository:

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

Use this when you prefer a shell install. The URL is a GitHub repository raw-file URL; GitHub serves the raw script bytes through its raw content host after redirect.

curl -fsSL https://github.com/YurunChen/repo-docs-skills/raw/main/install.sh | bash

Windows PowerShell:

irm https://github.com/YurunChen/repo-docs-skills/raw/main/install.ps1 | iex

From this source checkout:

./install.sh

# Install into all known locations: ~/.codex/skills, ~/.claude/skills, ~/.agents/skills
./install.sh --agent all

# Install into one explicit skills directory
./install.sh --target ~/.agents/skills

Use It Naturally

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

Use repo-docs-zh to create a Chinese repo guide for this project.

Explain how this subsystem works using repo-docs and the current source.

Modes

Validation

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

Use --lite for small projects and --seed for repositories that still need status-labeled plans instead of implementation claims. --repo-root checks source locators and post-anchor drift.

Quality Bar

A good Repo-Docs package is useful after the chat ends.

Source Layout

repo-docs-skills/
├── skills/
│   ├── repo-docs/        # installable skill package
│   └── repo-docs-zh/     # Chinese language overlay
├── site/                 # homepage source
├── docs/                 # GitHub Pages publish tree
├── install.sh
├── install.ps1
├── README.md
└── README_CN.md

The installable skill source lives under skills/. The site/ directory is homepage source, while docs/ is the GitHub Pages publish tree.

Installed Package Contents

<skills-dir>/
├── repo-docs/
│   ├── 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

Acknowledgements

Repo Docs Skills is developed by the AI4GC Lab at Zhejiang University.

• codebase-to-course
• neat-freak