Repo Docs

Bouwt een repo-docs gids vanuit één echt codepad, met een bewijstabel en een validator

Door YurunChen · YurunChen/repo-docs-skills

Getest · Werkt ★ 8.8/10

Repo Docs — Bouwt een repo-docs gids vanuit één echt codepad, met een bewijstabel en een validator

Wat het doet

Genereert en onderhoudt een Markdown-gids (README, one-real-run walkthrough, codekaart, modules, bron-bewijstabel, changelog) die een repository uitlegt via één echt gedrag in plaats van een bestandboomtour. Activeert wanneer iemand vraagt om een codebase te begrijpen, repo-docs te genereren of bij te werken, onboardingmateriaal te schrijven, vragen over repo-architectuur te beantwoorden, of docs te synchroniseren na codewijzigingen. Levert een Python validator die structuur, links, bewijslabels en 'reader scent' controleert vóór levering.

Testrapport

skills/repo-docs/SKILL.md opgehaald (frontmatter heeft name+description); steekproefsgewijs gecontroleerd REFERENCE.md, PAGE_RULES.md, scripts/validate_repo_docs.py, QUALITY_RULES.md en repo-docs-zh/SKILL.md — allemaal HTTP 200. Het installatieblok end-to-end geverifieerd onder `export HOME=$(mktemp -d)`: SKILL.md landt op ~/.claude/skills/repo-docs/SKILL.md met scripts/ en evals/ intact. Enige beveiligingsopmerking: install.sh adverteert `curl -fsSL ... | bash` in zijn eigen gebruikstekst; geen base64 blobs, geen injectiestrings, en de enige subprocess van de validator is `git diff --name-only`. Taak: documenteer simonw/json-flatten (132-regelige bibliotheek, commit 78c2835) voor een nieuwe bijdrager. Baseline (scratchpad/baseline/DOCUMENTATION.md, één bestand) opende met een bestandboom, vermeldde de $type encoding tabel en implementatienotities — nauwkeurig maar alleen-lezen, en het beweerde impliciet round-trip fidelity. Skill artefact (scratchpad/skillrun/repo-docs/: README, walkthroughs/one-real-run.md, references/source-evidence.md, change-log.md) dwong een Pass-2 "falsifying check" af, waardoor ik de code daadwerkelijk uitvoerde en een echt defect vond dat de baseline miste en de upstream README nooit vermeldt: `unflatten(flatten({'a.b': 1}))` retourneert `{'a': {'b': 1}}` — gestippelde sleutels vormen stilzwijgend om, en geen enkele test dekt dit. Dat werd de README headline caveat. De skill produceerde ook een Claim|Evidence|Confidence|Caveat|Used-by tabel die de opdracht of bronregel per rij citeerde, plus een uitleg die de baseline miste (waarom isinstance(bool) vóór int wordt gecontroleerd, en wat er breekt als het wordt omgewisseld). De gebundelde validator is echt en werkt: eerste concept gaf `FAILED: 2 error(s), 12 warning(s)` (ontbrekende `## Reader Routes` tabel, low-scent link labels), exit 1; na één bewerkingsronde, `OK: 0 errors, 6 warning(s)`. Trigger — MOET: (1) "Generate onboarding docs for this repo so a new engineer can understand it" -> laden; (2) "I refactored the auth module, update repo-docs to match" -> laden; (3) "Explain the architecture of this codebase to me" -> laden. MOET NIET: (4) "Write a CHANGELOG entry for the v2.1 release" -> overslaan (release notes, geen repo gids); (5) "Add docstrings to every function in src/utils.py" -> overslaan (inline comments). 5/5 correct. Kosten: 4 bestanden proces voor een 132-regelige repo, en de validator wil nog steeds een AGENTS.md geschreven in de root van de doel-repo.

Getest op: 2026-07-31 · Claude Code 2.x (agent harness)

Installatie

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.

Commando's en voorbeeldprompts

/repo-docsBouwt een repo-docs gids vanuit één echt codepad, met een bewijstabel en een validator

Skills reageren op gewone verzoeken — geen commando's om te onthouden. Na installatie activeren prompts zoals deze de skill (in het Engels):

Generate onboarding docs for this repository
Update repo docs after these code changes
Explain this repo's architecture with evidence

Volledig rapport (Engels) →