skill-analyzer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mathbullet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# skill-analyzer
+
+Analyze your Claude Code skill library: usage frequency, dead skills, and description budget consumption.
+
+## Quick Start
+
+```bash
+npx skill-analyzer report
+```
+
+## Install as Claude Code Plugin
+
+```
+/plugin add mathbullet/skill-analyzer
+```
+
+Then use `/skill-analyzer` in Claude Code.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `report` | Full analysis report (default) |
+| `usage` | Skill usage frequency |
+| `dead` | Unused skills |
+| `budget` | Description budget consumption |
+
+## Options
+
+- `--days N` — Limit to last N days
+- `--json` — JSON output
+- `--skills-dir <path>` — Skills directory (default: `~/.claude/skills`)
+- `--logs-dir <path>` — Logs directory (default: `~/.claude/projects`)
+
+## What it does
+
+- Scans `~/.claude/projects/**/*.jsonl` session logs for `Skill` tool invocations
+- Parses `~/.claude/skills/*/SKILL.md` frontmatter for description budget calculation
+- Normalizes skill names (e.g., `superpowers:brainstorming` → `brainstorming`)
+- Reports unused skills and their budget cost for cleanup decisions

package/dist/budget.d.ts

@@ -0,0 +1 @@
+export declare function budgetCommand(args: string[]): void;

package/dist/budget.js

@@ -0,0 +1,45 @@
+import chalk from "chalk";
+import { getSkillsDir, loadSkillRegistry } from "./registry.js";
+import { sectionHeader, keyValue, budgetBar, makeTable } from "./formatter.js";
+const OVERHEAD_PER_SKILL = 109;
+const DEFAULT_BUDGET = 16_000;
+export function budgetCommand(args) {
+    const skillsDir = getSkillsDir(args);
+    const skills = loadSkillRegistry(skillsDir);
+    const budget = parseInt(process.env["SLASH_COMMAND_TOOL_CHAR_BUDGET"] ?? String(DEFAULT_BUDGET), 10);
+    const isJson = args.includes("--json");
+    const entries = skills
+        .map((s) => ({
+        name: s.name,
+        descriptionLength: s.descriptionLength,
+        cost: s.descriptionLength + OVERHEAD_PER_SKILL,
+    }))
+        .sort((a, b) => b.cost - a.cost);
+    const totalCost = entries.reduce((sum, e) => sum + e.cost, 0);
+    if (isJson) {
+        console.log(JSON.stringify({ budget, totalCost, entries }, null, 2));
+        return;
+    }
+    const overBudget = totalCost > budget;
+    sectionHeader("Description Budget", overBudget ? "OVER BUDGET" : undefined);
+    keyValue([
+        ["Budget:", budgetBar(totalCost, budget)],
+        [
+            "Used:",
+            `${totalCost.toLocaleString()} / ${budget.toLocaleString()} chars`,
+        ],
+        [
+            "Remaining:",
+            overBudget
+                ? chalk.red(`-${(totalCost - budget).toLocaleString()} chars`)
+                : chalk.green(`${(budget - totalCost).toLocaleString()} chars`),
+        ],
+        ["Skills:", `${entries.length} (${OVERHEAD_PER_SKILL} chars overhead each)`],
+    ]);
+    makeTable({
+        head: ["#", "Skill", "Description Chars", "Total Chars"],
+        colAligns: ["right", "left", "right", "right"],
+        rows: entries.map((e, i) => [i + 1, e.name, e.descriptionLength, e.cost]),
+    });
+    console.log();
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function run(args: string[]): void;

package/dist/cli.js

@@ -0,0 +1,39 @@
+import { budgetCommand } from "./budget.js";
+import { usageCommand } from "./usage.js";
+import { deadCommand } from "./dead.js";
+import { reportCommand } from "./report.js";
+export function run(args) {
+    const command = args[0] ?? "report";
+    switch (command) {
+        case "budget":
+            budgetCommand(args.slice(1));
+            break;
+        case "usage":
+            usageCommand(args.slice(1));
+            break;
+        case "dead":
+            deadCommand(args.slice(1));
+            break;
+        case "report":
+            reportCommand(args.slice(1));
+            break;
+        default:
+            printHelp();
+    }
+}
+function printHelp() {
+    console.log(`skill-analyzer - Analyze your Claude Code skill library
+
+Usage: skill-analyzer <command> [options]
+
+Commands:
+  report    Full analysis report (default)
+  usage     Skill usage frequency
+  dead      Unused skills
+  budget    Description budget consumption
+
+Options:
+  --skills-dir <path>  Skills directory (default: ~/.claude/skills)
+  --json               Output as JSON
+  --help               Show this help`);
+}

package/dist/dead.d.ts

@@ -0,0 +1 @@
+export declare function deadCommand(args: string[]): void;

package/dist/dead.js

@@ -0,0 +1,47 @@
+import chalk from "chalk";
+import { getSkillsDir, loadSkillRegistry } from "./registry.js";
+import { getLogsDir, scanSessions, aggregateUsage } from "./scanner.js";
+import { sectionHeader, keyValue, makeTable } from "./formatter.js";
+export function deadCommand(args) {
+    const skillsDir = getSkillsDir(args);
+    const logsDir = getLogsDir(args);
+    const daysIdx = args.indexOf("--days");
+    const days = daysIdx !== -1 ? parseInt(args[daysIdx + 1], 10) : undefined;
+    const isJson = args.includes("--json");
+    const registry = loadSkillRegistry(skillsDir);
+    const invocations = scanSessions(logsDir, days);
+    const usage = aggregateUsage(invocations);
+    const usedSkills = new Set(usage.map((u) => u.skill));
+    const deadSkills = registry.filter((s) => !usedSkills.has(s.name));
+    if (isJson) {
+        console.log(JSON.stringify({ deadSkills: deadSkills.map((s) => s.name), count: deadSkills.length }, null, 2));
+        return;
+    }
+    const period = days ? `last ${days} days` : "all time";
+    sectionHeader(`Dead Skills (${period})`);
+    const totalWaste = deadSkills.reduce((sum, s) => sum + s.descriptionLength + 109, 0);
+    keyValue([
+        ["Dead:", `${deadSkills.length} of ${registry.length} local skills`],
+        [
+            "Savings:",
+            deadSkills.length > 0
+                ? chalk.yellow(`${totalWaste.toLocaleString()} chars recoverable`)
+                : chalk.green("None needed"),
+        ],
+    ]);
+    if (deadSkills.length === 0) {
+        console.log(chalk.green("  All skills have been used at least once.\n"));
+        return;
+    }
+    makeTable({
+        head: ["#", "Skill", "Description Chars", "Total Chars"],
+        colAligns: ["right", "left", "right", "right"],
+        rows: deadSkills.map((s, i) => [
+            i + 1,
+            chalk.red(s.name),
+            s.descriptionLength,
+            s.descriptionLength + 109,
+        ]),
+    });
+    console.log();
+}

package/dist/formatter.d.ts

@@ -0,0 +1,8 @@
+export declare function sectionHeader(title: string, warning?: string): void;
+export declare function keyValue(pairs: [string, string][]): void;
+export declare function budgetBar(used: number, total: number): string;
+export declare function makeTable(options: {
+    head: string[];
+    rows: (string | number)[][];
+    colAligns?: ("left" | "right" | "middle")[];
+}): void;

package/dist/formatter.js

@@ -0,0 +1,57 @@
+import chalk from "chalk";
+import Table from "cli-table3";
+export function sectionHeader(title, warning) {
+    const header = warning
+        ? chalk.red.bold(`  ${title}  ${warning}`)
+        : chalk.cyan.bold(`  ${title}`);
+    console.log(`\n${header}\n`);
+}
+export function keyValue(pairs) {
+    for (const [key, value] of pairs) {
+        console.log(`  ${chalk.dim(key)}  ${value}`);
+    }
+    console.log();
+}
+export function budgetBar(used, total) {
+    const pct = used / total;
+    const width = 30;
+    const filled = Math.round(pct * width);
+    const empty = width - filled;
+    const color = pct > 1 ? chalk.red : pct > 0.7 ? chalk.yellow : chalk.green;
+    const bar = color("█".repeat(filled)) + chalk.dim("░".repeat(empty));
+    const label = color(`${(pct * 100).toFixed(0)}%`);
+    return `${bar} ${label}`;
+}
+export function makeTable(options) {
+    const table = new Table({
+        head: options.head.map((h) => chalk.bold(h)),
+        colAligns: options.colAligns,
+        style: {
+            head: [],
+            border: [],
+            "padding-left": 1,
+            "padding-right": 1,
+        },
+        chars: {
+            top: "─",
+            "top-mid": "┬",
+            "top-left": "┌",
+            "top-right": "┐",
+            bottom: "─",
+            "bottom-mid": "┴",
+            "bottom-left": "└",
+            "bottom-right": "┘",
+            left: "│",
+            "left-mid": "├",
+            mid: "─",
+            "mid-mid": "┼",
+            right: "│",
+            "right-mid": "┤",
+            middle: "│",
+        },
+    });
+    for (const row of options.rows) {
+        table.push(row.map(String));
+    }
+    console.log(table.toString());
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "./cli.js";
+run(process.argv.slice(2));

package/dist/normalizer.d.ts

@@ -0,0 +1 @@
+export declare function normalizeSkillName(input: Record<string, unknown>): string | null;

package/dist/normalizer.js

@@ -0,0 +1,11 @@
+export function normalizeSkillName(input) {
+    const raw = (input["skill"] ?? input["skillName"] ?? input["skill_name"]);
+    if (!raw || typeof raw !== "string")
+        return null;
+    // Strip plugin prefix: "superpowers:brainstorming" → "brainstorming"
+    const colonIdx = raw.indexOf(":");
+    if (colonIdx !== -1) {
+        return raw.slice(colonIdx + 1);
+    }
+    return raw;
+}

package/dist/registry.d.ts

@@ -0,0 +1,8 @@
+export interface SkillEntry {
+    name: string;
+    description: string;
+    descriptionLength: number;
+    path: string;
+}
+export declare function getSkillsDir(args: string[]): string;
+export declare function loadSkillRegistry(skillsDir: string): SkillEntry[];

package/dist/registry.js

@@ -0,0 +1,51 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+export function getSkillsDir(args) {
+    const idx = args.indexOf("--skills-dir");
+    if (idx !== -1 && args[idx + 1]) {
+        return args[idx + 1];
+    }
+    return join(homedir(), ".claude", "skills");
+}
+export function loadSkillRegistry(skillsDir) {
+    const entries = [];
+    let dirs;
+    try {
+        dirs = readdirSync(skillsDir);
+    }
+    catch {
+        console.error(`Cannot read skills directory: ${skillsDir}`);
+        process.exit(1);
+    }
+    for (const dir of dirs) {
+        const skillMdPath = join(skillsDir, dir, "SKILL.md");
+        try {
+            statSync(skillMdPath);
+        }
+        catch {
+            continue;
+        }
+        const content = readFileSync(skillMdPath, "utf-8");
+        const { name, description } = parseFrontmatter(content, dir);
+        entries.push({
+            name,
+            description,
+            descriptionLength: description.length,
+            path: skillMdPath,
+        });
+    }
+    return entries;
+}
+function parseFrontmatter(content, fallbackName) {
+    const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!match) {
+        return { name: fallbackName, description: "" };
+    }
+    const frontmatter = match[1];
+    const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+    const name = nameMatch ? nameMatch[1].trim() : fallbackName;
+    const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+    const description = descMatch ? descMatch[1].trim() : "";
+    return { name, description };
+}

package/dist/report.d.ts

@@ -0,0 +1 @@
+export declare function reportCommand(args: string[]): void;

package/dist/report.js

@@ -0,0 +1,41 @@
+import { getSkillsDir, loadSkillRegistry } from "./registry.js";
+import { getLogsDir, scanSessions, aggregateUsage } from "./scanner.js";
+import { budgetCommand } from "./budget.js";
+import { usageCommand } from "./usage.js";
+import { deadCommand } from "./dead.js";
+export function reportCommand(args) {
+    const isJson = args.includes("--json");
+    if (isJson) {
+        reportJson(args);
+        return;
+    }
+    // Just run all three in sequence
+    usageCommand(args);
+    deadCommand(args);
+    budgetCommand(args);
+}
+function reportJson(args) {
+    const skillsDir = getSkillsDir(args);
+    const logsDir = getLogsDir(args);
+    const daysIdx = args.indexOf("--days");
+    const days = daysIdx !== -1 ? parseInt(args[daysIdx + 1], 10) : undefined;
+    const registry = loadSkillRegistry(skillsDir);
+    const invocations = scanSessions(logsDir, days);
+    const usage = aggregateUsage(invocations);
+    const usedSkills = new Set(usage.map((u) => u.skill));
+    const deadSkills = registry.filter((s) => !usedSkills.has(s.name)).map((s) => s.name);
+    const budget = parseInt(process.env["SLASH_COMMAND_TOOL_CHAR_BUDGET"] ?? "16000", 10);
+    const budgetEntries = registry
+        .map((s) => ({
+        name: s.name,
+        descriptionLength: s.descriptionLength,
+        cost: s.descriptionLength + 109,
+    }))
+        .sort((a, b) => b.cost - a.cost);
+    const totalCost = budgetEntries.reduce((sum, e) => sum + e.cost, 0);
+    console.log(JSON.stringify({
+        usage: { totalInvocations: invocations.length, skills: usage },
+        dead: { count: deadSkills.length, skills: deadSkills },
+        budget: { limit: budget, totalCost, entries: budgetEntries },
+    }, null, 2));
+}

package/dist/scanner.d.ts

@@ -0,0 +1,13 @@
+export interface SkillInvocation {
+    skill: string;
+    timestamp: string;
+    sessionId: string;
+}
+export interface UsageResult {
+    skill: string;
+    count: number;
+    lastUsed: string;
+}
+export declare function getLogsDir(args: string[]): string;
+export declare function scanSessions(logsDir: string, daysLimit?: number): SkillInvocation[];
+export declare function aggregateUsage(invocations: SkillInvocation[]): UsageResult[];

package/dist/scanner.js

@@ -0,0 +1,114 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { normalizeSkillName } from "./normalizer.js";
+export function getLogsDir(args) {
+    const idx = args.indexOf("--logs-dir");
+    if (idx !== -1 && args[idx + 1]) {
+        return args[idx + 1];
+    }
+    return join(homedir(), ".claude", "projects");
+}
+export function scanSessions(logsDir, daysLimit) {
+    const invocations = [];
+    const cutoff = daysLimit
+        ? new Date(Date.now() - daysLimit * 86_400_000)
+        : null;
+    let projectDirs;
+    try {
+        projectDirs = readdirSync(logsDir);
+    }
+    catch {
+        console.error(`Cannot read logs directory: ${logsDir}`);
+        process.exit(1);
+    }
+    for (const projectDir of projectDirs) {
+        const projectPath = join(logsDir, projectDir);
+        try {
+            if (!statSync(projectPath).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        let files;
+        try {
+            files = readdirSync(projectPath).filter((f) => f.endsWith(".jsonl"));
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            const filePath = join(projectPath, file);
+            // Quick mtime filter when --days is specified
+            if (cutoff) {
+                try {
+                    const mtime = statSync(filePath).mtime;
+                    if (mtime < cutoff)
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+            }
+            const content = readFileSync(filePath, "utf-8");
+            for (const line of content.split("\n")) {
+                if (!line.includes('"Skill"'))
+                    continue;
+                try {
+                    const obj = JSON.parse(line);
+                    const msg = obj["message"];
+                    if (!msg)
+                        continue;
+                    const contentArr = msg["content"];
+                    if (!Array.isArray(contentArr))
+                        continue;
+                    for (const block of contentArr) {
+                        if (typeof block === "object" &&
+                            block !== null &&
+                            block["type"] === "tool_use" &&
+                            block["name"] === "Skill") {
+                            const input = block["input"];
+                            if (!input)
+                                continue;
+                            const name = normalizeSkillName(input);
+                            if (!name)
+                                continue;
+                            invocations.push({
+                                skill: name,
+                                timestamp: obj["timestamp"] ?? "",
+                                sessionId: obj["sessionId"] ?? "",
+                            });
+                        }
+                    }
+                }
+                catch {
+                    // Skip malformed lines
+                }
+            }
+        }
+    }
+    return invocations;
+}
+export function aggregateUsage(invocations) {
+    const map = new Map();
+    for (const inv of invocations) {
+        const existing = map.get(inv.skill);
+        if (!existing) {
+            map.set(inv.skill, { count: 1, lastUsed: inv.timestamp });
+        }
+        else {
+            existing.count++;
+            if (inv.timestamp > existing.lastUsed) {
+                existing.lastUsed = inv.timestamp;
+            }
+        }
+    }
+    return Array.from(map.entries())
+        .map(([skill, data]) => ({
+        skill,
+        count: data.count,
+        lastUsed: data.lastUsed,
+    }))
+        .sort((a, b) => b.count - a.count);
+}

package/dist/usage.d.ts

@@ -0,0 +1 @@
+export declare function usageCommand(args: string[]): void;

package/dist/usage.js

@@ -0,0 +1,36 @@
+import chalk from "chalk";
+import { getLogsDir, scanSessions, aggregateUsage } from "./scanner.js";
+import { sectionHeader, keyValue, makeTable } from "./formatter.js";
+export function usageCommand(args) {
+    const logsDir = getLogsDir(args);
+    const daysIdx = args.indexOf("--days");
+    const days = daysIdx !== -1 ? parseInt(args[daysIdx + 1], 10) : undefined;
+    const isJson = args.includes("--json");
+    const invocations = scanSessions(logsDir, days);
+    const usage = aggregateUsage(invocations);
+    if (isJson) {
+        console.log(JSON.stringify({ totalInvocations: invocations.length, skills: usage }, null, 2));
+        return;
+    }
+    const period = days ? `last ${days} days` : "all time";
+    sectionHeader(`Skill Usage (${period})`);
+    keyValue([
+        ["Invocations:", String(invocations.length)],
+        ["Unique skills:", String(usage.length)],
+    ]);
+    if (usage.length === 0) {
+        console.log(chalk.dim("  No skill invocations found.\n"));
+        return;
+    }
+    makeTable({
+        head: ["#", "Skill", "Count", "Last Used"],
+        colAligns: ["right", "left", "right", "left"],
+        rows: usage.map((u, i) => [
+            i + 1,
+            u.skill,
+            u.count,
+            u.lastUsed ? u.lastUsed.slice(0, 10) : "unknown",
+        ]),
+    });
+    console.log();
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "skill-analyzer",
+  "version": "0.1.0",
+  "description": "Analyze Claude Code skill library: usage frequency, dead skills, description budget consumption",
+  "type": "module",
+  "bin": {
+    "skill-analyzer": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "claude-code",
+    "skills",
+    "analyzer",
+    "cli"
+  ],
+  "author": "mathbullet",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5"
+  }
+}