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 .
skill-auditor ~/.hermes/skills
skill-auditor ~/.hermes/skills --report md
skill-auditor ~/.hermes/skills --report json
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