Skill Cleaner

Use this when trimming skill prompt budget, finding duplicate skills, auditing enabled/disabled skill roots, or deciding which skills/plugins to remove.

This is adapted for Joel's system from Peter Steinberger's agent-scripts skill-cleaner skill.

Joel System Contract

Canonical joelclaw skills live in the owning repo's skills/ directory, usually ~/Code/joelhooks/joelclaw/skills/ or a runtime checkout's skills/.
Consumer skill roots should be real directories:
- ~/.pi/agent/skills/
- ~/.agents/skills/
- ~/.claude/skills/
Skill packs should be namespaced symlinks inside those roots, for example ~/.agents/skills/joelclaw-runtime -> ~/Code/joelhooks/joelclaw-runtime/skills.
Flat per-skill symlinks are compatibility shims only, for consumers that still require ~/.pi/agent/skills/<name>/SKILL.md.
External skill packs may live under ~/.pi/agent/git/, ~/.pi/agent/npm/node_modules/, or extension directories. Do not copy those into joelclaw unless Joel explicitly wants a curated fork.
Preserve project-local skills and repo policy even when they look redundant. They often encode operational truth.

Workflow

Run the analyzer from this skill directory or the joelclaw repo root:

node --experimental-strip-types skills/skill-cleaner/scripts/skill-cleaner.ts --months 3

Useful variants:

node --experimental-strip-types skills/skill-cleaner/scripts/skill-cleaner.ts --no-logs
node --experimental-strip-types skills/skill-cleaner/scripts/skill-cleaner.ts --months 6 --max-log-mb 800 --deep-logs
node --experimental-strip-types skills/skill-cleaner/scripts/skill-cleaner.ts --context-tokens 272000 --budget-percent 2 --no-logs
node --experimental-strip-types skills/skill-cleaner/scripts/skill-cleaner.ts --root ~/Code/badass-courses/skills --no-logs
node --experimental-strip-types skills/skill-cleaner/scripts/skill-cleaner.ts --json --no-logs

Read the report in this order:

Skill Budget: GPT-5.6 Sol-sized context, 2% skill budget, model-budgeted usage, and pre-budget full-list pressure.
Description candidates: long descriptions where tighter plain language saves prompt budget.
Duplicates: same skill name or near-identical description/body across Pi, joelclaw canonical, external packs, Codex, and project roots.
Unused candidates: no recent $skill mention, SKILL.md read, or explicit skill-use trace in recent Pi/Codex/Claude logs.
Root summary: where skills came from and whether config marks them disabled.

Before deleting or editing:

Verify the kept copy exists and is loaded.
Prefer canonical joelclaw repo copies for Joel-owned operational skills.
Prefer external package copies for third-party skills unless we intentionally forked them.
Preserve trigger nouns in descriptions: product, tool, action, object.
Never delete ignored/untracked skill dirs without naming the destination or confirming they are disposable.

Analyzer Notes

The script mirrors model-visible skill list line shape: - name: description (file: path).
It applies Codex/Pi-like frontmatter rules: YAML frontmatter only, default name from parent dir, single-line sanitized name and description.
It follows the common 2% of raw context_window prompt-budget heuristic, token cost ceil(utf8_bytes / 4), then full descriptions -> equal description truncation -> omitted minimum lines.
It searches ~/.pi/models_cache.json then ~/.codex/models_cache.json; fallback is 272,000 tokens and 95% effective context.
It scans Joel's normal skill roots by default: joelclaw canonical, Pi user skills, agents skills, Claude skills, Pi git/npm/extension skills, plus legacy Codex roots.
Extra folders such as project-specific skill roots are included only with --root <path>.
It realpath-dedupes roots, so symlinked roots do not create false duplicates.
For duplicate names, it reports description/body similarity and suggests deletion candidates only when bodies are near copies.
Usage evidence is heuristic: $skill, Use $skill, and paths like skills/<name>/SKILL.md in recent logs.

Output Policy

Suggest first; edit only when the user asks.
If asked to apply cleanup, make small grouped commits: descriptions, deletes, config disables.
Do not delete ignored/untracked skill dirs without naming the destination or confirming they are disposable.
For broad cleanup, pair this with skill-review and keep the parent agent as the decision-maker. No silent axe murder. 🐀