open-source · Python 3.10+ · MIT

Audit your Claude Code
skill catalog.

Two stdlib-only Python skills that scan your local transcripts, reconcile invocations against your on-disk skill catalog, and tell you exactly which skills you use, when you last used them, and which are safe to archive.

View on GitHub Install

Runtime stdlib only, no dependencies

Platforms macOS / Linux / Windows

Network offline, no telemetry

License MIT

The problem

Your skill catalog grows faster than it gets cleaned up.

After installing dozens of marketplace skills, plugins, and personal scripts, the catalog becomes noisy. The core difficulty is that auto-triggered skills load through Read or shell access to SKILL.md — not always through the explicit Skill tool — so a simple grep of your transcript history undercounts invocations. Both skills in this repo scan every Claude Code transcript (~/.claude/projects/**/*.jsonl) and Codex session (~/.codex/sessions/**/*.jsonl), detect all six invocation patterns, and reconcile the results against your on-disk catalog: global, project, plugin (marketplace + cache), Codex skills, and Codex prompts.

Detection

What gets counted

Each event credits the skill once. Same-named skills across sources are merged into one row with summed counts.

Source	Pattern detected
Claude Code explicit	tool_use with name="Skill", input.skill=<name>
Claude Code slash command	<command-name>/name</command-name> in user messages only
Claude Code auto-trigger	Read of */skills/<name>/SKILL.md
Claude Code shell auto-trigger	Bash command containing */skills/<name>/SKILL.md
Codex slash command	User input_text whose first line is /name
Codex auto-trigger	function_call(exec_command/shell) arguments containing */skills/<name>/SKILL.md

Preview

Generated HTML dashboard

Running analyze.py writes a self-contained HTML file you can sort, filter, and export. The mock below shows representative rows across all three verdict states.

Name	Verdict	Sources	Count	Sessions	Last used	Days since	Size (KB)	Description
tdd	KEEP	global	48	19	2026-05-21	5	3.1	TDD workflow: red, green, refactor loop
brainstorming	KEEP	global project	31	14	2026-05-24	2	2.4	Explores intent and requirements before implementation
code-review	KEEP	global	22	11	2026-05-18	8	4.7	Review current diff for correctness bugs
deep-dive	REVIEW	global	3	3	2026-02-14	101	1.8	Deep-dive research loop with evaluator
wiki-ingest	REVIEW	global codex	0	0	—	—	6.2	Add new sources to wiki pages
pptx-design-styles	DELETE	global	1	1	2025-10-03	235	9.1	PowerPoint design style reference
reddit-poster	DELETE	project	0	0	—	—	2.0	Post to Reddit via MCP server

Classification

Verdict logic

Each skill is classified once, at report generation time, based on count and recency.

KEEP

The skill has been invoked at least once and was last used within 90 days. count > 0 and days_since ≤ 90

REVIEW

Never used but installed within the last 60 days, or used but last seen between 91 and 180 days ago. (count = 0 and install_age ≤ 60) or (days_since ≤ 180)

DELETE

Never used and installed over 60 days ago, or last used more than 180 days ago. (count = 0 and install_age > 60) or (days_since > 180)

Install

Clone the repo and copy the skill directories into your ~/.claude/skills/ folder. No package manager, no dependencies.

macOS / Linux

# clone
git clone https://github.com/cskwork/skill-usage-stats.git
cd skill-usage-stats

# install both skills
cp -R skills/skill-usage-stats ~/.claude/skills/
cp -R skills/skill-cleanup     ~/.claude/skills/

Windows (PowerShell)

# clone
git clone https://github.com/cskwork/skill-usage-stats.git
cd skill-usage-stats

# install both skills
Copy-Item -Recurse skills/skill-usage-stats $HOME\.claude\skills\
Copy-Item -Recurse skills/skill-cleanup     $HOME\.claude\skills\

Run the analyzer

analyze.py

# generate and open the HTML dashboard
python3 ~/.claude/skills/skill-usage-stats/analyze.py

# optional flags
#   --days N           only count last N days
#   --project <str>   restrict to matching cwd
#   --out <path>      output path (default: ~/.claude/skill-stats.html)
#   --no-open         write only, do not open browser

skill-cleanup

Archive workflow

skill-cleanup never deletes skills. Claude Code skills are moved under ~/.claude/skills-archive/<source>/<name>/ and Codex skills under ~/.codex/skills-archive/<source>/<name>/; either way SKILL.md is renamed to SKILL.md.archived. Because the harness discovers skills only by locating SKILL.md, the renamed file stops being auto-loaded while every other file remains intact and recoverable.

A .archived-meta.json file is written next to each archived skill recording the original path, archive date, and the stats-report reason. The tool refuses to operate on ~/.claude/plugins/cache/... paths, which are managed by the marketplace and would be re-installed automatically.

By default the tool runs in dry-run mode and prints a preview of every move. Pass --apply to commit. Restore any skill with a single command.

archive.py

# dry-run by default — preview only
python3 ~/.claude/skills/skill-cleanup/archive.py

# commit the moves
python3 ~/.claude/skills/skill-cleanup/archive.py --apply

# also archive REVIEW-verdict skills older than 90d
python3 ~/.claude/skills/skill-cleanup/archive.py \
        --verdict DELETE,REVIEW --days 90 --apply

# restrict to one source
python3 ~/.claude/skills/skill-cleanup/archive.py \
        --source claude-project --apply

# list archived skills
python3 ~/.claude/skills/skill-cleanup/archive.py list-archive

# restore a skill
python3 ~/.claude/skills/skill-cleanup/archive.py restore reddit-poster

Audit your Claude Codeskill catalog.