Repo Docs

Tworzy przewodnik repo-docs z jednej rzeczywistej ścieżki kodu, z tabelą dowodów i walidatorem

Autor: YurunChen · YurunChen/repo-docs-skills

Testowano · Działa ★ 8.8/10

Repo Docs — Tworzy przewodnik repo-docs z jednej rzeczywistej ścieżki kodu, z tabelą dowodów i walidatorem

Co robi ten skill

Generuje i utrzymuje przewodnik Markdown (README, instruktaż one-real-run, mapa kodu, moduły, tabela dowodów źródłowych, dziennik zmian), który wyjaśnia repozytorium poprzez jedno rzeczywiste zachowanie zamiast przeglądu drzewa plików. Uruchamia się, gdy ktoś prosi o zrozumienie bazy kodu, generowanie lub aktualizowanie dokumentacji repozytorium, pisanie materiałów wdrożeniowych, odpowiadanie na pytania dotyczące architektury repozytorium lub synchronizowanie dokumentacji po zmianach kodu. Dostarcza walidator Pythona, który sprawdza strukturę, linki, etykiety dowodów i czytelność przed dostarczeniem.

Raport z testu

Pobrano skills/repo-docs/SKILL.md (frontmatter zawiera name+description); sprawdzono REFERENCE.md, PAGE_RULES.md, scripts/validate_repo_docs.py, QUALITY_RULES.md i repo-docs-zh/SKILL.md — wszystkie HTTP 200. Zweryfikowano blok instalacyjny od początku do końca pod `export HOME=$(mktemp -d)`: SKILL.md ląduje w ~/.claude/skills/repo-docs/SKILL.md z nienaruszonymi scripts/ i evals/. Jedyna uwaga dotycząca bezpieczeństwa: install.sh reklamuje `curl -fsSL ... | bash` w swoim własnym tekście użycia; brak blobów base64, brak ciągów wstrzykujących, a jedynym podprocesem walidatora jest `git diff --name-only`. Zadanie: udokumentować simonw/json-flatten (biblioteka 132 linii, commit 78c2835) dla nowego współpracownika. Linia bazowa (scratchpad/baseline/DOCUMENTATION.md, jeden plik) rozpoczęła się od drzewa plików, wymieniła tabelę kodowania $type i uwagi implementacyjne — dokładne, ale tylko do odczytu, i niejawnie potwierdzała wierność w obie strony. Artefakt umiejętności (scratchpad/skillrun/repo-docs/: README, walkthroughs/one-real-run.md, references/source-evidence.md, change-log.md) wymusił Pass-2 "falsifying check", co sprawiło, że faktycznie wykonałem kod i znalazłem prawdziwą wadę, którą linia bazowa pominęła, a README upstream nigdy nie wspomina: `unflatten(flatten({'a.b': 1}))` zwraca `{'a': {'b': 1}}` — klucze z kropkami cicho zmieniają kształt, a żaden test tego nie obejmuje. To stało się głównym zastrzeżeniem w README. Umiejętność wygenerowała również tabelę Claim|Evidence|Confidence|Caveat|Used-by, cytującą polecenie lub linię źródłową dla każdego wiersza, plus wyjaśnienie, którego brakowało w linii bazowej (dlaczego isinstance(bool) jest sprawdzane przed int, i co się psuje, jeśli zostanie zamienione). Dołączony walidator jest prawdziwy i działa: pierwszy szkic dał `FAILED: 2 error(s), 12 warning(s)` (brak tabeli `## Reader Routes`, mało sugestywne etykiety linków), exit 1; po jednej poprawce, `OK: 0 errors, 6 warning(s)`. Wyzwalacz — POWINIEN: (1) "Generate onboarding docs for this repo so a new engineer can understand it" -> załadować; (2) "I refactored the auth module, update repo-docs to match" -> załadować; (3) "Explain the architecture of this codebase to me" -> załadować. NIE POWINIEN: (4) "Write a CHANGELOG entry for the v2.1 release" -> pominąć (release notes, nie przewodnik po repozytorium); (5) "Add docstrings to every function in src/utils.py" -> pominąć (komentarze w kodzie). 5/5 poprawnie. Koszt: 4 pliki procesu dla repozytorium 132-liniowego, a walidator nadal chce, aby AGENTS.md został zapisany w docelowym katalogu głównym repozytorium.

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

Instalacja

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.

Komendy i przykładowe prompty

/repo-docsTworzy przewodnik repo-docs z jednej rzeczywistej ścieżki kodu, z tabelą dowodów i walidatorem

Skille uruchamiają się na zwykłe polecenia — bez komend do zapamiętania. Po instalacji aktywują go prompty takie jak te (po angielsku):

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

Pełny raport →