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:

{
  "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:

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

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