@crafter/skillkit 0.1.3 → 0.1.5

package/README.md

@@ -0,0 +1,112 @@
+# 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
+
+Scans skill directories for 15+ agents automatically:
+
+- Claude Code, Cursor, Codex, Windsurf, Gemini CLI
+- Cline, Roo Code, Continue, OpenCode, GitHub Copilot
+- OpenHands, Amp, Goose, Kilo Code, Trae
+
+Skills installed via [skills.sh](https://skills.sh) symlinks are deduplicated across agents.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crafter/skillkit",
-	"version": "0.1.3",
+	"version": "0.1.5",
 	"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.3";
+const VERSION = "0.1.5";
 
 function printHelp(): void {
 	console.log(`

package/src/commands/health.ts

@@ -3,7 +3,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { getTopSkills } from "../db/queries";
 import { getDb } from "../db/schema";
-import { scanInstalledSkills } from "../scanner/skills";
+import { getDetectedAgents, scanInstalledSkills } from "../scanner/skills";
 import { bold, dim, green, red, yellow } from "../tui/colors";
 
 const METADATA_BUDGET = 16000;
@@ -114,7 +114,9 @@ export async function runHealth(): Promise<void> {
 
 	console.log(`\n  ${bold("SKILLKIT HEALTH REPORT")}\n`);
 
-	console.log(check(`${skills.length} skills installed`));
+	const agents = getDetectedAgents();
+	console.log(check(`${skills.length} skills across ${agents.length} agents`));
+	console.log(dim(`    ${agents.join(", ")}`));
 
 	if (dbExists && hasDbData) {
 		console.log(

package/src/commands/list.ts

@@ -16,10 +16,15 @@ export function runList(): void {
 	const skills = scanInstalledSkills();
 
 	if (skills.length === 0) {
-		console.log("\n  No skills installed in ~/.claude/skills/\n");
+		console.log("\n  No skills found.\n");
 		return;
 	}
 
+	const agentCounts = new Map<string, number>();
+	for (const s of skills) {
+		agentCounts.set(s.agent, (agentCounts.get(s.agent) ?? 0) + 1);
+	}
+
 	const totalSize = skills.reduce((acc, s) => acc + s.size, 0);
 
 	console.log(`\n  ${bold(`INSTALLED SKILLS (${skills.length})`)}\n`);
@@ -40,7 +45,10 @@ export function runList(): void {
 		console.log(`  ${name}${desc}${size}`);
 	}
 
+	const agentSummary = [...agentCounts.entries()]
+		.map(([a, c]) => `${a} (${c})`)
+		.join(", ");
 	console.log(
-		`\n  ${dim(`Total: ${skills.length} skills | ${formatSize(totalSize)} context budget`)}\n`,
+		`\n  ${dim(`Total: ${skills.length} skills | ${formatSize(totalSize)} | ${agentSummary}`)}\n`,
 	);
 }

package/src/commands/scan.ts

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { upsertInstalledSkill } from "../db/queries";
 import { getDb } from "../db/schema";
 import { scanAllSessions } from "../scanner/index";
-import { scanInstalledSkills } from "../scanner/skills";
+import { getDetectedAgents, scanInstalledSkills } from "../scanner/skills";
 import { bold, cyan, dim } from "../tui/colors";
 
 function detectSource(skillPath: string): "skills.sh" | "manual" {
@@ -37,7 +37,12 @@ function countSessions(): number {
 export async function runScan(): Promise<void> {
 	const db = getDb();
 
-	console.log(`\n  ${dim("Scanning ~/.claude/skills/ ...")}`);
+	const agents = getDetectedAgents();
+	if (agents.length === 0) {
+		console.log(`\n  ${dim("No agent skill directories found.")}\n`);
+		return;
+	}
+	console.log(`\n  ${dim(`Scanning ${agents.length} agents: ${agents.join(", ")}`)}`);
 
 	const skills = scanInstalledSkills();
 

package/src/index.ts

@@ -13,7 +13,7 @@ export {
 } from "./db/queries";
 export { getDb } from "./db/schema";
 export { parseSessionFile, scanAllSessions } from "./scanner/index";
-export { scanInstalledSkills } from "./scanner/skills";
+export { getDetectedAgents, scanInstalledSkills } from "./scanner/skills";
 export type {
 	InstalledSkill,
 	SkillInvocation,

package/src/scanner/skills.ts

@@ -3,6 +3,24 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import type { InstalledSkill } from "../types";
 
+const AGENT_SKILL_PATHS: Array<{ agent: string; dir: string }> = [
+	{ agent: "Claude Code", dir: join(homedir(), ".claude", "skills") },
+	{ agent: "Cursor", dir: join(homedir(), ".cursor", "skills") },
+	{ agent: "Codex", dir: join(homedir(), ".codex", "skills") },
+	{ agent: "Windsurf", dir: join(homedir(), ".codeium", "windsurf", "skills") },
+	{ agent: "Gemini CLI", dir: join(homedir(), ".gemini", "skills") },
+	{ agent: "Cline", dir: join(homedir(), ".cline", "skills") },
+	{ agent: "Roo Code", dir: join(homedir(), ".roo", "skills") },
+	{ agent: "Continue", dir: join(homedir(), ".continue", "skills") },
+	{ agent: "OpenCode", dir: join(homedir(), ".config", "opencode", "skills") },
+	{ agent: "GitHub Copilot", dir: join(homedir(), ".copilot", "skills") },
+	{ agent: "OpenHands", dir: join(homedir(), ".openhands", "skills") },
+	{ agent: "Amp", dir: join(homedir(), ".config", "agents", "skills") },
+	{ agent: "Goose", dir: join(homedir(), ".config", "goose", "skills") },
+	{ agent: "Kilo Code", dir: join(homedir(), ".kilocode", "skills") },
+	{ agent: "Trae", dir: join(homedir(), ".trae", "skills") },
+];
+
 function parseYamlFrontmatter(content: string): Record<string, string> {
 	const match = content.match(/^---\n([\s\S]*?)\n---/);
 	if (!match || !match[1]) return {};
@@ -38,12 +56,13 @@ function getDirSize(dirPath: string): number {
 	return total;
 }
 
-export function scanInstalledSkills(): InstalledSkill[] {
-	const skillsDir = join(homedir(), ".claude", "skills");
+function scanSkillsDir(
+	skillsDir: string,
+	agent: string,
+): InstalledSkill[] {
 	if (!existsSync(skillsDir)) return [];
 
 	const skills: InstalledSkill[] = [];
-
 	let entries: string[];
 	try {
 		entries = readdirSync(skillsDir);
@@ -95,8 +114,37 @@ export function scanInstalledSkills(): InstalledSkill[] {
 			description,
 			size,
 			installedAt: new Date(stat.birthtime).toISOString(),
+			agent,
 		});
 	}
 
-	return skills.sort((a, b) => a.name.localeCompare(b.name));
+	return skills;
+}
+
+export function scanInstalledSkills(): InstalledSkill[] {
+	const allSkills: InstalledSkill[] = [];
+	const seen = new Set<string>();
+
+	for (const { agent, dir } of AGENT_SKILL_PATHS) {
+		const skills = scanSkillsDir(dir, agent);
+		for (const skill of skills) {
+			try {
+				const ino = statSync(skill.path).ino;
+				const key = `${ino}`;
+				if (seen.has(key)) continue;
+				seen.add(key);
+			} catch {}
+			allSkills.push(skill);
+		}
+	}
+
+	return allSkills.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function getDetectedAgents(): string[] {
+	const agents: string[] = [];
+	for (const { agent, dir } of AGENT_SKILL_PATHS) {
+		if (existsSync(dir)) agents.push(agent);
+	}
+	return agents;
 }

package/src/types/index.ts

@@ -4,6 +4,7 @@ export interface InstalledSkill {
 	description: string;
 	size: number;
 	installedAt: string;
+	agent: string;
 }
 
 export interface SkillInvocation {