| name | stale-skill-audit |
| version | 1.0.0 |
| author | Hermes Agent |
| license | MIT |
| platforms | ["linux","macos","windows"] |
| description | Audit an existing SKILL.md for stale content and produce a safe-subset cleanup PR — drop dead Provenance footers, swap drifted canonical names (bd→br), normalize header dates, never rewrite content. Use when the user says 'cleanup this skill', 'this skill is bloated', names a specific skill that drifted, or a scheduled `agent-agent-mistakes` review flagged a file. Triggers: 'cleanup this skill', 'prune this skill', 'this skill is bloated', 'audit stale skill content', 'normalize dates in SKILL.md', 'swap bd to br', 'safe subset cleanup'. |
| metadata | {"hermes":{"tags":["skills","audit","cleanup","maintenance","staleness","sediment"],"related_skills":["hermes-agent-skill-authoring","skillify","simplify-code","session-learn-distill","harness-postmortem"]}} |
Stale-Skill Audit — Safe-Subset Cleanup for an Existing SKILL.md
Skills accumulate sediment: dead Provenance footers, drifted CLI names, header dates that pin to a specific moment in time, WIP-forward language, and content-meaning edits that no longer pull their weight. This skill is the recipe for a single PR that removes the sediment without rewriting the skill.
Default philosophy: safe subset only. No paragraph removal, no rule reordering, no content-meaning edits. Drop dead audit data, swap drifted names, normalize header dates. Stop there unless the user explicitly escalates.
When to Use
- User says "cleanup this skill" / "prune this skill" / "this skill is bloated" / "audit stale skill content".
- User names a specific SKILL.md that drifted from current org conventions.
- A scheduled
agent-agent-mistakes or meta-autonomy-violation-handler review flagged a file.
- The org changed canonical CLIs, paths, or defaults and a skill still references the old ones (e.g.
bd → br).
- The skill's description is approaching 1024 chars (validator forces a rewrite — may as well clean the body too).
Do NOT use this for:
- Proactive "this looks old" cleanup without a signal. Unsolicited cleanup PRs don't merge.
- Creating a new skill (use
skillify).
- Simplifying code (use
simplify-code — that one is for code, not docs).
- Promoting local user-scope additions to the repo (separate "promote to repo" PR, not a cleanup PR).
Quick Start
- Find the canonical file. Check both
~/.claude/skills/<name>/SKILL.md (user-scope local) and the repo's .claude/skills/<name>/SKILL.md (remote canonical). They often drift.
- Run the indicator greps (see
references/staleness-audit.md). Each hit is a candidate edit.
- Classify each hit:
- Header/frame (description, lead-in, table title): normalize or drop.
- Incident-anchored (mid-rule, with a specific defect class or example): keep verbatim — it's load-bearing evidence.
- Provenance/audit footer: drop the whole section.
- Apply minimal patches with
patch (or skill_manage action='patch' for in-repo skills). replace_all=true only when every occurrence is unambiguously the same edit (e.g. → ).
