@crafter/skillkit 0.1.2 → 0.1.4

package/README.md

@@ -0,0 +1,113 @@
+# skillkit
+
+Local-first analytics for AI agent skills. Track usage, measure context budget, and prune what you don't use.
+
+## Why
+
+AI coding agents load skills into their context window on every session. More skills = less room for your actual code. But which skills do you actually use? Which ones are wasting context budget?
+
+**skillkit** answers these questions by scanning your session files, tracking invocations, and surfacing actionable insights - all locally on your machine.
+
+## Quick Start
+
+```bash
+npx @crafter/skillkit scan
+npx @crafter/skillkit stats
+npx @crafter/skillkit health
+```
+
+Or install globally:
+
+```bash
+npm i -g @crafter/skillkit
+skillkit scan
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `skillkit scan` | Discover installed skills and index session data |
+| `skillkit list` | List installed skills with size and context budget |
+| `skillkit stats` | Usage analytics with sparklines (last 30 days) |
+| `skillkit health` | Health check: unused skills, context budget, DB |
+| `skillkit prune` | Remove unused skills to reclaim context budget |
+
+Install skills via [skills.sh](https://skills.sh): `npx skills add <owner/repo>`
+
+## How It Works
+
+### Scan
+
+Discovers skills from `~/.claude/skills/` and indexes session files from `~/.claude/projects/`. Detects whether each skill was installed via skills.sh or manually.
+
+```
+$ skillkit scan
+  Scanning ~/.claude/skills/ ...
+  Found 12 skills (8 via skills.sh, 4 manual)
+  Scanning sessions...
+  Indexed 211 sessions · 1,847 invocations
+
+  Ready. Run skillkit stats to see usage.
+```
+
+### Stats
+
+Parses JSONL session files for `Skill` tool_use blocks and shows sparkline trends.
+
+```
+$ skillkit stats
+  SKILL           ████████████████████  42  ▂▃▅▇█▆▅▇█
+  commit          ████████████████████  42  ▂▃▅▇█▆▅▇█
+  review          ████████████████      38  ▁▃▅▆▇▇▆▅▃
+  deploy          ████████████          27  ▁▁▂▃▅▇█▇▅
+```
+
+### Health
+
+Checks metadata budget usage (name + description loaded at startup) and flags unused skills.
+
+```
+$ skillkit health
+  [████████░░] 78% metadata budget (12.5K / 16.0K)
+  ! 3 skills unused in 30d — run skillkit prune
+```
+
+### Prune
+
+Removes skills that haven't been used in the last 30 days.
+
+```
+$ skillkit prune
+  x scaffold (0.9K)
+  x lint (2.1K)
+
+  2 skills · 3.0K context reclaimable
+
+  Run with --yes to confirm deletion.
+```
+
+## Data Storage
+
+All data stays on your machine. No telemetry. No signup.
+
+| Path | Purpose |
+|------|---------|
+| `~/.skillkit/analytics.db` | SQLite database with invocation history |
+| `~/.claude/skills/` | Installed skills (read-only) |
+| `~/.claude/projects/**/*.jsonl` | Session files (read-only) |
+
+## Supported Agents
+
+Works with any agent that logs tool use in JSONL session files:
+
+- Claude Code
+- Cursor
+- Codex
+- VS Code (via extensions)
+- Windsurf
+- Gemini CLI
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crafter/skillkit",
-	"version": "0.1.2",
+	"version": "0.1.4",
 	"description": "Local-first analytics for AI agent skills. Track usage, measure context budget, and prune what you don't use.",
 	"type": "module",
 	"bin": {

package/src/bin.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { bold, cyan, dim, yellow } from "./tui/colors";
 
-const VERSION = "0.1.2";
+const VERSION = "0.1.4";
 
 function printHelp(): void {
 	console.log(`

package/src/commands/health.ts

@@ -5,7 +5,6 @@ import { getTopSkills } from "../db/queries";
 import { getDb } from "../db/schema";
 import { scanInstalledSkills } from "../scanner/skills";
 import { bold, dim, green, red, yellow } from "../tui/colors";
-import { healthGauge } from "../tui/health";
 
 const METADATA_BUDGET = 16000;
 const BODY_LINE_LIMIT = 500;
@@ -31,7 +30,7 @@ function parseFrontmatter(content: string): {
 	if (!match)
 		return { name: "", description: "", bodyLines: content.split("\n").length };
 
-	const yaml = match[1];
+	const yaml = match[1] ?? "";
 	const body = content.slice(match[0].length);
 	const bodyLines = body.trim() ? body.trim().split("\n").length : 0;
 
@@ -39,10 +38,11 @@ function parseFrontmatter(content: string): {
 	let description = "";
 
 	const nameMatch = yaml.match(/^name:\s*(.+)$/m);
-	if (nameMatch) name = nameMatch[1].trim().replace(/^["']|["']$/g, "");
+	if (nameMatch?.[1]) name = nameMatch[1].trim().replace(/^["']|["']$/g, "");
 
 	const descMatch = yaml.match(/^description:\s*(.+)$/m);
-	if (descMatch) description = descMatch[1].trim().replace(/^["']|["']$/g, "");
+	if (descMatch?.[1])
+		description = descMatch[1].trim().replace(/^["']|["']$/g, "");
 
 	return { name, description, bodyLines };
 }
@@ -138,28 +138,26 @@ export async function runHealth(): Promise<void> {
 	}
 
 	console.log();
-	const gaugeStr = healthGauge(100 - metadataPct);
 	const metaKb = (totalMetadataChars / 1000).toFixed(1);
 	const budgetKb = (METADATA_BUDGET / 1000).toFixed(1);
 
-	if (metadataPct >= 90) {
-		console.log(
-			`  ${red("●")} Metadata budget: ${metadataPct}% (${metaKb}K / ${budgetKb}K chars)`,
-		);
-	} else if (metadataPct >= 70) {
-		console.log(
-			`  ${yellow("●")} Metadata budget: ${metadataPct}% (${metaKb}K / ${budgetKb}K chars)`,
-		);
-	} else {
-		console.log(
-			info(
-				`Metadata budget: ${metadataPct}% (${metaKb}K / ${budgetKb}K chars)`,
-			),
-		);
-	}
-	console.log(`    ${gaugeStr}`);
+	const filled = Math.round(Math.min(metadataPct, 100) / 10);
+	const empty = 10 - filled;
+	const barFill = "█".repeat(filled);
+	const barEmpty = "░".repeat(empty);
+	const colorBar =
+		metadataPct >= 90
+			? red(barFill)
+			: metadataPct >= 70
+				? yellow(barFill)
+				: green(barFill);
+	const bar = `[${colorBar}${dim(barEmpty)}]`;
+
+	console.log(
+		`  ${bar} ${bold(`${metadataPct}%`)} metadata budget ${dim(`(${metaKb}K / ${budgetKb}K)`)}`,
+	);
 	console.log(
-		`    ${dim(`Names + descriptions loaded at startup (2% of context window)`)}`,
+		`    ${dim("name + description of each skill, loaded at startup")}`,
 	);
 
 	const bodyKb = (totalBodyChars / 1000).toFixed(1);