When to use

User says "are my skills up to date", "audit my skills", "check for skill drift", invokes /mikko-skills-freshness.

NOT for every commit. Cadence: when you suspect a referenced path has moved, after a refactor that renamed things, or quarterly.

Workflow

0. First run — baseline first

Fresh install with no manifest yet? Run --update BEFORE the review loop. The script writes the manifest unconditionally and the next invocation starts from "all up to date." Skip step 1; jump to step 5 syntax with --update.

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   CHECKS / ISSUE
project  equipment                        changed  2 pass, 1 FAIL
project  new-mission                      changed  no declared criteria - needs LLM review
global   mikko-audit                      new      3 pass

If the table is All skills up to date - nothing to review., STOP. Nothing further to do.

3. Per-row action

4. Ask before editing

Present findings as a short table first. Do not modify any skill file without explicit user approval.

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 project manifest is per-machine, not committable across mixed-OS teams — a sha256 over CRLF (Windows checkout) differs from LF (Unix checkout) of the same skill. Mixed-OS contributors should gitignore .claude/skills-freshness.manifest.json.

How to declare freshness criteria in a skill

In any SKILL.md, add a section under the exact heading # Freshness check (or ##/###) followed by a fenced TOML block:

[[check]]
kind = "path_exists"
path = "src/game/data/weapons.json"

[[check]]
kind = "file_contains"
path = "src/lib/schemas/save.ts"
pattern = "WEAPON_IDS"

[[check]]
kind = "no_broken_md_links"

Check kinds

pattern is a Python re regex, evaluated multiline.

root selects the path anchor:

• skill_dir — this skill's own directory
• scope_root — the repo root (project scope) or $HOME (global scope)
• home — $HOME
• absolute — path must be absolute (~ expanded)

Default: scope_root for project skills, skill_dir for global skills. Paths cannot escape their resolved root.

Content-reading checks (file_contains, file_lacks, no_broken_md_links) are restricted to skill_dir and scope_root — they reject root="home" / root="absolute" to prevent a skill from probing arbitrary files via a regex oracle. file_lacks on a missing file PASSES (use path_exists + file_lacks together to assert both).

Freshness check

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

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

[[check]]
kind = "no_broken_md_links"