Repo Docs

Crea una guía repo-docs a partir de una ruta de código real, con una tabla de evidencia y un validador

Por YurunChen · YurunChen/repo-docs-skills

Probado · Funciona ★ 8.8/10

Repo Docs — Crea una guía repo-docs a partir de una ruta de código real, con una tabla de evidencia y un validador

Qué hace

Genera y mantiene una guía Markdown (README, tutorial de una ejecución real, mapa de código, módulos, tabla de evidencia de origen, registro de cambios) que explica un repositorio a través de un comportamiento real en lugar de un recorrido por el árbol de archivos. Se activa cuando alguien pide comprender una base de código, generar o actualizar la documentación del repositorio, escribir material de incorporación, responder preguntas de arquitectura del repositorio o sincronizar la documentación después de cambios en el código. Incluye un validador de Python que verifica la estructura, los enlaces, las etiquetas de evidencia y la "reader scent" antes de la entrega.

Informe de la prueba

Obtuve skills/repo-docs/SKILL.md (el frontmatter tiene name+description); revisé REFERENCE.md, PAGE_RULES.md, scripts/validate_repo_docs.py, QUALITY_RULES.md y repo-docs-zh/SKILL.md — todos HTTP 200. Verifiqué el bloque de instalación de principio a fin bajo `export HOME=$(mktemp -d)`: SKILL.md aterriza en ~/.claude/skills/repo-docs/SKILL.md con scripts/ y evals/ intactos. Única nota de seguridad: install.sh anuncia `curl -fsSL ... | bash` en su propio texto de uso; sin blobs base64, sin cadenas de inyección, y el único subproceso del validador es `git diff --name-only`. Tarea: documentar simonw/json-flatten (biblioteca de 132 líneas, commit 78c2835) para un nuevo colaborador. La línea base (scratchpad/baseline/DOCUMENTATION.md, un archivo) se abrió con un árbol de archivos, listó la tabla de codificación $type y notas de implementación — precisas pero de solo lectura, e implícitamente afirmó la fidelidad de ida y vuelta. El artefacto de la habilidad (scratchpad/skillrun/repo-docs/: README, walkthroughs/one-real-run.md, references/source-evidence.md, change-log.md) forzó una "verificación de falsificación" de Pass-2, lo que me hizo ejecutar el código y encontrar un defecto real que la línea base omitió y el README upstream nunca menciona: `unflatten(flatten({'a.b': 1}))` devuelve `{'a': {'b': 1}}` — las claves con puntos se reforman silenciosamente, y ninguna prueba lo cubre. Eso se convirtió en la advertencia principal del README. La habilidad también produjo una tabla Claim|Evidence|Confidence|Caveat|Used-by citando el comando o la línea de origen por fila, además de una explicación que la línea base carecía (por qué se verifica isinstance(bool) antes de int, y qué se rompe si se intercambia). El validador incluido es real y funciona: el primer borrador dio `FAILED: 2 error(s), 12 warning(s)` (falta la tabla `## Reader Routes`, etiquetas de enlace de bajo "scent"), exit 1; después de una pasada de edición, `OK: 0 errors, 6 warning(s)`. Activación — DEBERÍA: (1) "Generate onboarding docs for this repo so a new engineer can understand it" -> carga; (2) "I refactored the auth module, update repo-docs to match" -> carga; (3) "Explain the architecture of this codebase to me" -> carga. NO DEBERÍA: (4) "Write a CHANGELOG entry for the v2.1 release" -> salta (notas de lanzamiento, no una guía de repositorio); (5) "Add docstrings to every function in src/utils.py" -> salta (comentarios en línea). 5/5 correcto. Costo: 4 archivos de proceso para un repositorio de 132 líneas, y el validador todavía quiere un AGENTS.md escrito en la raíz del repositorio de destino.

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

Instalación

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.

Comandos y prompts de ejemplo

/repo-docsCrea una guía repo-docs a partir de una ruta de código real, con una tabla de evidencia y un validador

Los skills se activan con peticiones en lenguaje natural, sin comandos que memorizar. Tras instalarlo, prompts como estos lo activan (en inglés):

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

Informe completo →