Repo Docs

Erstellt einen repo-docs-Leitfaden aus einem echten Codepfad, mit einer Evidenztabelle und einem Validator

von YurunChen · YurunChen/repo-docs-skills

Getestet · Funktioniert ★ 8.8/10

Repo Docs — Erstellt einen repo-docs-Leitfaden aus einem echten Codepfad, mit einer Evidenztabelle und einem Validator

Was es kann

Generiert und pflegt einen Markdown-Leitfaden (README, one-real-run Walkthrough, Code-Map, Module, Quell-Evidenztabelle, Änderungslog), der ein Repository durch ein echtes Verhalten anstelle einer Dateibaum-Tour erklärt. Wird ausgelöst, wenn jemand fragt, wie eine Codebasis zu verstehen ist, Repo-Dokumente generiert oder aktualisiert werden sollen, Onboarding-Material geschrieben werden soll, Repo-Architekturfragen beantwortet werden sollen oder Dokumente nach Codeänderungen synchronisiert werden sollen. Liefert einen Python-Validator, der Struktur, Links, Evidenzlabels und Lesbarkeit vor der Auslieferung überprüft.

Testbericht

skills/repo-docs/SKILL.md abgerufen (Frontmatter hat name+description); stichprobenartig REFERENCE.md, PAGE_RULES.md, scripts/validate_repo_docs.py, QUALITY_RULES.md und repo-docs-zh/SKILL.md überprüft – alle HTTP 200. Den Installationsblock unter `export HOME=$(mktemp -d)` vollständig verifiziert: SKILL.md landet unter ~/.claude/skills/repo-docs/SKILL.md mit intakten scripts/ und evals/. Einziger Sicherheitshinweis: install.sh bewirbt `curl -fsSL ... | bash` in seinem eigenen Nutzungstext; keine base64-Blobs, keine Injektionsstrings, und der einzige Subprozess des Validators ist `git diff --name-only`. Aufgabe: simonw/json-flatten (132-Zeilen-Bibliothek, Commit 78c2835) für einen neuen Mitwirkenden dokumentieren. Baseline (scratchpad/baseline/DOCUMENTATION.md, eine Datei) begann mit einem Dateibaum, listete die $type-Kodierungstabelle und Implementierungshinweise auf – genau, aber schreibgeschützt, und sie behauptete implizit eine Round-Trip-Fidelity. Skill-Artefakt (scratchpad/skillrun/repo-docs/: README, walkthroughs/one-real-run.md, references/source-evidence.md, change-log.md) erzwang einen Pass-2 "falsifying check", der mich dazu brachte, den Code tatsächlich auszuführen und einen echten Defekt zu finden, den die Baseline übersehen hatte und die Upstream-README nie erwähnt: `unflatten(flatten({'a.b': 1}))` gibt `{'a': {'b': 1}}` zurück – gepunktete Schlüssel formen sich stillschweigend um, und kein Test deckt dies ab. Das wurde zum README-Schlagzeilen-Vorbehalt. Der Skill erzeugte auch eine Claim|Evidence|Confidence|Caveat|Used-by-Tabelle, die den Befehl oder die Quellzeile pro Zeile zitierte, plus eine Erklärung, die der Baseline fehlte (warum isinstance(bool) vor int geprüft wird und was bricht, wenn vertauscht). Der gebündelte Validator ist echt und funktioniert: Der erste Entwurf ergab `FAILED: 2 error(s), 12 warning(s)` (fehlende `## Reader Routes`-Tabelle, wenig aussagekräftige Link-Labels), Exit 1; nach einem Bearbeitungsdurchlauf `OK: 0 errors, 6 warning(s)`. Auslöser – SOLLTE: (1) "Generate onboarding docs for this repo so a new engineer can understand it" -> laden; (2) "I refactored the auth module, update repo-docs to match" -> laden; (3) "Explain the architecture of this codebase to me" -> laden. SOLLTE NICHT: (4) "Write a CHANGELOG entry for the v2.1 release" -> überspringen (Release Notes, kein Repo-Leitfaden); (5) "Add docstrings to every function in src/utils.py" -> überspringen (Inline-Kommentare). 5/5 korrekt. Kosten: 4 Prozessdateien für ein 132-Zeilen-Repo, und der Validator möchte immer noch eine AGENTS.md im Ziel-Repo-Root geschrieben haben.

Getestet am: 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.

Befehle & Beispiel-Prompts

/repo-docsErstellt einen repo-docs-Leitfaden aus einem echten Codepfad, mit einer Evidenztabelle und einem Validator

Skills reagieren auf normale Anfragen — keine Slash-Befehle nötig. Nach der Installation aktivieren Prompts wie diese den Skill (auf Englisch):

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

Vollständiger Testbericht (Englisch) →