When to use

User says "audit my skills for quality", "any skills wasting tokens?", "look for LLM-as-loop smells", "are my skills well-designed", or invokes /mikko-skills-quality.

Quarterly cadence, or after writing a new skill. Companion to /mikko-skills-freshness (which checks for STALE skills); this one checks for BADLY-DESIGNED skills.

Workflow

0. First run — baseline first

Fresh install with no manifest yet? Run --update BEFORE reviewing. The script writes the manifest unconditionally and the next invocation starts from "all clean". Skip to step 5.

1. Run the audit

Pick the right script path for how the skill was installed:

Windows PowerShell — same paths with $env:USERPROFILE instead of ~ and \ separators.

Defaults: both scopes (project under cwd/.claude/skills/, global under ~/.claude/skills/), no manifest write.

2. Read the table

SCOPE    SKILL                            STATUS     TOP FINDING
project  big-iterator                     flagged    [HIGH] 6 loop-style prose patterns with no companion script. Likely asking ...
project  no-frontmatter-skill             flagged    [HIGH] Frontmatter missing required field(s): description.
global   touched-but-clean                changed    pre-pass clean - needs LLM verify (changed since last review)

If the table is All skills pass quality + unchanged - nothing to review., STOP. Nothing further to do.

3. Per-row action

The TOP FINDING column + the optional Additional findings: block carry the full signal. Do NOT open the skill's SKILL.md by default — only when the message is ambiguous or the user asks for a fix proposal.

4. Ask before editing

Present findings as a short table first. Do not modify any skill file without an explicit per-skill go-ahead.

5. Baseline once accepted

Same path as step 1, plus --update:

python <path-from-step-1> --update

Writes the manifest at each scope root. The next audit treats today's state as baseline.

The ruleset

Lives in rules.py next to this script. Each rule's own message is self-describing in the audit output — no per-rule cheat-sheet needed here. The single non-obvious property: editing rules.py re-keys every skill, because the manifest entry's key is (skill_hash + sha256(rules.py)). A rule change forces a full re-review next audit.

install.sh (symlink mode) keeps reading the source rules.py and _lib/. If the source tree moves or you delete it, the symlinks dangle and the skill silently breaks on next invocation — re-install from a fresh checkout. install-mikko.sh (copy mode) bundles sibling copies; this makes the installed rules.py the authoritative source for the hash, so editing the installed copy re-keys everyone locally (handy for tuning thresholds without forking the source). git pull of the source repo won't propagate to copy-mode installs without re-running install-mikko.sh.

Freshness check

[[check]]
kind = "path_exists"
path = "skills-quality.py"
root = "skill_dir"

[[check]]
kind = "path_exists"
path = "rules.py"
root = "skill_dir"

[[check]]
kind = "file_contains"
path = "skills-quality.py"
pattern = "SCRIPT_VERSION"
root = "skill_dir"

[[check]]
kind = "file_contains"
path = "rules.py"
pattern = "RULES"
root = "skill_dir"

[[check]]
kind = "no_broken_md_links"