skills-stats

Track and query Claude Code skill usage frequency from the command line.

Every time Claude Code invokes a skill — whether you type /skill-name explicitly or Claude matches a trigger phrase automatically — skills-stats records it. Then you can see which skills you actually use, how often, and when you last used them.

Installation

npm install -g skills-stats

Then install the hook so skills-stats starts recording:

skills-stats install

This adds a PostToolUse hook to your global ~/.claude/settings.json. A backup (.bak) is created automatically.

To install only for the current project:

skills-stats install --local

Usage

View statistics

# All skills, sorted by usage count (highest first)
skills-stats

# Top 5 most-used skills
skills-stats --top 5

# JSON output
skills-stats --json

# Relative timestamps ("3 hours ago" instead of "2026-07-11 15:08")
skills-stats --relative

Filter by time range

# Skills used in the last 7 days
skills-stats --since 7d

# Skills used in the last 24 hours
skills-stats --since 24h

# Skills used since a specific date
skills-stats --since 2026-07-01

# Skills used within a date range
skills-stats --since 2026-07-01 --until 2026-07-11

Supported duration units: s (seconds), m / min (minutes), h (hours), d (days), w (weeks).

Filter by project

skills-stats --project /Users/you/my-project

Include unused skills

# Show all installed skills, including ones never invoked
skills-stats --all

Uninstall

# Remove the hook (stops recording)
skills-stats uninstall

# Remove from project-local settings
skills-stats uninstall --local

How it works

1. skills-stats install injects two hooks into your Claude Code settings:

   • PostToolUse:Skill — fires when Claude invokes a skill via the Skill tool (automatic trigger phrase matching or model-initiated).
   • UserPromptSubmit — fires when you type /skill-name directly in the prompt.

2. Recording: Each hook runs a skills-stats record* command that reads the skill name and context from stdin JSON and writes a row to a SQLite database at ~/.claude/skills-usage/skills.db.

3. Querying: skills-stats (without arguments) queries the database, aggregates by skill name, and displays a table sorted by usage count.

Both hooks are designed to fail silently — if recording fails for any reason, it logs to stderr and exits cleanly without interrupting your Claude Code session.

Data storage

All data is stored locally in:

~/.claude/skills-usage/skills.db

The database uses WAL mode for safe concurrent access from multiple Claude Code sessions.

Schema

skill_events (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    skill_name  TEXT NOT NULL,
    invoked_at  INTEGER NOT NULL,  -- epoch ms
    project     TEXT NOT NULL DEFAULT '',
    session_id  TEXT NOT NULL DEFAULT ''
)

Commands

| Command | Description | |---|---| | skills-stats | Show usage statistics (default) | | skills-stats record | Record a skill event (called by hook) | | skills-stats install | Install the PostToolUse hook | | skills-stats uninstall | Remove the PostToolUse hook | | skills-stats --help | Show help |

Options (for show / default command)

| Option | Description | |---|---| | -t, --top <n> | Show top N skills | | --since <duration> | Filter since a time (e.g., 7d, 24h, 2026-07-01) | | --until <duration> | Filter until a time | | --project <path> | Filter by project directory | | --all | Include installed skills with zero usage | | --json | Output as JSON | | --relative | Show relative timestamps |

Requirements

• Node.js >= 18
• Claude Code (any recent version with hook support)

License

MIT