| name | skill-cleaner |
| description | Audit Codex/OpenClaw skills: loaded roots, duplicate skills, unused skills, prompt-budget costs, compact descriptions. |
Skill Cleaner
Use this when trimming skill prompt budget, finding duplicate skills, auditing enabled/disabled skill roots, or deciding which skills/plugins to remove.
Workflow
- Run the analyzer from this skill directory or 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 ~/Dropbox/boxd/skills --no-logs
- Read the report in this order:
Skill Budget: GPT-5.5 context size, 2% skills budget, Codex-budgeted usage, and pre-budget full-list pressure.Description candidates: long descriptions where relaxed grammar saves prompt budget.Duplicates: same skill name or near-identical description/body across Codex, plugin cache, repo siblings, and personal skill roots.Unused candidates: no recent $skill mention, SKILL.md read, or explicit skill-use trace in recent Codex/OpenClaw 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 deleting repo-local or
.ai_agents/ duplicates when Codex built-ins cover them.
- Preserve trigger nouns in descriptions: product, tool, action, object.
Analyzer Notes
- The script mirrors Codex's model-visible line shape:
- name: description (file: path).
- It applies Codex-like frontmatter rules: YAML frontmatter only, default name from parent dir, single-line sanitized
name and description.
- It follows Codex
core-skills/src/render.rs: 2% of raw context_window, token cost ceil(utf8_bytes / 4), then full descriptions -> equal description truncation -> omitted minimum lines.
- It reads
~/.codex/models_cache.json for GPT-5.5 context_window; fallback is 272,000 tokens and 2%.
- It scans only normal Codex/plugin/repo skill roots by default. Extra folders such as Dropbox archives are included only with
--root <path>.
- It realpath-dedupes roots, so symlinked roots such as
~/.codex/skills/agent-scripts -> ~/Projects/agent-scripts/skills do not create false duplicates.
- For duplicate names, it reports description/body similarity and suggests deletion candidates only when bodies are near copies. Keep priority defaults to direct Codex system skills, then direct Codex skills, then plugin skills, then personal/repo copies.
- It scans
~/.codex/history.jsonl, ~/.pi, ~/.claude, ~/.copilot, and ~/.opencode and recent ~/.codex/sessions/**/*.jsonl by default. Add --deep-logs . fan out parallel sub-agents for deep and time efficient investigations.
- Usage evidence is heuristic:
$skill, Use $skill, and paths like skills/<name>/SKILL.md and when there's tool calls that indicate that a skill was invoked.
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.
