Repo Docs

Opbygger en repo-docs guide fra én reel kodevej, med en evidens-tabel og en validator

Af YurunChen · YurunChen/repo-docs-skills

Testet · Virker ★ 8.8/10

Repo Docs — Opbygger en repo-docs guide fra én reel kodevej, med en evidens-tabel og en validator

Hvad det gør

Genererer og vedligeholder en Markdown-guide (README, one-real-run walkthrough, kodekort, moduler, kilde-evidens-tabel, ændringslog), der forklarer et repository gennem én reel adfærd i stedet for en filtræ-gennemgang. Udløses, når nogen beder om at forstå en kodebase, generere eller opdatere repo-docs, skrive onboarding-materiale, besvare repo-arkitekturspørgsmål eller synkronisere docs efter kodeændringer. Leverer en Python-validator, der kontrollerer struktur, links, evidensetiketter og læser-duft før levering.

Testrapport

Hentede skills/repo-docs/SKILL.md (frontmatter har name+description); spot-tjekkede REFERENCE.md, PAGE_RULES.md, scripts/validate_repo_docs.py, QUALITY_RULES.md og repo-docs-zh/SKILL.md — alle HTTP 200. Verificerede installationsblokken ende-til-ende under `export HOME=$(mktemp -d)`: SKILL.md lander på ~/.claude/skills/repo-docs/SKILL.md med scripts/ og evals/ intakt. Eneste sikkerhedsbemærkning: install.sh annoncerer `curl -fsSL ... | bash` i sin egen brugstekst; ingen base64 blobs, ingen injektionsstrenge, og validatorens eneste subprocess er `git diff --name-only`. Opgave: dokumenter simonw/json-flatten (132-linjers bibliotek, commit 78c2835) for en ny bidragyder. Baseline (scratchpad/baseline/DOCUMENTATION.md, én fil) åbnede med et filtræ, listede $type-kodningstabellen og implementeringsnoter — nøjagtig, men skrivebeskyttet, og den hævdede implicit round-trip fidelity. Færdighedsartefakt (scratchpad/skillrun/repo-docs/: README, walkthroughs/one-real-run.md, references/source-evidence.md, change-log.md) tvang en Pass-2 "falsifying check", som fik mig til faktisk at udføre koden og finde en reel defekt, baselinen missede, og den upstream README aldrig nævner: `unflatten(flatten({'a.b': 1}))` returnerer `{'a': {'b': 1}}` — prikkede nøgler omformer sig lydløst, og ingen test dækker det. Det blev README's overskriftsadvarsel. Færdigheden producerede også en Claim|Evidence|Confidence|Caveat|Used-by-tabel, der citerede kommandoen eller kildelinjen pr. række, plus en forklaring, baselinen manglede (hvorfor isinstance(bool) kontrolleres før int, og hvad der går i stykker, hvis det byttes om). Den medfølgende validator er reel og fungerer: første udkast gav `FAILED: 2 error(s), 12 warning(s)` (mangler `## Reader Routes`-tabel, lav-scent linketiketter), exit 1; efter én redigeringsrunde, `OK: 0 errors, 6 warning(s)`. Udløser — SKULLE: (1) "Generate onboarding docs for this repo so a new engineer can understand it" -> indlæs; (2) "I refactored the auth module, update repo-docs to match" -> indlæs; (3) "Explain the architecture of this codebase to me" -> indlæs. SKULLE IKKE: (4) "Write a CHANGELOG entry for the v2.1 release" -> spring over (release notes, ikke en repo-guide); (5) "Add docstrings to every function in src/utils.py" -> spring over (inline comments). 5/5 korrekt. Omkostning: 4 filer proces for et 132-linjers repo, og validatoren ønsker stadig en AGENTS.md skrevet ind i mål-repo-roden.

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

Installation

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.

Kommandoer og eksempelprompter

/repo-docsOpbygger en repo-docs guide fra én reel kodevej, med en evidens-tabel og en validator

Skills udløses af almindelige forespørgsler — ingen kommandoer at huske. Efter installationen aktiverer prompter som disse skillen (på engelsk):

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

Læs hele rapporten →