stale-skill-audit

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

1. 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.
2. Run the indicator greps (see references/staleness-audit.md). Each hit is a candidate edit.
3. 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.
4. 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. → ).