Skill Cleaner

Status: Experimental

Skill Cleaner audits installed Codex skills for prompt-budget pressure, duplicate copies, disabled entries, and optional recent-usage evidence. Its shared default is metadata-only and suggestion-only.

When To Use

• Review which installed skills consume the model-visible skill budget.
• Find duplicate or disabled skill copies before a controlled cleanup.
• Assess unused candidates after explicitly approving a local usage-log scan.

Requirements

• Node.js 22.6 or newer with --experimental-strip-types support.
• Read access to the installed Codex skill roots being audited.
• Explicit user authorization before adding --logs or inspecting any non-default root.
• No credentials or external service access are required.

Install

Try this skill intentionally while it is Experimental:

scripts/install-skill.sh skill-cleaner codex
scripts/install-skill.sh skill-cleaner copilot /path/to/project-repo
scripts/install-skill.sh skill-cleaner cursor /path/to/project-repo

Run

The default scans standard Codex skill metadata and plugin-cache metadata. It does not scan history or session logs:

node --experimental-strip-types /path/to/skill-cleaner/scripts/skill-cleaner.ts

Add another approved skill root explicitly with --root. Add --logs only after the user has specifically authorized local log inspection.

Typical Output

• Modeled skill-description budget and remaining capacity.
• Long-description and duplicate candidates with source paths.
• Root and disabled-skill summary.
• Unused candidates only when usage-log scanning was explicitly enabled.
• Suggestions only; no skills are edited, disabled, or deleted.

Testing

Run the fixture test from the repository root:

node --test skills/skill-cleaner/scripts/skill-cleaner.test.mjs

The test verifies log consent and date bounds, symlink containment, enabled-copy retention, explicit roots, and configurable token estimates.

Example Prompts

Use $skill-cleaner to audit my installed Codex skills. Keep the review metadata-only and do not change anything.

Use $skill-cleaner to identify unused candidates from the last three months. You may inspect my local Codex history and recent session logs for this audit, but do not edit or delete any skills.