Skill Usage Counter Plugin

Automatically track which skills are used in your Claude Code projects. Get insights into usage patterns, frequency, and trends.

Features

• Automatic Tracking: Records skill usage whenever a SKILL.md file is read
• Per-Project Statistics: Each project maintains its own usage statistics in .claude/skill-stats.json
• Detailed Metrics: Tracks total uses, first use, last use, and daily breakdown
• Easy Viewing: Use /skill-stats command to see formatted statistics
• Zero Configuration: Works out of the box after installation

How It Works

The plugin uses Claude Code's hook system to intercept Read tool calls:

1. When you run a skill or Claude reads a SKILL.md file, the hook captures this event
2. The skill name is extracted from the file path
3. Statistics are updated in .claude/skill-stats.json in your project's .claude directory
4. Use /skill-stats to view a formatted table of usage data

Installation

Option 1: Install from GitHub (Recommended)

/plugin install skill-usage-counter@github:landicefu/skill-usage-counter

Option 2: Install from npm

/plugin install skill-usage-counter@npm:@landicefu/skill-usage-counter

Option 3: Install Locally for Development

/plugin marketplace add /path/to/this/plugin
/plugin install skill-usage-counter@skill-usage-counter-marketplace

Usage

View Statistics

/skill-stats

This displays a table with:

• Skill Name: The name of the skill
• Total Uses: Total number of times the skill was used
• First Used: Date when the skill was first used
• Last Used: Date when the skill was last used
• Days Active: Number of unique days the skill was used

Data Location

Statistics are stored in:

<project-root>/.claude/skill-stats.json

Example file structure:

{
  "my-analyzer": {
    "total": 12,
    "firstUsed": "2024-03-15T10:30:45.123Z",
    "lastUsed": "2024-03-27T14:22:10.456Z",
    "byDate": {
      "2024-03-15": 2,
      "2024-03-20": 3,
      "2024-03-22": 5,
      "2024-03-27": 2
    }
  },
  "checker": {
    "total": 8,
    "firstUsed": "2024-03-20T09:15:30.789Z",
    "lastUsed": "2024-03-27T16:45:20.012Z",
    "byDate": {
      "2024-03-20": 2,
      "2024-03-25": 4,
      "2024-03-27": 2
    }
  }
}

Understanding the Statistics

Total Uses

The cumulative count of how many times each skill has been read/used in the project.

First Used / Last Used

Timestamps (ISO 8601 format) showing when the skill was first and last accessed.

By Date Breakdown

Daily usage counts (byDate object) help you see:

• Usage patterns over time
• Active development periods
• Skill adoption trends

Days Active

The number of unique dates a skill was used, indicating how actively a skill is being utilized.

Privacy & Storage

• Local Storage Only: All statistics are stored locally in your project's .claude directory
• No Remote Access: The plugin never sends data to external servers
• Per-Project: Statistics are isolated per project - no global tracking
• No Personal Data: Only tracks skill names and usage timestamps

Examples

Find Your Most-Used Skills

/skill-stats
# Shows skills sorted by usage frequency

Check Recent Activity

Look at the "Last Used" column to see which skills were recently accessed.

Identify Inactive Skills

Skills that haven't been used recently (old "Last Used" date) may be candidates for archival or refactoring.

Track Development Sessions

The "Days Active" column shows how many days a skill was used - useful for understanding project engagement.

Troubleshooting

Statistics Not Being Recorded

1. Check permissions: Ensure .claude directory is writable
2. Verify SKILL.md: Make sure you're actually reading .SKILL.md files
3. Check hook status: Run /plugin list to confirm the plugin is enabled

Cannot Read skill-stats.json

The file may be corrupted. You can:

1. Delete .claude/skill-stats.json to start fresh
2. The tracker will recreate it on the next skill usage

Plugin Not Installing

• Ensure you're using Claude Code v1.0+
• Check that the marketplace URL is correct
• Verify the plugin.json has valid JSON syntax

Contributing

To improve this plugin:

1. Fork the repository
2. Make your changes
3. Test locally: /plugin marketplace add ./path/to/fork
4. Submit a pull request

License

MIT - Feel free to use and modify for your needs.

Feedback

Have suggestions or found a bug? Please:

1. Check existing GitHub issues
2. Create a new issue with:
   • Your Claude Code version
   • The plugin version you're using
   • Steps to reproduce (if it's a bug)
   • Your expected vs. actual behavior

Support

For help with Claude Code plugins, see the official documentation:

• Claude Code Plugins Guide
• Plugins Troubleshooting