46 rules, most from Anthropic's official docs and some from practice, a validator that runs in one second and a five-step recipe to find and fix the skills that fail the most, without touching anything you did not approve.
Auditar Skills is an open kit to check your agent's skills, the folders with a SKILL.md file that Claude Code and Codex use to do a task the same way every time. It ships skill-creator-plus, a RoboNuggets skill that checks each skill against 46 rules (most from Anthropic's official docs, some from practice), plus a five-step INEMA recipe: run the validator, take the five worst, generate a report, test with and without the skill and turn on a hook. It is for anyone who already has several skills and does not know which ones are broken. All it needs is Python 3.8 or newer, and no skill changes without your approval.
The original skill-creator-plus, plus what INEMA added for day-to-day use, including a validator that understands skills written in Portuguese and Spanish.
Most come from Anthropic's official docs (skills guide, Claude Code docs, Fable 5 and Opus 5.5 prompting guide), each with its link; some, such as the NM and LB families, come from the author's practice and are marked as advice. 20 are read-only, judged by the agent.
validate_skill.py in plain Python, nothing to install. It checks the mechanical side of one skill or a whole folder and gives the file and line of each problem. Read-only; it changes nothing.
Five steps so you do not audit everything at once: validator, five worst, report, test with and without, hook. With two new scripts: relatorio.py and hook_validar.py.
First the validator measures; then the agent reads and reports; you decide what to apply; the test proves it; the hook holds it.
Frontmatter that YAML can parse; name and description within limits, in third person, saying when to use it.
SKILL.md under 500 lines, references one level deep, contents list in long files, no dead links or TODOs.
Checklist with "done when" lines and a go-back line; scripts that solve the error; packages with install lines.
Adjustments for the 5.5 models, hard rules in hooks, tests with and without the skill and a library with no two skills competing for the same request.
The validator and the scripts use only the Python standard library. The agent comes in for the report and the fix.
Linux, Mac or Windows. Nothing to install with pip.
# check the version python3 --version
To download the repository (or download the ZIP from GitHub).
git --versionOnly for the skill's AUDIT, NEW and REFINE modes. The validator runs without an agent.
# skills live in ~/.claude/skills # Claude Code ~/.agents/skills # Codex
Run them in order. Steps 2 and 3 only read your skills; step 4 only edits after you choose.
One folder in your home directory. The next commands run from inside it.
git clone https://github.com/inematds/auditar-skills ~/auditar-skills cd ~/auditar-skills
One line per skill: errors, warnings, notes and the rules broken. Exit code 0 = no errors, 1 = errors found, 2 = could not run.
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 sorts by errors and warnings and details the N worst, grouping findings by rule. Or pick the five you use most.
python3 skill-creator-plus/scripts/validate_skill.py --all ~/.claude/skills --json \ | python3 scripts/relatorio.py - --top 5 > relatorio.md
AUDIT mode reads the whole skill, marks each rule (pass, fail or n/a) with file and line and only edits what you approve.
cp -r ~/auditar-skills/skill-creator-plus ~/.claude/skills/ # Codex: ~/.agents/skills/ # in Claude Code, in a new session: "Audit the formato-curso-v2 skill against Anthropic's rules. Report only, do not edit anything."
The 5.5 models often do better with fewer instructions, but only a side-by-side run proves a line is dead weight. Set up two copies and run the same task in each.
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/ # delete the candidate lines only here
An example, not installed by default. Every time the agent saves a SKILL.md, the validator runs; if there are errors, the agent gets the list and fixes them right away. It goes in ~/.claude/settings.json.
{
"hooks": { "PostToolUse": [ {
"matcher": "Write|Edit",
"hooks": [ { "type": "command",
"command": "python3 ~/auditar-skills/scripts/hook_validar.py",
"timeout": 60 } ]
} ] }
}
Test it before turning it on: exit code 0 = no errors, 2 = errors listed. Details in docs/receita-inema.md (in Portuguese).
echo '{"tool_input":{"file_path":"'"$HOME"'/.claude/skills/minha-skill/SKILL.md"}}' \ | python3 scripts/hook_validar.py; echo "exit code: $?"
Run on copies of four INEMA skills, in a scratch folder, without touching the originals. The full report is in examples/relatorio-inema.md (in Portuguese).
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.
And skill-creator-plus itself passes its own validator: 0 errors and 1 warning (the README banner image is not mentioned in SKILL.md).
The mirror follows the original; the recipe grows as it is used on INEMA's skills.
skill-creator-plus/, validator adapted for PT/ES (DS3, ST5 and CT9, with a test), INEMA recipe, relatorio.py, hook_validar.py, guide and README in PT, EN and ES.skill-creator-plus/ folder is copied again and the INEMA change to the validator is reapplied.