Repo Docs

Bygger en repo-docs-guide fra én reell kodesti, med en bevis-tabell og en validator

av YurunChen · YurunChen/repo-docs-skills

Bestått ★ 8.8/10

Repo Docs — Bygger en repo-docs-guide fra én reell kodesti, med en bevis-tabell og en validator

Hva den gjør

Genererer og vedlikeholder en Markdown-guide (README, one-real-run gjennomgang, kodekart, moduler, kilde-bevis-tabell, endringslogg) som forklarer et repository gjennom én reell oppførsel i stedet for en filtre-tur. Utløses når noen ber om å forstå en kodebase, generere eller oppdatere repo-dokumentasjon, skrive onboarding-materiale, svare på repo-arkitekturspørsmål, eller synkronisere dokumentasjon etter kodeendringer. Leverer en Python-validator som sjekker struktur, lenker, bevisetiketter og leser-spor før levering.

Testrapport

Hentet skills/repo-docs/SKILL.md (frontmatter har name+description); stikkprøvekontrollerte REFERENCE.md, PAGE_RULES.md, scripts/validate_repo_docs.py, QUALITY_RULES.md og repo-docs-zh/SKILL.md — alle HTTP 200. Verifiserte installasjonsblokken ende-til-ende under `export HOME=$(mktemp -d)`: SKILL.md lander på ~/.claude/skills/repo-docs/SKILL.md med scripts/ og evals/ intakt. Eneste sikkerhetsmerknad: install.sh annonserer `curl -fsSL ... | bash` i sin egen brukstekst; ingen base64-blobs, ingen injeksjonsstrenger, og validatorens eneste subprosess er `git diff --name-only`. Oppgave: dokumentere simonw/json-flatten (132-linjers bibliotek, commit 78c2835) for en ny bidragsyter. Grunnlinjen (scratchpad/baseline/DOCUMENTATION.md, én fil) åpnet med et filtre, listet $type-kodingstabellen og implementeringsnotater — nøyaktig, men skrivebeskyttet, og den hevdet implisitt rundtur-trofasthet. Ferdighetsartefakten (scratchpad/skillrun/repo-docs/: README, walkthroughs/one-real-run.md, references/source-evidence.md, change-log.md) tvang en Pass-2 "falsifiserende sjekk", som fikk meg til å faktisk utføre koden og finne en reell defekt grunnlinjen savnet og den oppstrøms README aldri nevner: `unflatten(flatten({'a.b': 1}))` returnerer `{'a': {'b': 1}}` — prikkede nøkler omformer seg stille, og ingen test dekker det. Det ble README-overskriftens forbehold. Ferdigheten produserte også en Claim|Evidence|Confidence|Caveat|Used-by-tabell som siterer kommandoen eller kildelinjen per rad, pluss en forklaring grunnlinjen manglet (hvorfor isinstance(bool) sjekkes før int, og hva som bryter hvis de byttes). Den medfølgende validatoren er reell og fungerer: første utkast ga `FAILED: 2 error(s), 12 warning(s)` (manglende `## Reader Routes`-tabell, lav-scent lenkeetiketter), exit 1; etter én redigeringsrunde, `OK: 0 errors, 6 warning(s)`. Utløser — SKULLE: (1) "Generate onboarding docs for this repo so a new engineer can understand it" -> last; (2) "I refactored the auth module, update repo-docs to match" -> last; (3) "Explain the architecture of this codebase to me" -> last. SKULLE IKKE: (4) "Write a CHANGELOG entry for the v2.1 release" -> hopp over (release notes, ikke en repo-guide); (5) "Add docstrings to every function in src/utils.py" -> hopp over (inline comments). 5/5 korrekt. Kostnad: 4 filer med prosess for et 132-linjers repo, og validatoren ønsker fortsatt en AGENTS.md skrevet inn i mål-repoets rot.

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

Installer

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-docsBygger en repo-docs-guide fra én reell kodesti, med en bevis-tabell og en validator

Skills utløses av vanlige forespørsler — ingen kommandoer å huske. Etter installasjonen 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

Full rapport →