Skip to content
Back to search

repo-docs-skills

Living project docs for coding agents: keep guides, progress logs, change maps, and handoff context updated as your repo evolves.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yurunchen--repo-docs-skills/badge.svg)](/listings/yurunchen--repo-docs-skills)

HTML

<a href="/listings/yurunchen--repo-docs-skills"><img src="/api/listings/yurunchen--repo-docs-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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.

<details> <summary>Command-line install</summary>

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

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 265 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="site/assets/logo.png" width="86" alt="Repo-Docs logo" />
  3. <h1>Repo-Docs: Keep up with the code your agents write.</h1>
  4. <p><strong>An evidence atlas for agent-built code.</strong></p>
  5. <p>
  6. Vibe coding makes code move faster than memory. Repo-Docs turns each real
  7. run into walkthroughs, concepts, references, and sync rules that live beside
  8. the source.
  9. </p>
  10. <p>
  11. <a href="http://xhslink.com/o/9M27ebWDaD3">
  12. <img alt="RedNote(小红书)" src="https://img.shields.io/badge/RedNote(%E5%B0%8F%E7%BA%A2%E4%B9%A6)-Post-ff2442?style=for-the-badge&amp;labelColor=555" />
  13. </a>
  14. <a href="https://yurunchen.github.io/repo-docs-skills/">
  15. <img alt="Project homepage" src="https://img.shields.io/badge/Project%20Page-Online-27a36f?style=for-the-badge&amp;labelColor=555" />
  16. </a>
  17. </p>
  18. </div>
  19. <p align="center">
  20. <a href="README_CN.md">Chinese README</a> |
  21. <a href="skills/repo-docs/SKILL.md">Skill contract</a> |
  22. <a href="https://yurunchen.github.io/repo-docs-skills/">Project homepage</a> |
  23. <a href="#install-in-30-seconds">Install</a>
  24. </p>
  25. <p align="center">
  26. <a href="#why-this-exists-now"><strong>Why now</strong></a> |
  27. <a href="#the-repo-docs-loop"><strong>The loop</strong></a> |
  28. <a href="#what-it-builds"><strong>Artifacts</strong></a> |
  29. <a href="#quality-bar"><strong>Quality bar</strong></a>
  30. </p>
  31. <p align="center">
  32. <img
  33. src="site/assets/main.png"
  34. alt="Repo-Docs main preview"
  35. width="900"
  36. />
  37. </p>
  38. <p align="center">
  39. <em>Understand the repo before you memorize paths.</em>
  40. </p>
  41. ---
  42. ## The Problem
  43. <table>
  44. <tr>
  45. <td width="50%" valign="top">
  46. <h3>Agent-built repos often feel like this</h3>
  47. <ul>
  48. <li>Code changed quickly, but the reason stayed in chat.</li>
  49. <li>Files exist, yet no one can explain the real behavior path.</li>
  50. <li>README, source, tests, and agent memory drift apart.</li>
  51. <li>The next agent starts by rediscovering the same context.</li>
  52. </ul>
  53. </td>
  54. <td width="50%" valign="top">
  55. <h3>Repo-Docs leaves this behind</h3>
  56. <ul>
  57. <li>A walkthrough of one real run from entry to output.</li>
  58. <li>Concept pages for the few ideas that actually matter.</li>
  59. <li>Evidence pages for source proof and quality review.</li>
  60. <li>A sync rule that keeps future answers tied to current source.</li>
  61. </ul>
  62. </td>
  63. </tr>
  64. </table>
  65. Repo-Docs is not a file-tree tour, a generated API dump, or a chat transcript.
  66. It is a small project guide that tells a reader what the repo does, how the
  67. behavior moves, where the proof lives, and how to keep that understanding fresh.
  68. ## Why This Exists Now
  69. AI coding is no longer a niche workflow. Two 2026 open-source studies make the
  70. scale visible: [AIDev](https://arxiv.org/abs/2602.09185) reports 932,791
  71. agent-authored pull requests across 116,211 GitHub repositories, while a
  72. [multi-method census of 180 million repositories](https://arxiv.org/abs/2606.24429)
  73. shows that many agent traces are missed by single-signal detection.
  74. That growth creates a new maintenance problem: the code may be real, but the
  75. project understanding is often temporary. Repo-Docs gives coding agents a
  76. repeatable way to preserve the reasoning layer inside the repository itself.
  77. ## The Repo-Docs Loop
  78. ```mermaid
  79. flowchart LR
  80. A["User asks or agent changes repo"] --> B["Understanding sync check"]
  81. B --> C["Update README and walkthrough"]
  82. B --> D["Update change-log"]
  83. B --> E["Patch modules / glossary / references"]
  84. B --> F["Update AGENTS.md / CLAUDE.md"]
  85. C --> G["User can read the current project"]
  86. D --> G
  87. E --> G
  88. F --> G
  89. ```
  90. The loop is intentionally conservative. A good update touches the page that
  91. would otherwise mislead the next reader, not every page that could be polished.
  92. ## What It Builds
  93. | Artifact | Job |
  94. | --- | --- |
  95. | `repo-docs/README.md` | Orient the reader and point to the first useful path. |
  96. | `walkthroughs/one-real-run.md` | Follow one real behavior from observable entry to output. |
  97. | `code-map.md` | Map in-scope source directories to responsibilities, important code, tests, and likely change points. |
  98. | `modules/` | Explain durable concepts the walkthrough names. |
  99. | `references/` | Hold source evidence and optional quality review. |
  100. | `glossary.md` | Translate repeated project terms into plain meaning. |
  101. | `change-log.md` | Record meaningful guide work, verification, and sync anchors. |
  102. | `AGENTS.md` / `CLAUDE.md` | Tell future coding agents when and how to keep docs current. |
  103. ## Install In 30 Seconds
  104. Give this natural-language install request to your coding agent:
  105. ```text
  106. Install the repo-docs skill from this project:
  107. https://github.com/YurunChen/repo-docs-skills
  108. Make both repo-docs and repo-docs-zh available in my agent skill directory.
  109. ```
  110. Then ask it to run the skill in any repository:
  111. ```text
  112. Use the repo-docs skill to create docs for this repository.
  113. ```
  114. <details>
  115. <summary>Command-line install</summary>
  116. 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.
  117. ```bash
  118. curl -fsSL https://github.com/YurunChen/repo-docs-skills/raw/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 143 on GitHub
  119. ```
  120. Windows PowerShell:
  121. ```powershell
  122. irm https://github.com/YurunChen/repo-docs-skills/raw/main/install.ps1 | iex
  123. ```
  124. From this source checkout:
  125. ```bash
  126. ./install.sh
  127. # Install into all known locations: ~/.codex/skills, ~/.claude/skills, ~/.agents/skills
  128. ./install.sh --agent all
  129. # Install into one explicit skills directory
  130. ./install.sh --target ~/.agents/skills
  131. ```
  132. </details>
  133. ## Use It Naturally
  134. ```text
  135. Use the repo-docs skill to create docs for this repository.
  136. ```
  137. ```text
  138. Use repo-docs-zh to create a Chinese repo guide for this project.
  139. ```
  140. ```text
  141. Explain how this subsystem works using repo-docs and the current source.
  142. ```
  143. ## Modes
  144. | Mode | Use when | What it preserves |
  145. | --- | --- | --- |
  146. | Seed | The repo is new or has little runtime evidence | Goals, decisions, planned work, and unknowns |
  147. | Build | The repo needs its first guide | Walkthrough, concepts, references, glossary, and sync rule |
  148. | Sync | A repo question or guide-covered behavior may make docs stale | The smallest page that would otherwise mislead |
  149. | Cleanup | The user asks to remove generated docs | Docs package and stale root-agent pointers |
  150. | Question refinement | A question exposes a wrong reader model | The corrected page, then an answer linked to it |
  151. ## Validation
  152. ```bash
  153. python skills/repo-docs/scripts/validate_repo_docs.py /path/to/repo-docs --repo-root /path/to/repo
  154. ```
  155. Use `--lite` for small projects and `--seed` for repositories that still need
  156. status-labeled plans instead of implementation claims. `--repo-root` checks
  157. source locators and post-anchor drift.
  158. ## Quality Bar
  159. A good Repo-Docs package is useful after the chat ends.
  160. | Principle | Meaning |
  161. | --- | --- |
  162. | Behavior before inventory | Teach one real workflow before listing files. |
  163. | Reader handles before locators | Explain the concept, then link to the exact path, function, field, or command. |
  164. | One durable fact, one home | Concepts and needed details live in modules; evidence and quality audit live in references; history lives in the change log. |
  165. | Evidence stays visible | Current source, tests, config, data, commands, and artifacts outrank memory or stale docs. |
  166. | Patches stay surgical | When understanding drifts, update the smallest page that fixes the reader model. |
  167. ## Source Layout
  168. ```text
  169. repo-docs-skills/
  170. ├── skills/
  171. │ ├── repo-docs/ # installable skill package
  172. │ └── repo-docs-zh/ # Chinese language overlay
  173. ├── site/ # homepage source
  174. ├── docs/ # GitHub Pages publish tree
  175. ├── install.sh
  176. ├── install.ps1
  177. ├── README.md
  178. └── README_CN.md
  179. ```
  180. The installable skill source lives under `skills/`. The `site/` directory is homepage source, while `docs/` is the GitHub Pages publish tree.
  181. ## Installed Package Contents
  182. ```text
  183. <skills-dir>/
  184. ├── repo-docs/
  185. │ ├── SKILL.md
  186. │ ├── REFERENCE.md
  187. │ ├── WRITING.md
  188. │ ├── PAGE_RULES.md
  189. │ ├── SCOPE_MODES.md
  190. │ ├── SYNC_RULES.md
  191. │ ├── QUALITY_RULES.md
  192. │ ├── EXAMPLES.md
  193. │ ├── validate_repo_docs.py
  194. │ └── scripts/
  195. │ └── validate_repo_docs.py
  196. └── repo-docs-zh/
  197. └── SKILL.md
  198. ```
  199. ## Acknowledgements
  200. Repo Docs Skills is developed by the [AI4GC Lab](https://ai4gc.org/) at Zhejiang University.
  201. - [codebase-to-course](https://github.com/zarazhangrui/codebase-to-course)
  202. - [neat-freak](https://github.com/KKKKhazix/khazix-skills)
  203. ---
  204. <div align="center">
  205. <strong>Repo-Docs:</strong> make the repository explain itself.
  206. <br />
  207. <sub>Walkthroughs, evidence, references, sync rules, and project memory for fast-moving code.</sub>
  208. <br />
  209. <br />
  210. <img src="https://visitor-badge.laobi.icu/badge?page_id=YurunChen.Repo-Docs" alt="visitors" />
  211. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.