Skills Audit
Validates all .claude/skills/*/SKILL.md files against canonical template standards and Anthropic's latest published best practices.
What this skill does
- Runs 12 deterministic validation rules (frontmatter, structure, classification, content)
- Fetches latest Anthropic skill docs and compares against our standards (by default)
- Produces a structured PASS/WARN/FAIL report per skill
- Optionally auto-fixes trivial issues
Quick start
python .claude/skills/do-skills-audit/scripts/audit_skills.py $ARGUMENTS
If $ARGUMENTS was not substituted (the command shows a literal $ARGUMENTS): Look at the user's original message — they invoked this as /do-skills-audit <flags>. Extract whatever follows /do-skills-audit and pass it to the script. If no flags were provided, run the script with no arguments (default behavior).
Arguments
| Flag | Description |
|---|---|
--fix |
Auto-fix trivial issues (missing name, trailing whitespace) |
--json |
Output JSON only |
--skill <name> |
Audit a single skill |
--no-sync |
Skip best practices sync (fast, offline) |
--apply |
Apply best practices updates to template/validator |
--update-skills |
Update existing skills to match new best practices |
--force-refresh |
Bypass doc cache and re-fetch |
Validation Rules
Structural (FAIL): line count ≤500, frontmatter exists, name valid, broken sub-file links Quality (WARN): description trigger-oriented, description ≤1024 chars, known fields only, argument-hint presence Classification (WARN): infrastructure/background/fork skills have correct frontmatter flags Content (WARN): no duplicate descriptions across skills
After the Audit
With --fix: trivial issues (missing name field, trailing whitespace) are auto-corrected in place. Complex findings (classification mismatches, trigger phrasing, duplicate descriptions) are reported for human review. Without --fix: all findings are report-only.