English · 简体中文

Skill Pruner

Cross-platform cleanup tool for AI agents. Prevent tool overload and context bloat.

Giving an AI Agent (like Claude Code, Cursor, or Codex) too many custom skills significantly drops its tool-selection accuracy. The agent hesitates, hallucinates, and burns through context window tokens just trying to figure out which tool to use.

Skill Pruner is a local, cross-platform utility that automatically scans your agent usage logs (JSONL/SQLite) to find custom tools you haven't used in 30 days. It then safely quarantines them—never deleting, always symlink-aware—to keep your agent fast, smart, and focused.

1. Supported Platforms

Skill Pruner parses the raw, hidden logs of these platforms to find what you actually use:

Platform	Detection Method	Notes
WorkBuddy	usage-log.json	Native JSON tracking support
Hermes	.usage.json	Native JSON tracking support
Claude Code	projects/*/*.jsonl	Parses raw transcript tool calls
Codex	sessions/**/*.jsonl	Parses CLI session history
Cursor	agent-transcripts/	Parses Agent transcripts & SQLite
AGY	conversations/*.db	Queries SQLite view_file events
Trae	skills/	Standard directory scan
Copilot	skills/	Standard directory scan

2. Quick Install

If your agent supports npx skills, simply run:

npx skills add willson-wen/skill-pruner

(You can also literally tell your agent: "Install the skill-pruner from willson-wen and scan my system.")

Or install manually via git and python:

git clone https://github.com/willson-wen/skill-pruner.git
cd skill-pruner

3. Workflow & Usage

We recommend running the Pruner manually once a month to keep your agents sharp.

Scan your entire system:

skill-pruner scan

Generate a report of idle skills (unused for 30 days):

skill-pruner report --days 30

Safely archive stale skills: (Runs as a dry-run by default. Use --confirm to actually execute).

skill-pruner prune --days 30 --confirm

Restore a skill if you need it back:

skill-pruner restore <skill-name>

4. Architecture & Safety Guarantees

graph TD
    A[detect_platforms.py] -->|Detect 8 Platforms| B(pruner.py scan)
    B --> C{Platform Adapters}
    C -->|Direct Read| D1[WorkBuddy / Hermes]
    C -->|Regex Parse| D2[Claude / Codex JSONL]
    C -->|Query| D3[AGY / Cursor SQLite]
    C --> E[Unified Usage Data]
    E --> F[pruner.py report]
    F --> G((User Confirmation))
    G -->|Approve| H[pruner.py prune]
    H --> I[Archive to ~/.skill-pruner]

Loading

Safety First

• Zero Deletion: Pruned skills are moved to a cold archive directory. os.remove() is strictly banned in the source code.
• Symlink Awareness: If a skill is symlinked from your central dotfiles, Pruner will carefully unlink the symlink from the agent directory without destroying your original source file.
• Privacy: 100% local. No logs or data ever leave your machine.

5. Contributing

Want to add an adapter for a new agent platform? We'd love that. Check out the Platform Adapters Guide and submit a PR.

License

MIT License