Repo Docs

Vytváří průvodce repo-docs z jedné skutečné cesty kódu, s tabulkou důkazů a validátorem

od YurunChen · YurunChen/repo-docs-skills

Otestováno · Funguje ★ 8.8/10

Repo Docs — Vytváří průvodce repo-docs z jedné skutečné cesty kódu, s tabulkou důkazů a validátorem

Co umí

Generuje a udržuje Markdown průvodce (README, one-real-run walkthrough, code map, modules, source-evidence table, change log), který vysvětluje repozitář prostřednictvím jednoho skutečného chování namísto prohlídky stromu souborů. Spouští se, když někdo požádá o pochopení codebase, generování nebo aktualizaci repo docs, psaní onboarding materiálů, zodpovězení otázek architektury repozitáře nebo synchronizaci dokumentace po změnách kódu. Dodává Python validátor, který kontroluje strukturu, odkazy, štítky důkazů a čtenářskou přitažlivost před doručením.

Testovací report

Načteno skills/repo-docs/SKILL.md (frontmatter má name+description); namátkově zkontrolováno REFERENCE.md, PAGE_RULES.md, scripts/validate_repo_docs.py, QUALITY_RULES.md a repo-docs-zh/SKILL.md — všechny HTTP 200. Ověřen instalační blok od začátku do konce pod `export HOME=$(mktemp -d)`: SKILL.md se umístil na ~/.claude/skills/repo-docs/SKILL.md s neporušenými scripts/ a evals/. Jediná bezpečnostní poznámka: install.sh inzeruje `curl -fsSL ... | bash` ve svém vlastním textu použití; žádné base64 bloby, žádné injekční řetězce a jediný podproces validátoru je `git diff --name-only`. Úkol: dokumentovat simonw/json-flatten (132řádková knihovna, commit 78c2835) pro nového přispěvatele. Baseline (scratchpad/baseline/DOCUMENTATION.md, jeden soubor) se otevřel se stromem souborů, vypsal tabulku kódování $type a poznámky k implementaci — přesné, ale pouze pro čtení, a implicitně tvrdil věrnost obousměrného převodu. Artefakt dovednosti (scratchpad/skillrun/repo-docs/: README, walkthroughs/one-real-run.md, references/source-evidence.md, change-log.md) vynutil Pass-2 "falsifikující kontrolu", která mě donutila skutečně spustit kód a najít skutečnou vadu, kterou baseline minul a upstream README nikdy nezmiňuje: `unflatten(flatten({'a.b': 1}))` vrací `{'a': {'b': 1}}` — tečkované klíče tiše mění tvar a žádný test to nepokrývá. To se stalo hlavním upozorněním v README. Dovednost také vytvořila tabulku Claim|Evidence|Confidence|Caveat|Used-by citující příkaz nebo zdrojový řádek na řádek, plus vysvětlení, které baseline postrádal (proč se isinstance(bool) kontroluje před int, a co se rozbije, pokud se prohodí). Přiložený validátor je skutečný a funguje: první návrh dal `FAILED: 2 error(s), 12 warning(s)` (chybí tabulka `## Reader Routes`, málo přitažlivé popisky odkazů), exit 1; po jedné úpravě `OK: 0 errors, 6 warning(s)`. Spouštění — MĚLO by: (1) "Generate onboarding docs for this repo so a new engineer can understand it" -> načíst; (2) "I refactored the auth module, update repo-docs to match" -> načíst; (3) "Explain the architecture of this codebase to me" -> načíst. NEMĚLO by: (4) "Write a CHANGELOG entry for the v2.1 release" -> přeskočit (poznámky k vydání, nikoli průvodce repozitářem); (5) "Add docstrings to every function in src/utils.py" -> přeskočit (inline komentáře). 5/5 správně. Cena: 4 soubory procesu pro 132řádkový repozitář, a validátor stále chce, aby byl AGENTS.md zapsán do kořenového adresáře cílového repozitáře.

Testováno: 2026-07-31 · Claude Code 2.x (agent harness)

Instalace

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.

Příkazy a ukázkové prompty

/repo-docsVytváří průvodce repo-docs z jedné skutečné cesty kódu, s tabulkou důkazů a validátorem

Skilly se spouštějí běžnými požadavky — žádné příkazy k zapamatování. Po instalaci ho aktivují prompty jako tyto (anglicky):

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

Kompletní testovací report (anglicky) →