Repo Docs

Crea una guida repo-docs da un percorso di codice reale, con una tabella di evidenze e un validatore

di YurunChen · YurunChen/repo-docs-skills

Promosso ★ 8.8/10

Repo Docs — Crea una guida repo-docs da un percorso di codice reale, con una tabella di evidenze e un validatore

Cosa fa

Genera e mantiene una guida Markdown (README, walkthrough one-real-run, mappa del codice, moduli, tabella delle evidenze sorgente, change log) che spiega un repository attraverso un comportamento reale invece di un tour dell'albero dei file. Si attiva quando qualcuno chiede di comprendere una codebase, generare o aggiornare la documentazione del repository, scrivere materiale di onboarding, rispondere a domande sull'architettura del repository o sincronizzare la documentazione dopo modifiche al codice. Fornisce un validatore Python che controlla struttura, link, etichette delle evidenze e 'reader scent' prima della consegna.

Rapporto di test

Recuperato skills/repo-docs/SKILL.md (il frontmatter ha name+description); controllati a campione REFERENCE.md, PAGE_RULES.md, scripts/validate_repo_docs.py, QUALITY_RULES.md e repo-docs-zh/SKILL.md — tutti HTTP 200. Verificato il blocco di installazione end-to-end sotto `export HOME=$(mktemp -d)`: SKILL.md è stato posizionato in ~/.claude/skills/repo-docs/SKILL.md con scripts/ ed evals/ intatti. Unica nota di sicurezza: install.sh pubblicizza `curl -fsSL ... | bash` nel proprio testo di utilizzo; nessun blob base64, nessuna stringa di injection, e l'unico sottoprocesso del validatore è `git diff --name-only`. Task: documentare simonw/json-flatten (libreria di 132 righe, commit 78c2835) per un nuovo collaboratore. La baseline (scratchpad/baseline/DOCUMENTATION.md, un file) si apriva con un albero di file, elencava la tabella di codifica $type e le note di implementazione — accurate ma di sola lettura, e asseriva implicitamente la fedeltà di round-trip. L'artefatto della skill (scratchpad/skillrun/repo-docs/: README, walkthroughs/one-real-run.md, references/source-evidence.md, change-log.md) ha forzato un "controllo di falsificazione" Pass-2, che mi ha fatto effettivamente eseguire il codice e trovare un difetto reale che la baseline aveva perso e il README a monte non menziona mai: `unflatten(flatten({'a.b': 1}))` restituisce `{'a': {'b': 1}}` — le chiavi puntate si rimodellano silenziosamente, e nessun test lo copre. Questo è diventato l'avvertenza principale del README. La skill ha anche prodotto una tabella Claim|Evidence|Confidence|Caveat|Used-by che citava il comando o la riga sorgente per riga, più una spiegazione che la baseline non aveva (perché isinstance(bool) viene controllato prima di int, e cosa si rompe se scambiato). Il validatore incluso è reale e funziona: la prima bozza ha dato `FAILED: 2 error(s), 12 warning(s)` (tabella `## Reader Routes` mancante, etichette di link a basso 'scent'), exit 1; dopo un passaggio di modifica, `OK: 0 errors, 6 warning(s)`. Trigger — DOVREBBE: (1) "Generate onboarding docs for this repo so a new engineer can understand it" -> carica; (2) "I refactored the auth module, update repo-docs to match" -> carica; (3) "Explain the architecture of this codebase to me" -> carica. NON DOVREBBE: (4) "Write a CHANGELOG entry for the v2.1 release" -> salta (note di rilascio, non una guida al repository); (5) "Add docstrings to every function in src/utils.py" -> salta (commenti inline). 5/5 corretto. Costo: 4 file di processo per un repository di 132 righe, e il validatore vuole ancora un AGENTS.md scritto nella root del repository target.

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

Installazione

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.

Comandi e prompt di esempio

/repo-docsCrea una guida repo-docs da un percorso di codice reale, con una tabella di evidenze e un validatore

Gli skill si attivano con richieste in linguaggio naturale, senza comandi da ricordare. Dopo l'installazione, prompt come questi lo attivano (in inglese):

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

Rapporto completo →