skill-audit

# Skill Audit ## Overview Skills accumulate. Nobody deletes them, most developers hit 8-12 installed skills before the per-session token cost of loading every description starts to outweigh the benefit, and a skill installed at both the personal and project scope with the same name fails silently — the higher-precedence one wins and the other never fires, with no error anywhere. This script checks the mechanical properties that predict a skill working or silently failing: valid frontmatter, a description that leads with the trigger (not a workflow summary), a body under the token-efficiency guideline, and no name collision across scopes. **Core principle:** A skill that never triggers and a skill that doesn't exist have the same effect on the user, but only one of them is visible in a directory listing. This script finds the invisible kind. ## Usage ```bash python3 ${CLAUDE_SKILL_DIR}/scripts/audit.py [skills_dir ...] ``` With no arguments, checks `.claude/skills/` (project) and `~/.claude/skills/` (personal) if they exist. Pass explicit paths to also check a plugin's `skills/` directory (plugin skill dirs aren't auto-discovered, since a plugin's install location varies). Exit code 0 = clean, 1 = findings, 2 = usage error. ```bash python3 ${CLAUDE_SKILL_DIR}/scripts/audit.py .claude/skills ~/.claude/skills ./my-plugin/skills ``` ## What it checks | Check | Why it matters | |---|---| | Frontmatter parses | A `SKILL.md` without valid `---`-delimited YAML at the top is ...