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: 
 
 Keep — valuable but under-discovered. Improve its description / trigger in the registry so agents find it. 
 Deprecate — keep file on disk for reference but hide from discovery: UPDATE skills SET active=0 WHERE name='X' . 
 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 .