Writing your Agent skill (Skill) descriptions too long doesn't just waste Tokens — it also lowers the Agent's accuracy when picking a skill. After someone trimmed a 90-plus-word description down to under 40 words, the Agent picked the right skill on the very first try.

Peter, the "father of the lobster," couldn't stand watching this any more and open-sourced a tool that gives every Skill a "health check": skill-cleaner.

Why Put Your Skills on a Diet

The trouble with Skill prompts looks, on the surface, like copy length, but it actually affects three things:

• Cost: every extra sentence of description is another Token bill on every Agent call
• Latency: the more information the Agent sees, the more noise it faces when choosing
• Accuracy: information overload makes the Agent pick the wrong tool

Peter's position is clear: a Skill should be like a road sign — its job is to help the Agent find the way, not to hang the entire manual on the sign. And skill-cleaner itself is the best demonstration -- its Skill.md is only 56 lines of prompts, while the scripts it invokes run to nearly a thousand lines of code.

Five Core Features

1. Skill Prompt Budget Audit

It analyzes how much context Token space each Skill occupies, computes the budget utilization ratio, and proposes an optimization plan. The script uses the same prompt-budget accounting logic as Codex's official source code, reads the local model cache configuration to get GPT-5.5 context window parameters (272K Tokens by default), and strictly follows Codex's billing rule (UTF8 byte count / 4, rounded up).

2. Duplicate Skill Detection

It scans across Codex's built-in library, plugin caches, codebases, and personal skill root directories for same-named skills and duplicates with highly similar descriptions/content, flagging the redundant entries.

3. Unused Skill Screening

Based on history logs, it identifies idle skills that have gone a long time without being invoked, mentioned, or touched in any way, and provides a cleanup candidate list.

4. Skill Root Directory Audit

It tallies the source root directories of all skills, marks enabled/disabled status, and maps out the skill loading chain.

5. Description Slimming

It finds verbose skill descriptions and slims them down through a three-step process:

• Text preprocessing: normalize the format, lowercase everything, strip punctuation
• Scenario recognition: a built-in keyword lexicon of preset scenarios identifies the business domain each skill belongs to
• Standardized replacement: replace verbose descriptions with preset short action phrases

For example: debugging skills become debug, inspect, fix; deployment and release skills become deploy, release, verify.

How to Use It

Preparation

• A Node.js environment
• An existing Agent Skills directory

Step 1: Installation

# Clone the repository
git clone https://github.com/steipete/agent-scripts/tree/main/skills/skill-cleaner

# Install dependencies
npm install

Step 2: Run the Audit Analysis

Run the script in your skills directory or repo root:

node skill-cleaner.js --dir /path/to/skills

Supported parameters:

• --time-range: specify the time range to analyze
• --log-depth: log analysis depth
• --budget-threshold: budget threshold
• --custom-root: custom skill root directory

Step 3: Review the Report and Optimize

Read the core reports in order: skill budget -> description optimization items -> duplicate skills -> unused skills -> root directory summary.

Safety principles while optimizing:

• Keep Codex built-in skills first
• Don't delete unrelated directories you haven't confirmed
• Verify that the retained files are valid before modifying anything

Verifying the Results

After optimizing, you can watch two metrics:

1. Token budget utilization: check whether each Skill's share of the context has dropped
2. Agent invocation accuracy: after descriptions are slimmed, whether the Agent picks the correct skill more accurately

FAQ

• Q: Will slimming descriptions lose key information? A: skill-cleaner's strategy is to replace verbose descriptions with standardized short phrases, keeping the "action" rather than the "explanation." What an Agent needs is an accurate road sign, not a detailed manual.

• Q: Does it support non-Codex Agent frameworks? A: The core logic is generic, but the billing rule and budget baseline default to Codex standards. If you use another framework, you need to adjust the budget parameters yourself.

GitHub: https://github.com/steipete/agent-scripts/tree/main/skills/skill-cleaner