# Skill Use Counter

# Skill Use Counter

**Owner:** CodeCraft
**Implemented:** 2026-04-17 (Hive Activation Phase 3 T7 + T8)
**Hook:** `~/.claude/hooks/skill-use-counter.sh`
**Viewer:** `~/system/tools/skill-usage.js`
**Audit:** `~/system/tools/skill-audit-report.sh` (weekly)

## Purpose

Before T7, `skill-registry.db.use_count` stayed at 0 forever. We had 76 skills on disk and no idea which were alive, which were dead, or which to retire.

Now: every Skill tool invocation increments `use_count`. Once a week an audit report lists top used + dead candidates.

## Hook wiring

Registered in `~/.claude/settings.json` under `PostToolUse`:

```json
{
  "matcher": "Skill|mcp__skill",
  "hooks": [
    {"type": "command", "command": "bash ~/.claude/hooks/skill-use-counter.sh", "async": true}
  ]
}
```

The hook reads the tool invocation JSON from stdin, extracts the skill name, runs:

```sql
UPDATE skills SET use_count = use_count + 1 WHERE name = '<skill>';
```

Never blocks: exits 0 even if the DB is missing. SQL injection safe (single quotes are doubled before the sqlite3 call).

## Logs

Every increment appends a line to `~/system/logs/skill-use.log`:

```
2026-04-17T00:42:13Z SKILL=sync
2026-04-17T00:43:01Z SKILL=build
```

## Reading usage

```bash
# Top 20 used
node ~/system/tools/skill-usage.js

# All (including 0-count)
node ~/system/tools/skill-usage.js --all

# Retirement candidates (0 uses, > 30 days old)
node ~/system/tools/skill-usage.js --dead

# Custom window
node ~/system/tools/skill-usage.js --dead --days 60
```

## Weekly audit

`com.alai.skill-audit.plist` runs every Monday 07:00 CEST, writes `~/system/reports/skill-audit-<date>.md` with:
- total skills
- top 20 used (name, category, uses)
- retirement candidates (0 uses, > 30 days old)
- recommendation section — human review required

**Week 1 is bootstrap only** — every skill was registered at `use_count=0`, so all show up as candidates. Wait for week 2+ to make real retirement decisions.

## What to do with retirement candidates

Three options — pick per skill:

1. **Keep** — valuable but under-discovered. Improve its `description`/`trigger` in the registry so agents find it.
2. **Deprecate** — keep file on disk for reference but hide from discovery: `UPDATE skills SET active=0 WHERE name='X'`.
3. **Remove** — delete directory + registry row. Only if truly obsolete.

The audit report is read-only. No auto-retirement.

## Known issues

- The hook doesn't increment when a skill is invoked indirectly (skill-within-skill). Acceptable for now — top-level usage is the signal that matters.
- `use_count` is cumulative since 2026-04-17. No time-windowed counter yet. If you need "uses in last N days", grep `~/system/logs/skill-use.log`.