46 regras, a maioria da documentação oficial da Anthropic e algumas da prática, um validador que roda em um segundo e uma receita em cinco passos para achar e corrigir as skills que mais falham, sem mexer em nada que você não aprovou.
Auditar Skills é um kit aberto para conferir as skills do seu agente, as pastas com um arquivo SKILL.md que o Claude Code e o Codex usam para fazer uma tarefa sempre do mesmo jeito. Ele traz o skill-creator-plus, uma skill da RoboNuggets que confere cada skill contra 46 regras (a maioria da documentação oficial da Anthropic, algumas da prática), e uma receita do INEMA em cinco passos: rodar o validador, pegar as cinco piores, gerar um relatório, testar com e sem a skill e ligar um hook. Serve para quem já tem várias skills e não sabe quais estão quebradas. Precisa só de Python 3.8 ou mais novo, e nenhuma skill muda sem você aprovar.
O skill-creator-plus original, mais o que o INEMA acrescentou para usar no dia a dia, inclusive um validador que entende skills em português e espanhol.
A maioria vem da documentação oficial da Anthropic (guia de skills, docs do Claude Code, guia de prompting do Fable 5 e do Opus 5.5), com o link de cada uma; algumas, como as famílias NM e LB, vêm da prática do autor e estão marcadas como conselho. 20 são só por leitura, julgadas pelo agente.
validate_skill.py em Python puro, sem instalar nada. Confere a parte mecânica de uma skill ou de uma pasta inteira e diz arquivo e linha de cada problema. Só lê; não altera nada.
Cinco passos para não auditar tudo de uma vez: validador, cinco piores, relatório, teste com e sem, hook. Com dois scripts novos: relatorio.py e hook_validar.py.
Primeiro o validador mede; depois o agente lê e relata; você decide o que aplicar; o teste prova; o hook segura.
Frontmatter que o YAML entende; nome e descrição dentro do limite, em terceira pessoa, dizendo quando usar.
SKILL.md abaixo de 500 linhas, referências a um nível, sumário em arquivo longo, nada de link morto ou TODO.
Checklist com "pronto quando" e linha de voltar; scripts que resolvem o erro; pacotes com linha de instalação.
Ajustes para os modelos 5.5, regra dura em hook, testes com e sem a skill e biblioteca sem duas skills disputando o mesmo pedido.
O validador e os scripts usam só a biblioteca padrão do Python. O agente entra no relatório e na correção.
Linux, Mac ou Windows. Nada para instalar com pip.
# conferir a versão python3 --version
Para baixar o repositório (ou baixe o ZIP pelo GitHub).
git --versionSó para os modos AUDIT, NEW e REFINE da skill. O validador roda sem agente.
# skills ficam em ~/.claude/skills # Claude Code ~/.agents/skills # Codex
Rode na ordem. Os passos 2 e 3 só leem as suas skills; o passo 4 só edita depois que você escolher.
Uma pasta na sua casa. Os comandos seguintes rodam de dentro dela.
git clone https://github.com/inematds/auditar-skills ~/auditar-skills cd ~/auditar-skills
Uma linha por skill: erros, avisos, notas e as regras violadas. Código de saída 0 = sem erro, 1 = há erros, 2 = não conseguiu rodar.
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 erros e avisos e detalha as N piores, agrupando os achados por regra. Ou escolha as cinco que você mais usa.
python3 skill-creator-plus/scripts/validate_skill.py --all ~/.claude/skills --json \ | python3 scripts/relatorio.py - --top 5 > relatorio.md
O modo AUDIT lê a skill inteira, marca cada regra (passa, falha ou n/a) com arquivo e linha e só edita o que você aprovar.
cp -r ~/auditar-skills/skill-creator-plus ~/.claude/skills/ # Codex: ~/.agents/skills/ # no Claude Code, numa sessão nova: "Audite a skill formato-curso-v2 contra as regras da Anthropic. Só o relatório, não edite nada."
Os modelos 5.5 costumam ir melhor com menos instrução, mas só uma execução comparada prova que uma linha é peso morto. Monte duas cópias e rode a mesma tarefa em cada uma.
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/ # apague as linhas candidatas só aqui
Exemplo, não vem instalado. Toda vez que o agente salvar um SKILL.md, o validador roda; se houver erro, o agente recebe a lista e corrige na hora. Vai no ~/.claude/settings.json.
{
"hooks": { "PostToolUse": [ {
"matcher": "Write|Edit",
"hooks": [ { "type": "command",
"command": "python3 ~/auditar-skills/scripts/hook_validar.py",
"timeout": 60 } ]
} ] }
}
Teste antes de ligar: código 0 = sem erro, 2 = erros listados. Detalhes em docs/receita-inema.md.
echo '{"tool_input":{"file_path":"'"$HOME"'/.claude/skills/minha-skill/SKILL.md"}}' \ | python3 scripts/hook_validar.py; echo "código: $?"
Rodado em cópias de quatro skills do INEMA, no scratchpad, sem tocar nas originais. O relatório completo está em examples/relatorio-inema.md.
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.
E o próprio skill-creator-plus passa no seu validador: 0 erros e 1 aviso (a imagem do banner do README não é citada no SKILL.md).
O espelho acompanha o original; a receita cresce com o uso nas skills do INEMA.
skill-creator-plus/, validador adaptado para PT/ES (DS3, ST5 e CT9, com teste), receita INEMA, relatorio.py, hook_validar.py, guia e README em PT, EN e ES.skill-creator-plus/ é copiada de novo e a mudança INEMA no validador é reaplicada.