# Agent Skill Audit

> Usa al auditar que los skills describan bien su repo fuente.

- Skill: `ntizar/agent-skill-audit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ntizar/agent-skill-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ntizar/agent-skill-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: ntizar (https://skillmd.com/u/ntizar)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ntizar/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.