Repo Docs

Construit un guide repo-docs à partir d'un chemin de code réel, avec une table de preuves et un validateur

par YurunChen · YurunChen/repo-docs-skills

Testé · Fonctionne ★ 8.8/10

Repo Docs — Construit un guide repo-docs à partir d'un chemin de code réel, avec une table de preuves et un validateur

Ce que fait

Génère et maintient un guide Markdown (README, walkthrough d'une exécution réelle, carte de code, modules, table de preuves source, journal des modifications) qui explique un dépôt à travers un comportement réel plutôt qu'une visite de l'arborescence des fichiers. Se déclenche lorsque quelqu'un demande de comprendre une base de code, de générer ou de mettre à jour la documentation du dépôt, d'écrire du matériel d'intégration, de répondre à des questions d'architecture de dépôt ou de synchroniser la documentation après des modifications de code. Fournit un validateur Python qui vérifie la structure, les liens, les étiquettes de preuves et l'attrait pour le lecteur avant la livraison.

Rapport de test

Récupéré skills/repo-docs/SKILL.md (le frontmatter contient name+description) ; vérifié ponctuellement REFERENCE.md, PAGE_RULES.md, scripts/validate_repo_docs.py, QUALITY_RULES.md et repo-docs-zh/SKILL.md — tous HTTP 200. Vérifié le bloc d'installation de bout en bout sous `export HOME=$(mktemp -d)` : SKILL.md atterrit dans ~/.claude/skills/repo-docs/SKILL.md avec scripts/ et evals/ intacts. Seule note de sécurité : install.sh annonce `curl -fsSL ... | bash` dans son propre texte d'utilisation ; pas de blobs base64, pas de chaînes d'injection, et le seul sous-processus du validateur est `git diff --name-only`. Tâche : documenter simonw/json-flatten (bibliothèque de 132 lignes, commit 78c2835) pour un nouveau contributeur. La base de référence (scratchpad/baseline/DOCUMENTATION.md, un fichier) s'est ouverte avec une arborescence de fichiers, a listé la table d'encodage $type et les notes d'implémentation — précis mais en lecture seule, et elle affirmait implicitement la fidélité aller-retour. L'artefact de compétence (scratchpad/skillrun/repo-docs/: README, walkthroughs/one-real-run.md, references/source-evidence.md, change-log.md) a forcé une "vérification falsifiante" de Pass-2, ce qui m'a fait réellement exécuter le code et trouver un défaut réel que la base de référence avait manqué et que le README en amont ne mentionne jamais : `unflatten(flatten({'a.b': 1}))` renvoie `{'a': {'b': 1}}` — les clés pointillées remodèlent silencieusement, et aucun test ne le couvre. Cela est devenu la mise en garde principale du README. La compétence a également produit une table Claim|Evidence|Confidence|Caveat|Used-by citant la commande ou la ligne source par ligne, plus une explication que la base de référence n'avait pas (pourquoi isinstance(bool) est vérifié avant int, et ce qui se casse si échangé). Le validateur fourni est réel et fonctionne : le premier brouillon a donné `FAILED: 2 error(s), 12 warning(s)` (table `## Reader Routes` manquante, étiquettes de liens peu claires), exit 1 ; après un passage d'édition, `OK: 0 errors, 6 warning(s)`. Déclencheur — DEVRAIT : (1) "Generate onboarding docs for this repo so a new engineer can understand it" -> charger ; (2) "I refactored the auth module, update repo-docs to match" -> charger ; (3) "Explain the architecture of this codebase to me" -> charger. NE DEVRAIT PAS : (4) "Write a CHANGELOG entry for the v2.1 release" -> sauter (notes de version, pas un guide de dépôt) ; (5) "Add docstrings to every function in src/utils.py" -> sauter (commentaires en ligne). 5/5 correct. Coût : 4 fichiers de processus pour un dépôt de 132 lignes, et le validateur veut toujours un AGENTS.md écrit à la racine du dépôt cible.

Testé le: 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.

Commandes et exemples de prompts

/repo-docsConstruit un guide repo-docs à partir d'un chemin de code réel, avec une table de preuves et un validateur

Les skills se déclenchent sur des demandes en langage courant — aucune commande à retenir. Après installation, des prompts comme ceux-ci l'activent (en anglais) :

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

Rapport complet →