npm package: @landicefu/skill-usage-counter
Description: Track skill usage statistics per project in Claude Code
Author: Landice Fu
Latest version: 1.0.2

# 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)

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

### Option 2: Install from npm

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

### Option 3: Install Locally for Development

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

## Usage

### View Statistics

```bash
/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:
```json
{
  "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

```bash
/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](https://code.claude.com/docs/en/plugins)
- [Plugins Troubleshooting](https://code.claude.com/docs/en/plugins-reference#troubleshooting)