About

Imported from joelhooks/joelclaw (skills/skill-cleaner/SKILL.md). Install upstream with npx skills add joelhooks/joelclaw --skill skill-cleaner. Copyright stays with the author.

Skill Cleaner

Name: skill-cleaner
Author: joelhooks

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. 🐀

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/joelhooks-joelclaw-skill-cleaner/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

joelhooks-joelclaw-skill-cleaner.ocm.jsonjson

{
  "ocm": "1",
  "id": "joelhooks-joelclaw-skill-cleaner",
  "kind": "skill",
  "name": "skill-cleaner",
  "description": "Audit Joel's Pi/joelclaw skills: loaded roots, duplicates, stale or unused skills, prompt-budget cost, and compact descriptions. Use when trimming skill prompt budget, finding duplicate skills, or deciding which skill copy should be canonical.",
  "publisher": "joelhooks",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "finance"
    ],
    "tags": [
      "skill-md",
      "joelclaw",
      "pi",
      "skills",
      "maintenance",
      "prompt-budget",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Audit Joel's Pi/joelclaw skills: loaded roots, duplicates, stale or unused skills, prompt-budget cost, and compact descriptions. Use when trimming skill prompt budget, finding duplicate skills, or deciding which skill copy should be canonical."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/joelhooks/joelclaw",
      "path": "skills/skill-cleaner/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/joelhooks/joelclaw/blob/HEAD/skills/skill-cleaner/SKILL.md",
      "key": "joelhooks/joelclaw/skills/skill-cleaner/SKILL.md"
    }
  },
  "instructions": "# Skill Cleaner\n\nUse this when trimming skill prompt budget, finding duplicate skills, auditing enabled/disabled skill roots, or deciding which skills/plugins to remove.\n\nThis is adapted for Joel's system from Peter Steinberger's `agent-scripts` `skill-cleaner` skill.\n\n## Joel System Contract\n\n- Canonical joelclaw skills live in the owning repo's `skills/` directory, usually `~/Code/joelhooks/joelclaw/skills/` or a runtime checkout's `skills/`.\n- Consumer skill roots should be real directories:\n  - `~/.pi/agent/skills/`\n  - `~/.agents/skills/`\n  - `~/.claude/skills/`\n- Skill packs should be na",
  "cost": {
    "context_tokens": 1134
  }
}

Fetch it by URL: GET /api/v1/registry/joelhooks-joelclaw-skill-cleaner/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.