46 reglas, la mayoría de la documentación oficial de Anthropic y algunas de la práctica, un validador que corre en un segundo y una receta en cinco pasos para encontrar y corregir las skills que más fallan, sin tocar nada que no hayas aprobado.
Auditar Skills es un kit abierto para revisar las skills de tu agente, las carpetas con un archivo SKILL.md que Claude Code y Codex usan para hacer una tarea siempre de la misma manera. Incluye skill-creator-plus, una skill de RoboNuggets que revisa cada skill contra 46 reglas (la mayoría de la documentación oficial de Anthropic, algunas de la práctica), y una receta de INEMA en cinco pasos: correr el validador, tomar las cinco peores, generar un informe, probar con y sin la skill y activar un hook. Sirve para quien ya tiene varias skills y no sabe cuáles están rotas. Solo necesita Python 3.8 o más reciente, y ninguna skill cambia sin tu aprobación.
El skill-creator-plus original, más lo que INEMA agregó para usarlo en el día a día, incluido un validador que entiende skills en portugués y español.
La mayoría viene de la documentación oficial de Anthropic (guía de skills, docs de Claude Code, guía de prompting de Fable 5 y Opus 5.5), con el enlace de cada una; algunas, como las familias NM y LB, vienen de la práctica del autor y están marcadas como consejo. 20 son solo de lectura, juzgadas por el agente.
validate_skill.py en Python puro, sin instalar nada. Revisa la parte mecánica de una skill o de una carpeta entera e indica archivo y línea de cada problema. Solo lee; no modifica nada.
Cinco pasos para no auditar todo de una vez: validador, cinco peores, informe, prueba con y sin, hook. Con dos scripts nuevos: relatorio.py y hook_validar.py.
Primero el validador mide; después el agente lee e informa; tú decides qué aplicar; la prueba lo demuestra; el hook lo sostiene.
Frontmatter que el YAML entiende; nombre y descripción dentro del límite, en tercera persona, diciendo cuándo usarla.
SKILL.md con menos de 500 líneas, referencias a un solo nivel, índice en archivos largos, nada de enlaces rotos ni TODO.
Checklist con "listo cuando" y línea de volver atrás; scripts que resuelven el error; paquetes con su línea de instalación.
Ajustes para los modelos 5.5, regla estricta en hook, pruebas con y sin la skill y una biblioteca sin dos skills peleando por el mismo pedido.
El validador y los scripts usan solo la biblioteca estándar de Python. El agente entra en el informe y en la corrección.
Linux, Mac o Windows. Nada que instalar con pip.
# verificar la versión python3 --version
Para descargar el repositorio (o baja el ZIP desde GitHub).
git --versionSolo para los modos AUDIT, NEW y REFINE de la skill. El validador corre sin agente.
# las skills viven en ~/.claude/skills # Claude Code ~/.agents/skills # Codex
Córrelos en orden. Los pasos 2 y 3 solo leen tus skills; el paso 4 solo edita después de que elijas.
Una carpeta en tu directorio personal. Los siguientes comandos se corren desde adentro.
git clone https://github.com/inematds/auditar-skills ~/auditar-skills cd ~/auditar-skills
Una línea por skill: errores, avisos, notas y las reglas incumplidas. Código de salida 0 = sin errores, 1 = hay errores, 2 = no pudo correr.
python3 skill-creator-plus/scripts/validate_skill.py --all ~/.claude/skills # Claude Code python3 skill-creator-plus/scripts/validate_skill.py --all ~/.agents/skills # Codex
relatorio.py ordena por errores y avisos y detalla las N peores, agrupando los hallazgos por regla. O elige las cinco que más usas.
python3 skill-creator-plus/scripts/validate_skill.py --all ~/.claude/skills --json \ | python3 scripts/relatorio.py - --top 5 > relatorio.md
El modo AUDIT lee la skill completa, marca cada regla (pasa, falla o n/a) con archivo y línea y solo edita lo que apruebes.
cp -r ~/auditar-skills/skill-creator-plus ~/.claude/skills/ # Codex: ~/.agents/skills/ # en Claude Code, en una sesión nueva: "Audita la skill formato-curso-v2 contra las reglas de Anthropic. Solo el informe, no edites nada."
Los modelos 5.5 suelen rendir mejor con menos instrucciones, pero solo una ejecución comparada demuestra que una línea es peso muerto. Arma dos copias y corre la misma tarea en cada una.
mkdir -p /tmp/teste-com/.claude/skills /tmp/teste-sem/.claude/skills cp -r ~/.claude/skills/minha-skill /tmp/teste-com/.claude/skills/ cp -r ~/.claude/skills/minha-skill /tmp/teste-sem/.claude/skills/ # borra las líneas candidatas solo aquí
Es un ejemplo, no viene instalado. Cada vez que el agente guarde un SKILL.md, corre el validador; si hay errores, el agente recibe la lista y los corrige en el momento. Va en ~/.claude/settings.json.
{
"hooks": { "PostToolUse": [ {
"matcher": "Write|Edit",
"hooks": [ { "type": "command",
"command": "python3 ~/auditar-skills/scripts/hook_validar.py",
"timeout": 60 } ]
} ] }
}
Pruébalo antes de activarlo: código 0 = sin errores, 2 = errores listados. Detalles en docs/receita-inema.md (en portugués).
echo '{"tool_input":{"file_path":"'"$HOME"'/.claude/skills/minha-skill/SKILL.md"}}' \ | python3 scripts/hook_validar.py; echo "código de salida: $?"
Corrido sobre copias de cuatro skills de INEMA, en una carpeta temporal, sin tocar las originales. El informe completo está en examples/relatorio-inema.md (en portugués).
Skill Errors Warnings Notes Rules ---------------- ------ -------- ----- ------------ video-ia 16 8 2 ST5 ST6 media-use 13 11 2 ST4 ST5 ST6 SC5 formato-curso-v2 5 0 5 DS1 ST5 clima 0 1 0 DS3
### 3. formato-curso-v2 - DS1 (erro, 1x) - SKILL.md:3 description is 1251 characters; the limit is 1024. - ST5 (erro, 4x) - references/LEARN-LAYER.md is 618 lines with no contents list in its first 50 lines.
Y el propio skill-creator-plus pasa su validador: 0 errores y 1 aviso (la imagen del banner del README no se menciona en el SKILL.md).
El espejo sigue al original; la receta crece con el uso en las skills de INEMA.
skill-creator-plus/, validador adaptado a PT/ES (DS3, ST5 y CT9, con prueba), receta INEMA, relatorio.py, hook_validar.py, guía y README en PT, EN y ES.skill-creator-plus/ se vuelve a copiar y se reaplica el cambio INEMA en el validador.