Repo Docs
Builds a repo-docs guide from one real code path, with an evidence table and a validator
Test report
- Verdict
- Tested · Works
- Score
- Tested
- Jul 31, 2026
- Environment
- Claude Code 2.x (agent harness)
- Upstream re-checked
- Aug 10, 2026 · d8ef152
Fetched skills/repo-docs/SKILL.md (frontmatter has name+description); spot-checked REFERENCE.md, PAGE_RULES.md, scripts/validate_repo_docs.py, QUALITY_RULES.md and repo-docs-zh/SKILL.md — all HTTP 200. Verified the install block end to end under `export HOME=$(mktemp -d)`: SKILL.md lands at ~/.claude/skills/repo-docs/SKILL.md with scripts/ and evals/ intact. Only security note: install.sh advertises `curl -fsSL ... | bash` in its own usage text; no base64 blobs, no injection strings, and the validator's only subprocess is `git diff --name-only`. Task: document simonw/json-flatten (132-line library, commit 78c2835) for a new contributor. Baseline (scratchpad/baseline/DOCUMENTATION.md, one file) opened with a file tree, listed the $type encoding table and implementation notes — accurate but read-only, and it implicitly asserted round-trip fidelity. Skill artifact (scratchpad/skillrun/repo-docs/: README, walkthroughs/one-real-run.md, references/source-evidence.md, change-log.md) forced a Pass-2 "falsifying check", which made me actually execute the code and find a real defect the baseline missed and the upstream README never mentions: `unflatten(flatten({'a.b': 1}))` returns `{'a': {'b': 1}}` — dotted keys silently reshape, and no test covers it. That became the README headline caveat. The skill also produced a Claim|Evidence|Confidence|Caveat|Used-by table citing the command or source line per row, plus an explanation the baseline lacked (why isinstance(bool) is checked before int, and what breaks if swapped). The bundled validator is real and works: first draft gave `FAILED: 2 error(s), 12 warning(s)` (missing `## Reader Routes` table, low-scent link labels), exit 1; after one edit pass, `OK: 0 errors, 6 warning(s)`. Trigger — SHOULD: (1) "Generate onboarding docs for this repo so a new engineer can understand it" -> load; (2) "I refactored the auth module, update repo-docs to match" -> load; (3) "Explain the architecture of this codebase to me" -> load. SHOULD NOT: (4) "Write a CHANGELOG entry for the v2.1 release" -> skip (release notes, not a repo guide); (5) "Add docstrings to every function in src/utils.py" -> skip (inline comments). 5/5 correct. Cost: 4 files of process for a 132-line repo, and the validator still wants an AGENTS.md written into the target repo root.
Scored on four weighted criteria — install, triggering, output vs. baseline, docs. How scoring works
- Installs cleanly 5/5
- Triggers reliably 5/5
- Output vs. baseline 8/10
- Docs & honesty 4/5
What Repo Docs does
Generates and maintains a Markdown guide (README, one-real-run walkthrough, code map, modules, source-evidence table, change log) that explains a repository through one real behavior instead of a file-tree tour. Triggers when someone asks to understand a codebase, generate or update repo docs, write onboarding material, answer repo-architecture questions, or sync docs after code changes. Ships a Python validator that checks structure, links, evidence labels, and reader scent before delivery.
How to install Repo Docs
git clone --depth 1 https://github.com/YurunChen/repo-docs-skills.git /tmp/repo-docs-src
mkdir -p ~/.claude/skills
cp -R /tmp/repo-docs-src/skills/repo-docs ~/.claude/skills/repo-docs
# Optional Chinese overlay:
# cp -R /tmp/repo-docs-src/skills/repo-docs-zh ~/.claude/skills/repo-docs-zh
# Bundled finish gate needs python3 (stdlib only, no pip deps):
# python3 ~/.claude/skills/repo-docs/scripts/validate_repo_docs.py <path-to-repo-docs> --repo-root <repo-root> [--lite]
# The repo also ships install.sh, whose usage advertises curl|bash; the clone above avoids that.
Skills live in ~/.claude/skills/ (global) or .claude/skills/
(per-project). Restart Claude Code after installing.
Commands — how to trigger Repo Docs
-
/repo-docsBuilds a repo-docs guide from one real code path, with an evidence table and a validator
It also activates on plain-language prompts like these:
-
Generate onboarding docs for this repository -
Update repo docs after these code changes -
Explain this repo's architecture with evidence
Frequently asked questions
- Is the Repo Docs skill free?
- Yes. The skill itself is free from YurunChen/repo-docs-skills. SkillProof publishes the install command and an independent test verdict at no cost.
- Does Repo Docs work with Claude Code?
- We tested it with Claude Code 2.x (agent harness) on Jul 31, 2026. Verdict: Tested · Works. Fetched skills/repo-docs/SKILL.md (frontmatter has name+description); spot-checked REFERENCE.md, PAGE_RULES.md, scripts/validate_repo_docs.py, QUALITY_RULES.md and repo-docs-zh/SKILL.md — all HTTP 200. Verified the install block end to end under `export HOME=$(mktemp -d)`: SKILL.md lands at ~/.claude/skills/repo-docs/SKILL.md with scripts/ and evals/ intact. Only security note: install.sh advertises `curl -fsSL ... | bash` in its own usage text; no base64 blobs, no injection strings, and the validator's only subprocess is `git diff --name-only`. Task: document simonw/json-flatten (132-line library, commit 78c2835) for a new contributor. Baseline (scratchpad/baseline/DOCUMENTATION.md, one file) opened with a file tree, listed the $type encoding table and implementation notes — accurate but read-only, and it implicitly asserted round-trip fidelity. Skill artifact (scratchpad/skillrun/repo-docs/: README, walkthroughs/one-real-run.md, references/source-evidence.md, change-log.md) forced a Pass-2 "falsifying check", which made me actually execute the code and find a real defect the baseline missed and the upstream README never mentions: `unflatten(flatten({'a.b': 1}))` returns `{'a': {'b': 1}}` — dotted keys silently reshape, and no test covers it. That became the README headline caveat. The skill also produced a Claim|Evidence|Confidence|Caveat|Used-by table citing the command or source line per row, plus an explanation the baseline lacked (why isinstance(bool) is checked before int, and what breaks if swapped). The bundled validator is real and works: first draft gave `FAILED: 2 error(s), 12 warning(s)` (missing `## Reader Routes` table, low-scent link labels), exit 1; after one edit pass, `OK: 0 errors, 6 warning(s)`. Trigger — SHOULD: (1) "Generate onboarding docs for this repo so a new engineer can understand it" -> load; (2) "I refactored the auth module, update repo-docs to match" -> load; (3) "Explain the architecture of this codebase to me" -> load. SHOULD NOT: (4) "Write a CHANGELOG entry for the v2.1 release" -> skip (release notes, not a repo guide); (5) "Add docstrings to every function in src/utils.py" -> skip (inline comments). 5/5 correct. Cost: 4 files of process for a 132-line repo, and the validator still wants an AGENTS.md written into the target repo root.
- What is the Repo Docs SkillProof Score?
- 8.8/10 — installs cleanly 5/5, triggers reliably 5/5, output vs. baseline 8/10, docs & honesty 4/5.
- How do I install Repo Docs?
- Copy the install command from this page, run it in your terminal, and restart Claude Code. Skills live in ~/.claude/skills/ (global) or .claude/skills/ inside a project.
- Can I use Repo Docs with Cursor, Copilot, Gemini CLI, Codex or other AI tools?
- The SKILL.md format is native to Claude (Claude Code, Desktop, claude.ai). The instructions inside adapt to other assistants: Cursor rules, GitHub Copilot instructions, Windsurf rules, Custom GPTs, AGENTS.md for OpenAI Codex, and GEMINI.md for Google Gemini CLI — our conversion guides cover each, and the free converter on the tools page does the wrapping for you.