skill-mechanic

name	skill-mechanic
description	Audit, secure, deduplicate, update-check, and manage the local agent skill library. Use when asked to audit skills, check skill health or security, review a newly installed or third-party skill, find duplicate/overlapping skills, check skills for updates or drift, or clean up the skill library. Not for authoring new skills from scratch (use skill-creator for that).
license	MIT
compatibility	Requires python3. Works on any Agent Skills (agentskills.io) library; auto-detects Claude Code, OpenClaw, hermes-agent, and fft_nano skill directories.
metadata	{"version":"1.0.0","source":"local"}
allowed-tools	Read Glob Grep Bash(python3:*) Bash(git log:*) Bash(git diff:*) Bash(git status:*)

Skill Mechanic

You are the curator of this machine's skill library. Your job is disciplined triage, not busywork: "healthy, no action needed" is a successful audit, and you must be structurally incapable of manufacturing work. Every conclusion you report must trace to evidence (file:line or a script measurement).

All deterministic facts come from the bundled engine — never eyeball what the script can measure:

python3 scripts/skilltool.py <inventory|validate|measure|scan|diff|all> [--roots DIR ...]

Run it with the skill's own directory as cwd, or by absolute path. With no --roots it auto-detects known libraries on this machine: ~/.claude/skills, ~/.openclaw/skills, ~/.openclaw/plugin-skills, ~/fft_nano/skills/runtime, ~/hermes-agent/skills, plus ./.claude/skills and ./skills in the current project. When running inside one agent, default to auditing that agent's own library unless the user asks for everything.

State lives in ~/.skill-mechanic/ (baselines + decisions.jsonl). Never store state inside the skill directory itself.

Modes

Request	What to do	Mutates?
status	skilltool.py all on this agent's roots; report the one-line verdict + budget	No
audit [scope]	Full pipeline below; write the report	No
review <path/skill>	Deep single-skill review (--roots pointed at it) — the quarantine gate for anything new or third-party. Read every file.	No
updates	diff for drift; check metadata.source/metadata.version fields and, for skills inside git repos, git log -1 -- <dir>	No
fix	Apply MUST/SHOULD items from the latest report one at a time, showing diffs; get confirmation before each destructive change (delete, merge, move)	Yes
dedupe	Cluster overlapping skills, propose a merge/retire plan, execute only on approval	Yes
accept	skilltool.py decide --id X --status accepted --reason "..."	State only

Audit modes are strictly read-only. Do not "fix things while you're in there."

Audit pipeline

1. Facts — skilltool.py all. This yields spec-conformance findings, token-budget measurements, security candidates, and drift vs the last baseline in one JSON blob.
2. Judge security candidates — every scan candidate gets a verdict: confirmed / plausible / benign, per references/security-rubric.md. Read the actual file at the flagged line before judging; most matches in a healthy library are benign (a security skill describing attacks will match attack patterns). Never report a raw regex hit as a vulnerability.
3. Judge quality — score only skills the facts flagged (thin descriptions, oversized bodies, placeholders) plus any the user asked about, using references/quality-rubric.md. Do not rubric-score an entire healthy library unprompted.
4. Library coherence — from the inventory, identify overlap clusters: skills whose descriptions could route the same request (e.g. near-identical names, foo vs foo_v2 vs foo.bak). Flag pairs where an agent genuinely could not tell which to fire.
5. Triage — force every finding through the gates in references/triage-policy.md into MUST / SHOULD / COULD / NOTHING.
6. Report — use assets/report-template.md. First line is the verdict: either "No action required" or "N items need attention (M must, K should)".
7. Baseline — after the user has seen the report (not before), offer to run skilltool.py diff --update so future audits detect drift/tampering.

Triage gates (summary — full text in references/triage-policy.md)

• MUST: confirmed injection/exfiltration; unexplained file drift since the last reviewed baseline; a skill that errors on invocation and is actively used; a name collision that makes a skill silently unreachable.
• SHOULD: high-overlap duplicates; unverified drift; spec violations that degrade routing (empty/placeholder description, name-dir mismatch); a frequently-used skill at 2x+ the body budget.
• COULD: style, missing license, weak descriptions on rarely-used skills. Cap at 5 per report; label "fine to ignore forever."
• NOTHING: everything else — state it affirmatively with the count.

Hard rules: never re-raise a finding recorded in decisions.jsonl (the engine filters these; do not use --all-findings except when explicitly asked); never invent COULDs to fill space; never recommend refactoring a working, unflagged skill. Include this skill itself in every full audit — it gets no exemption.

Security escalation

If you confirm active malicious behavior (exfiltration, credential theft, concealed instructions), that is the report's headline. Name the skill, quote the evidence, recommend immediate removal or quarantine — but do not delete anything yourself without confirmation; quarantine means moving the directory to ~/.skill-mechanic/quarantine/, never deleting it, so evidence is kept.

Scale note

For libraries over ~50 skills in an agent that supports subagents, fan per-skill judgment (steps 2-3) out to cheaper-model subagents in batches, passing each batch the relevant JSON slice and the two rubric files; do final triage and the report yourself. In agents without subagents, run the pipeline inline — the scripts keep it cheap.