agent-skill-audit

# Auditoría de skills vs su repo fuente Clase de tarea: **verificar que un SKILL.md no mienta sobre el proyecto que documenta /comandos inventados, CDN falsos, función mal descrita, categoría errónea.** Nace del pipeline stars-explorer (que a veces creó skills en lote sin leer el README), pero aplica a CUALQUIER skill cuyo contenido deba corresponder a una fuente real (repo, API, herramienta). Es el paso que David llama "ser agresivo": no solo crear, re-verificar lo creado, periódicamente. ## When to Use - Al re-auditar skills que el pipeline generó desde repos star-eados. - Cuando un skill describe una herramienta y dudas de que los comandos/CLI/CDN sean reales. - Antes de confiar en un skill "herencia" (creado en batch sin leer su README). - Cuando David pide repasar la base de skills por calidad/veracidad. ## Reglas que no se pueden saltar 1. **`category: "upgrade"` en el registry ≠ contenido arreglado.** Marcar "upgrade" significa que el dedup decidió mejorar, no que el SKILL.md esté reescrito a v2. Verificar SIEMPRE la `version` del frontmatter y las afirmaciones concretas. 2. **No editar por editar.** Los root-level no son todos v1 (mastermind, github-workflow, pdf-processing son legítimos sin categoría). El marcador es función-descrita vs real, no la ubicación. 3. **Los children verifican, el orquestador parchea.** Subagentes investigan y devuelven JSON; el padre aplica `skill_manage(patch)` y lo verifica. Nunca asumir el self-report de un child como verdad. 4. **No `git clone`** para auditar un repo pequeño: basta curl de 2-3 ficheros clave del tree (lección 2026-09-04). Un child con repo sin README debe marcar "sin datos", no inventar. ## Método (receta completa en `references/audit-recipe.md`) ### 1. Mapear repo → skill desde el registry Leer `data/stars-registry.json`, subdict `processed`, filtrar `skill_created: true`, resolver `skill_name`/basename contra `agent/skills/**` hasta el `SKILL.md`. Volcar a `C:/Users/d_ant/AppData/Local/Temp/audit_map.json`. ### 2. Identificar candidatos v1 Root-level (sin categoría) = candidatos del maratón. Listar con `ls -d agent/skills/*/ | while read d; do [ -f "$d/SKILL.md" ] && echo "$d"; done`. ### 3. Verificar contra la fuente real `gh api repos/<repo>` / `curl -s https://api.github.com/repos/<repo>` y `/readme`. Comparar función, comandos, CDN, endpoints, stars, categoría librería-vs-app. ### 4. Barrido en paralelo (delegación) Repartir ~4-6 skills por child (leaf), 3 en paralelo. Cada child devuelve `{"auditoria":[{"repo","veredicto":"OK|NEEDS_PATCH","skill_version","discrepancias",...,"stars_reales","lenguaje_real"}]}`. El padre parchea los `NEEDS_PATCH`. ## Pitfalls de entorno (Windows) - **`python -c` con backslashes/rutas Windows en git-bash** → `SyntaxError: unterminated string literal`. Y `python.exe` nativo NO lee `/tmp` (MSYS) → `FileNotFoundError`. Usar `write_file` en `C:/Users/d_ant/AppData/Local/Temp/<>.py` y ejecutarlo con el Python del sistema `C:/Users/d_ant/AppData/Local/Programs/Python/Python312/python.exe`. - **Post-patch siempre**: `python scripts/sincronizar-skills.py` (inst→repo) + `python scripts/indexar-skills.py` (Python del sistema) + commit/push. ## Estado verificado (2026-09-05) Barrido de 12 skills (TTS/OCR/PDF/routing/scraping) en 3 subagentes. `minimaps-js` y `gtfs-to-chart` (los señalados como fabricados) ya estaban a v2 correcto → la incidencia original del maratón quedó cerrada. Ver antagonista del pipeline en el skill `stars-explorer` (user-owned) y sus pitfalls de v1.