Guide · Agent skill
How to use the Skill Cleaner agent skill: audit Codex skills
Updated · written with AI from the project's own documentation and checked against our catalogue data
Skill Cleaner is an agent skill for people who run many custom skills in Codex or OpenClaw. A skill is a folder containing instructions that tells an AI coding agent how to handle a particular task. This one teaches the agent to run an analyzer script that reports how much prompt space your skills use, which skills are duplicates, and which ones have seen little recent use. After this guide you will know how to install the skill, ask for an audit in plain language, and read the report safely before changing anything.
Skill Cleanersteipete/agent-scripts · MIT Download the skill Quick start
- 1Download the ZIP. Download the skill-cleaner ZIP file from this page.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use or into your project's .claude/skills/ folder.
- 3Or upload in the Claude apps. Open Settings → Capabilities → Skills in the Claude apps and upload the ZIP instead.
- 4Confirm prerequisites. Check that Node.js with --experimental-strip-types support and the Codex CLI are available, or plan to use --no-live.
- 5Ask for an audit. Request a skill audit in plain language, such as asking for prompt budget and duplicate findings.
- 6Review the report. Read Skill Budget, Description candidates, Duplicates, Unused candidates and Root summary in that order.
- 7Verify before cleaning up. Confirm the kept copy is loaded, then ask for small grouped changes only if you want them.
What does the skill-cleaner skill make the agent do?
When you ask for a skill audit, the agent runs a Node analyzer script (scripts/skill-cleaner.ts). The script inventories the skills loaded into Codex, estimates how much of the prompt budget they consume, finds duplicate or near-identical skills across folders, and flags skills with little recent usage in session logs.
The agent then reports suggestions. According to the skill's output policy, it edits nothing unless you ask it to, and if you do ask for cleanup it makes small grouped commits covering descriptions, deletes or config disables.
- Skill Budget: live Codex inventory, the 2% budget, budgeted usage and full-description pressure
- Description candidates: long descriptions where shorter wording would save prompt budget
- Duplicates: same skill name or near-identical description or body across roots
- Unused candidates: no recent user mention or actual SKILL.md read in recent logs
- Root summary: where skills came from and whether config marks them disabled
Install the skill-cleaner skill
Download the ZIP file from this page. Then choose one of two routes. For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
After unzipping, the skill should sit in its own folder containing SKILL.md, agents/openai.yaml, and scripts/ with skill-cleaner.ts and skill-cleaner.test.ts.
- Personal: ~/.claude/skills/
- Per project: .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check what you need before running it
The analyzer needs Node.js with --experimental-strip-types support, the Codex CLI, and local Codex files such as ~/.codex/history.jsonl and ~/.codex/sessions for usage evidence. By default the script calls codex debug prompt-input to read the live skill list. If you do not have the Codex CLI, pass --no-live, which uses a broader filesystem fallback instead.
The skill runs scripts and does not use the network, according to its listing.
- Node.js with --experimental-strip-types support
- Codex CLI (not needed if you use --no-live)
- Local Codex files in ~/.codex for usage evidence
Run an audit with a natural request
You do not need to type the script command yourself. Ask the agent in plain words, for example: "Audit my skills for prompt budget and duplicates" or "Find skills I never use and long descriptions I can shorten." The skill's description covers budget, usage, duplicates and compact descriptions, so requests about those topics are the ones it is built for.
If you prefer to run the analyzer directly, the base command from the skill is shown below. It reads the last three months of logs.
- "Trim my skill prompt budget"
- "Find duplicate skills across my repos and plugin cache"
- "Which skills have not been used in recent Codex sessions?"
- "Audit only my Dropbox skills folder without logs"
node --experimental-strip-types skills/skill-cleaner/scripts/skill-cleaner.ts --months 3Useful analyzer options
The skill documents several variants. Use --no-logs to skip log scanning, and --no-live with --no-logs to skip the live Codex inventory as well. --root adds an extra folder to scan, and --root-only scans only the roots you supply, so it requires at least one --root. Deeper log reading is available with --deep-logs, which also covers archived sessions and common OpenClaw or Clawd log folders.
- --no-logs: skip history and session scanning
- --no-live --no-logs: use the filesystem fallback only
- --root ~/.agents/skills --root-only --no-logs: scan just one root
- --months 6 --max-log-mb 800 --deep-logs: wider log history
node --experimental-strip-types skills/skill-cleaner/scripts/skill-cleaner.ts --root ~/.agents/skills --root-only --no-logsRead the report and verify before deleting
Read the report in order: Skill Budget first, then Description candidates, Duplicates, Unused candidates and Root summary. Treat usage results as heuristic. They come from user mentions such as $skill or "use skill" and from paths seen in tool-call arguments, so a skill can be useful without appearing there.
Before deleting or editing anything, confirm that the copy you plan to keep exists and is loaded. The skill suggests deleting repo-local or agent-scripts duplicates when Codex built-ins cover the same job, and keeping repo-local OpenClaw maintainer skills that encode repo policy or live operations. Keep the wording of trigger nouns in descriptions (product, tool, action, object) so the agent still knows when to use the skill.
- Confirm the kept copy exists and is loaded
- Keep repo-local OpenClaw maintainer skills that hold repo policy
- Do not delete ignored or untracked skill folders unless you name the destination or confirm they are disposable
What people use it for
- Cutting prompt bloat by shortening long skill descriptions while keeping trigger nouns
- Finding the same skill copied across repos, a plugin cache and a personal folder
- Auditing an archive folder such as a Dropbox skills directory with --root and --root-only
- Spotting skills that have had no recent user mention or SKILL.md read in Codex logs
Frequently asked questions
How do I install the skill-cleaner skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What do I need to run skill-cleaner?
You need Node.js with --experimental-strip-types support and the Codex CLI, because the script calls codex debug prompt-input by default. Local Codex files such as ~/.codex/history.jsonl and ~/.codex/sessions provide usage evidence. If you lack the Codex CLI, use --no-live.
Is skill-cleaner free and what is its licence?
The skill is listed under the MIT licence in the steipete/agent-scripts repository. This page does not list any price, so check the source repository for terms.
Does skill-cleaner delete my skills automatically?
No. Its output policy says to suggest first and edit only when you ask. If you request cleanup, it makes small grouped commits, but deleting duplicates can remove the only copy of a skill if the kept copy is not verified, so check first.
Does skill-cleaner work with Claude Code or other agents?
The source describes it as a Codex and OpenClaw skill audit. It reads Codex-specific config, history and session files, so it is not meant for users who do not use Codex or OpenClaw.
Why does the analyzer report a skill as unused when I use it?
Usage evidence is heuristic. It counts user $skill or use skill mentions and paths in tool-call arguments in the logs it scans. Try --deep-logs or a longer --months window if your usage is older or archived.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Skill Cleaner suits developers and maintainers who run many custom Codex or OpenClaw skills and want to cut prompt bloat or remove duplicate copies. It is a poor fit if you do not use Codex or OpenClaw, or if you want unattended deletion, since the skill is designed to suggest changes and verify copies before anything is removed.
Download the skill