# skill-auditor v0.1.0: auditar colecciones de skills de agentes IA por integridad y secretos

> Source: <https://dev.to/magopredator/skill-auditor-v010-auditar-colecciones-de-skills-de-agentes-ia-por-integridad-y-secretos-3m47>
> Published: 2026-07-14 02:24:23+00:00

Una CLI agent-agnostic (Hermes primero) que escanea skills por integridad estructural, referencias rotas y secretos hardcodeados, y clasifica cada skill en lenguaje claro. 95% de cobertura de tests, CI verde.

Las colecciones de skills de un agente IA crecen sin revisión: 100–200+ entradas en Hermes, Claude Code, OpenCode o Codex. La superficie de prompts del agente es, en la práctica, código ejecutable que carga comandos y (en skills de seguridad) maneja guía sobre credenciales. Nadie la audita.

En una colección real de 200 skills de Hermes, una auditoría directa al filesystem encontró:

`software-development/software-development/software-development/`

) que causaba una colisión de nombre activa en runtime y arrastraba un bug de doble escapado;`anti-evasión`

vs `anti-evasion`

);`references`

que nunca se entregaron.El hygiene de secretos estaba limpio (solo placeholders de documentación), pero "limpio porque lo miré una vez" no es un proceso. `skill-auditor`

lo vuelve repetible.

Audita cualquier directorio de skills (Hermes es el target primario; es agent-agnostic vía `name`

/`description`

en frontmatter YAML):

| Chequeo | Hallazgo | Notas |
|---|---|---|
| Frontmatter YAML parseable | `FRONTMATTER_ERROR` |
multilínea `\ |
{% raw %}`name` presente |
`NAME_MISSING` |
|
`description` presente y ≥15 chars |
`DESC_EMPTY` / `DESC_SHORT`
|
|
`name` duplicado |
`NAME_DUPLICADO` |
|
Carpeta anidada `X/X/X`
|
`NESTED_DUPLICATE` |
solo la copia innermost es eliminable |
Referencias `scripts/` `references/` rotas |
`REF_ROTA` |
ignora `/tmp` , `/opt` , placeholders |
| Secretos hardcodeados | `SECRET` |
AWS/GH/OpenAI/Anthropic/Google/Slack/GitLab, claves privadas, asignaciones; filtra placeholders |

Cada skill recibe una **clasificación en lenguaje claro**: categoría (carpeta superior), propósito de una línea, y estado `OK`

/ `WARNING`

/ `BROKEN`

.

Reportes en `terminal`

(por defecto), `md`

(una sección por skill) y `json`

(para CI gates).

`--fix`

(opt-in, solo seguro)
Imprime el diff primero y aplica solo correcciones demostrablemente seguras y reversibles:

Nunca edita valores de secreto, nunca reescribe la prosa del skill, nunca borra la única copia de un skill. Si hay un hallazgo `SECRET`

sobre un archivo, ningún fix lo toca.

`SKILL.md`

, determinista y ordenado.`pyyaml.safe_load`

con fallback regex conservador si pyyaml no está. Los bloques multilínea se preservan como texto real (un parser regex ingenuo los lee como descripción de 1 char — esa fue la clase de falso positivo exacta de un script ad-hoc previo, y es el test de regresión).`name`

y auto-anidado `X/X/.../X`

con run-length ≥ 3 (solo el innermost es la copia eliminable).El proyecto se construyó por SDD (Spec-Driven Development) con criterios de aceptación Pass/Fail:

`--cov-fail-under=85`

).`All checks passed!`

).`FRONTMATTER_ERROR`

, `REF_ROTA`

, secreto real (placeholder ignorado), `NAME_DUPLICADO`

, `NESTED_DUPLICATE`

; `--fix`

elimina solo la carpeta inner y deja la outer intacta; re-audit baja de 9 a 8 skills sin nested.`push`

/`PR`

→ checkout → setup-python 3.11 → install → ruff → pytest con cov≥85 → smoke del CLI. Run real: `success`

.Todas las métricas son salida cruda de `pytest --cov`

y del log de CI, no resumen.

```
pip install -e .
# auditoría read-only
skill-auditor ~/.hermes/skills
# reporte markdown
skill-auditor ~/.hermes/skills --report md
# JSON para CI
skill-auditor ~/.hermes/skills --report json
# correcciones seguras (muestra diff, luego aplica)
skill-auditor ~/.hermes/skills --fix
```

Python 3.11+, `pyyaml`

(única dependencia de runtime), `argparse`

, `pytest`

, `ruff`

. Licencia AGPL-3.0-or-later.

*Licencia: AGPL-3.0-or-later © 2026 Pedro Sordo Martínez — amurlaniakea@gmail.com*