Repo Docs

Bygger en repo-docs-guide från en verklig kodsökväg, med en bevis tabell och en validator

av YurunChen · YurunChen/repo-docs-skills

Testad · Fungerar ★ 8.8/10

Repo Docs — Bygger en repo-docs-guide från en verklig kodsökväg, med en bevis tabell och en validator

Vad den gör

Genererar och underhåller en Markdown-guide (README, one-real-run walkthrough, kodkarta, moduler, källbevis tabell, ändringslogg) som förklarar ett repository genom ett verkligt beteende istället för en filträdsgenomgång. Utlöses när någon ber att förstå en kodbas, generera eller uppdatera repo-dokumentation, skriva onboarding-material, svara på repo-arkitekturfrågor, eller synkronisera dokumentation efter kodändringar. Levererar en Python-validator som kontrollerar struktur, länkar, bevisetiketter och läsbarhet innan leverans.

Testrapport

Hämtade skills/repo-docs/SKILL.md (frontmatter har name+description); stickprovskontrollerade REFERENCE.md, PAGE_RULES.md, scripts/validate_repo_docs.py, QUALITY_RULES.md och repo-docs-zh/SKILL.md — alla HTTP 200. Verifierade installationsblocket från början till slut under `export HOME=$(mktemp -d)`: SKILL.md hamnar på ~/.claude/skills/repo-docs/SKILL.md med scripts/ och evals/ intakta. Enda säkerhetsanmärkningen: install.sh annonserar `curl -fsSL ... | bash` i sin egen användningstext; inga base64-blobbar, inga injektionssträngar, och validatorns enda subprocess är `git diff --name-only`. Uppgift: dokumentera simonw/json-flatten (132-raders bibliotek, commit 78c2835) för en ny bidragsgivare. Baseline (scratchpad/baseline/DOCUMENTATION.md, en fil) öppnade med en filträd, listade $type-kodningstabellen och implementeringsanteckningar — korrekt men skrivskyddad, och den hävdade implicit round-trip-fidelitet. Färdighetsartefakt (scratchpad/skillrun/repo-docs/: README, walkthroughs/one-real-run.md, references/source-evidence.md, change-log.md) tvingade fram en Pass-2 "falsifying check", vilket fick mig att faktiskt exekvera koden och hitta en verklig defekt som baseline missade och den uppströms README aldrig nämner: `unflatten(flatten({'a.b': 1}))` returnerar `{'a': {'b': 1}}` — prickade nycklar omformar tyst, och inget test täcker det. Det blev README-rubrikvarningen. Färdigheten producerade också en Claim|Evidence|Confidence|Caveat|Used-by-tabell som citerade kommandot eller källraden per rad, plus en förklaring som baseline saknade (varför isinstance(bool) kontrolleras före int, och vad som går sönder om de byts). Den medföljande validatorn är verklig och fungerar: första utkastet gav `FAILED: 2 error(s), 12 warning(s)` (saknar `## Reader Routes`-tabell, låg-scent länk-etiketter), exit 1; efter en redigeringspass, `OK: 0 errors, 6 warning(s)`. Trigger — SKA: (1) "Generate onboarding docs for this repo so a new engineer can understand it" -> ladda; (2) "I refactored the auth module, update repo-docs to match" -> ladda; (3) "Explain the architecture of this codebase to me" -> ladda. SKA INTE: (4) "Write a CHANGELOG entry for the v2.1 release" -> hoppa över (release notes, inte en repo-guide); (5) "Add docstrings to every function in src/utils.py" -> hoppa över (inline-kommentarer). 5/5 korrekt. Kostnad: 4 filer process för ett 132-raders repo, och validatorn vill fortfarande ha en AGENTS.md skriven i målrepots rot.

Testad: 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.

Kommandon och exempelprompter

/repo-docsBygger en repo-docs-guide från en verklig kodsökväg, med en bevis tabell och en validator

Skills triggas av vanliga förfrågningar — inga kommandon att memorera. Efter installationen aktiverar prompter som dessa skillen (på engelska):

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

Läs hela rapporten →