@crafter/skillkit 0.1.0 → 0.1.2

package/package.json

@@ -1,10 +1,15 @@
 {
 	"name": "@crafter/skillkit",
-	"version": "0.1.0",
+	"version": "0.1.2",
+	"description": "Local-first analytics for AI agent skills. Track usage, measure context budget, and prune what you don't use.",
 	"type": "module",
 	"bin": {
-		"skill-kit": "./src/bin.ts"
+		"skillkit": "./src/bin.ts"
 	},
+	"files": [
+		"src",
+		"README.md"
+	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
@@ -13,10 +18,34 @@
 	},
 	"scripts": {
 		"dev": "bun run src/bin.ts",
-		"build": "bun build src/bin.ts --compile --outfile dist/skill-kit",
+		"build": "bun build src/bin.ts --compile --outfile dist/skillkit",
 		"test": "bun test src/",
 		"type-check": "tsc --noEmit"
 	},
+	"keywords": [
+		"skillkit",
+		"skills",
+		"analytics",
+		"claude-code",
+		"cursor",
+		"ai-agent",
+		"context-window",
+		"cli"
+	],
+	"author": "Crafter Station <the.crafter.station@gmail.com>",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/crafter-station/skill-kit.git",
+		"directory": "packages/cli"
+	},
+	"homepage": "https://github.com/crafter-station/skill-kit#readme",
+	"bugs": {
+		"url": "https://github.com/crafter-station/skill-kit/issues"
+	},
+	"engines": {
+		"bun": ">=1.0.0"
+	},
 	"devDependencies": {
 		"@types/bun": "^1.2.14",
 		"typescript": "^5.9.3"

package/src/bin.ts

@@ -1,60 +1,35 @@
 #!/usr/bin/env bun
 import { bold, cyan, dim, yellow } from "./tui/colors";
 
-const VERSION = "0.1.0";
+const VERSION = "0.1.2";
 
 function printHelp(): void {
 	console.log(`
-  ${bold("skill-kit")} ${dim(`v${VERSION}`)} - Analytics & management for AI agent skills
+  ${bold("skillkit")} ${dim(`v${VERSION}`)} - Analytics for AI agent skills
 
   ${bold("USAGE")}
-    skill-kit <command> [args]
+    skillkit <command> [args]
 
-  ${bold("MANAGEMENT")} ${dim("(powered by skills.sh)")}
-    ${cyan("install")}     Install a skill ${dim("(skill-kit install owner/repo)")}
-    ${cyan("uninstall")}   Remove a skill ${dim("(skill-kit uninstall name)")}
-    ${cyan("update")}      Update all skills to latest
-    ${cyan("find")}        Search the skills.sh registry
-
-  ${bold("ANALYTICS")} ${dim("(local-first)")}
+  ${bold("COMMANDS")}
+    ${cyan("scan")}        Discover installed skills and index session data
     ${cyan("list")}        List installed skills with size & context budget
     ${cyan("stats")}       Usage analytics with sparklines (last 30 days)
     ${cyan("health")}      Health check: unused skills, context budget, DB
-    ${cyan("analyze")}     Scan session files to populate analytics DB
-
-  ${bold("OTHER")}
+    ${cyan("prune")}       Remove unused skills to reclaim context budget
     ${cyan("version")}     Print version
     ${cyan("help")}        Show this help message
+
+  ${dim("Install skills via skills.sh: npx skills add <owner/repo>")}
 `);
 }
 
 async function main(): Promise<void> {
 	const cmd = process.argv[2];
-	const args = process.argv.slice(3);
 
 	switch (cmd) {
-		case "install":
-		case "add": {
-			const { runInstall } = await import("./commands/install");
-			runInstall(args);
-			break;
-		}
-		case "uninstall":
-		case "remove": {
-			const { runUninstall } = await import("./commands/uninstall");
-			runUninstall(args);
-			break;
-		}
-		case "update":
-		case "upgrade": {
-			const { runUpdate } = await import("./commands/update");
-			runUpdate();
-			break;
-		}
-		case "find":
-		case "search": {
-			const { runFind } = await import("./commands/find");
-			runFind(args);
+		case "scan": {
+			const { runScan } = await import("./commands/scan");
+			await runScan();
 			break;
 		}
 		case "list":
@@ -73,15 +48,9 @@ async function main(): Promise<void> {
 			await runHealth();
 			break;
 		}
-		case "analyze": {
-			const { getDb } = await import("./db/schema");
-			const { scanAllSessions } = await import("./scanner/index");
-			const db = getDb();
-			console.log("\n  Scanning ~/.claude/projects/ for skill invocations...");
-			const count = await scanAllSessions(db);
-			console.log(
-				`  ${count > 0 ? `Found ${count} new invocations.` : "No new invocations found."}\n`,
-			);
+		case "prune": {
+			const { runPrune } = await import("./commands/prune");
+			await runPrune();
 			break;
 		}
 		case "version":

package/src/commands/health.ts

@@ -4,10 +4,11 @@ import { join } from "node:path";
 import { getTopSkills } from "../db/queries";
 import { getDb } from "../db/schema";
 import { scanInstalledSkills } from "../scanner/skills";
-import { bold, dim, green, yellow } from "../tui/colors";
+import { bold, dim, green, red, yellow } from "../tui/colors";
 import { healthGauge } from "../tui/health";
 
-const CONTEXT_BUDGET = 16000;
+const METADATA_BUDGET = 16000;
+const BODY_LINE_LIMIT = 500;
 
 function check(label: string) {
 	return `  ${green("✓")} ${label}`;
@@ -21,26 +22,66 @@ function info(label: string) {
 	return `  ${dim("●")} ${label}`;
 }
 
-function _formatSize(bytes: number): string {
-	if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-	return `${bytes} B`;
+function parseFrontmatter(content: string): {
+	name: string;
+	description: string;
+	bodyLines: number;
+} {
+	const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+	if (!match)
+		return { name: "", description: "", bodyLines: content.split("\n").length };
+
+	const yaml = match[1];
+	const body = content.slice(match[0].length);
+	const bodyLines = body.trim() ? body.trim().split("\n").length : 0;
+
+	let name = "";
+	let description = "";
+
+	const nameMatch = yaml.match(/^name:\s*(.+)$/m);
+	if (nameMatch) name = nameMatch[1].trim().replace(/^["']|["']$/g, "");
+
+	const descMatch = yaml.match(/^description:\s*(.+)$/m);
+	if (descMatch) description = descMatch[1].trim().replace(/^["']|["']$/g, "");
+
+	return { name, description, bodyLines };
 }
 
 export async function runHealth(): Promise<void> {
 	const skills = scanInstalledSkills();
-	const _skillsDir = join(homedir(), ".claude", "skills");
-	const dbPath = join(homedir(), ".skill-kit", "analytics.db");
+	const dbPath = join(homedir(), ".skillkit", "analytics.db");
 	const dbExists = existsSync(dbPath);
 
-	let totalContextChars = 0;
+	let totalMetadataChars = 0;
+	let totalBodyChars = 0;
+	const oversizedSkills: Array<{ name: string; lines: number }> = [];
+	const longDescSkills: Array<{ name: string; chars: number }> = [];
+
 	for (const skill of skills) {
 		const skillMdPath = join(skill.path, "SKILL.md");
-		if (existsSync(skillMdPath)) {
-			try {
-				const content = readFileSync(skillMdPath, "utf-8");
-				totalContextChars += content.length;
-			} catch {}
-		}
+		if (!existsSync(skillMdPath)) continue;
+		try {
+			const content = readFileSync(skillMdPath, "utf-8");
+			const fm = parseFrontmatter(content);
+
+			const metadataSize =
+				(fm.name || skill.name).length + fm.description.length;
+			totalMetadataChars += metadataSize;
+			totalBodyChars += content.length;
+
+			if (fm.bodyLines > BODY_LINE_LIMIT) {
+				oversizedSkills.push({
+					name: fm.name || skill.name,
+					lines: fm.bodyLines,
+				});
+			}
+			if (fm.description.length > 1024) {
+				longDescSkills.push({
+					name: fm.name || skill.name,
+					chars: fm.description.length,
+				});
+			}
+		} catch {}
 	}
 
 	let eventCount = 0;
@@ -66,14 +107,12 @@ export async function runHealth(): Promise<void> {
 		}
 	}
 
-	const contextPct = Math.min(
+	const metadataPct = Math.min(
 		100,
-		Math.round((totalContextChars / CONTEXT_BUDGET) * 100),
+		Math.round((totalMetadataChars / METADATA_BUDGET) * 100),
 	);
-	const usedContextKb = (totalContextChars / 1000).toFixed(1);
-	const budgetKb = (CONTEXT_BUDGET / 1000).toFixed(1);
 
-	console.log(`\n  ${bold("SKILL-KIT HEALTH REPORT")}\n`);
+	console.log(`\n  ${bold("SKILLKIT HEALTH REPORT")}\n`);
 
 	console.log(check(`${skills.length} skills installed`));
 
@@ -83,46 +122,76 @@ export async function runHealth(): Promise<void> {
 		);
 	} else if (dbExists) {
 		console.log(warn("Analytics DB exists but has no data"));
-		console.log(dim("    Run: skill-kit stats"));
+		console.log(dim("    Run: skillkit scan"));
 	} else {
 		console.log(warn("Analytics DB not found"));
-		console.log(dim("    Run: skill-kit stats"));
+		console.log(dim("    Run: skillkit scan"));
 	}
 
 	if (neverUsed.length > 0) {
 		console.log();
-		console.log(warn(`${neverUsed.length} skills never used`));
+		console.log(warn(`${neverUsed.length} skills never used in 30d`));
 		const preview = neverUsed.slice(0, 5).join(", ");
 		const more = neverUsed.length > 5 ? ` +${neverUsed.length - 5} more` : "";
 		console.log(`    ${dim(preview + more)}`);
-		console.log(`    ${dim("Run: skill-kit uninstall <name>")}`);
+		console.log(`    ${dim("Run: skillkit prune")}`);
 	}
 
-	const unusedContextChars = neverUsed.reduce((acc, name) => {
-		const skill = skills.find((s) => s.name === name);
-		if (!skill) return acc;
-		const skillMdPath = join(skill.path, "SKILL.md");
-		if (!existsSync(skillMdPath)) return acc;
-		try {
-			return acc + readFileSync(skillMdPath, "utf-8").length;
-		} catch {
-			return acc;
-		}
-	}, 0);
-
 	console.log();
-	const gaugeStr = healthGauge(100 - contextPct);
+	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}`);
 	console.log(
-		info(
-			`Context budget: ${contextPct}% consumed (${usedContextKb}K / ${budgetKb}K chars)`,
-		),
+		`    ${dim(`Names + descriptions loaded at startup (2% of context window)`)}`,
 	);
-	console.log(`    ${gaugeStr}`);
-	if (unusedContextChars > 0) {
+
+	const bodyKb = (totalBodyChars / 1000).toFixed(1);
+	console.log(info(`Total skill content: ${bodyKb}K chars (loaded on-demand)`));
+
+	if (oversizedSkills.length > 0) {
+		console.log();
+		console.log(
+			warn(
+				`${oversizedSkills.length} skills exceed ${BODY_LINE_LIMIT}-line recommendation`,
+			),
+		);
+		for (const s of oversizedSkills.slice(0, 5)) {
+			console.log(`    ${dim(`${s.name}: ${s.lines} lines`)}`);
+		}
+		if (oversizedSkills.length > 5) {
+			console.log(`    ${dim(`+${oversizedSkills.length - 5} more`)}`);
+		}
 		console.log(
-			`    ${dim(`${neverUsed.length} unused skills waste ~${(unusedContextChars / 1000).toFixed(1)}K chars`)}`,
+			`    ${dim("Split large SKILL.md into referenced files for progressive disclosure")}`,
 		);
 	}
 
+	if (longDescSkills.length > 0) {
+		console.log();
+		console.log(
+			warn(`${longDescSkills.length} skills have descriptions over 1024 chars`),
+		);
+		for (const s of longDescSkills.slice(0, 3)) {
+			console.log(`    ${dim(`${s.name}: ${s.chars} chars`)}`);
+		}
+	}
+
 	console.log();
 }

package/src/commands/prune.ts

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+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 { bold, cyan, dim, red, yellow } from "../tui/colors";
+
+export async function runPrune(): Promise<void> {
+	const dbPath = join(homedir(), ".skillkit", "analytics.db");
+	if (!existsSync(dbPath)) {
+		console.log(`\n  ${yellow("No analytics data yet.")}`);
+		console.log(`  ${dim("Run: skillkit scan")}\n`);
+		return;
+	}
+
+	const db = getDb();
+	const skills = scanInstalledSkills();
+
+	if (skills.length === 0) {
+		console.log(`\n  ${dim("No skills installed.")}\n`);
+		return;
+	}
+
+	const topSkills = getTopSkills(db, 30);
+	const usedNames = new Set(topSkills.map((s) => s.skill_name));
+	const unused = skills.filter((s) => !usedNames.has(s.name));
+
+	if (unused.length === 0) {
+		console.log(
+			`\n  ${dim("All")} ${bold(String(skills.length))} ${dim("skills were used in the last 30 days. Nothing to prune.")}\n`,
+		);
+		return;
+	}
+
+	let totalWaste = 0;
+	const candidates: Array<{ name: string; path: string; chars: number }> = [];
+
+	for (const skill of unused) {
+		const skillMdPath = join(skill.path, "SKILL.md");
+		let chars = 0;
+		if (existsSync(skillMdPath)) {
+			try {
+				chars = readFileSync(skillMdPath, "utf-8").length;
+			} catch {}
+		}
+		totalWaste += chars;
+		candidates.push({ name: skill.name, path: skill.path, chars });
+	}
+
+	console.log(
+		`\n  ${bold("PRUNE")} ${dim("— unused skills in the last 30 days")}\n`,
+	);
+
+	for (const c of candidates) {
+		const size = c.chars > 0 ? dim(` (${(c.chars / 1000).toFixed(1)}K)`) : "";
+		console.log(`  ${red("×")} ${c.name}${size}`);
+	}
+
+	console.log(
+		`\n  ${bold(String(candidates.length))} skills ${dim("·")} ${bold(`${(totalWaste / 1000).toFixed(1)}K`)} ${dim("context reclaimable")}`,
+	);
+
+	const args = process.argv.slice(3);
+	if (!args.includes("--yes") && !args.includes("-y")) {
+		console.log(
+			`\n  ${dim("Run with")} ${cyan("--yes")} ${dim("to confirm deletion.")}\n`,
+		);
+		return;
+	}
+
+	let removed = 0;
+	for (const c of candidates) {
+		try {
+			rmSync(c.path, { recursive: true, force: true });
+			removed++;
+		} catch {
+			console.log(`  ${yellow("!")} Failed to remove ${c.name}`);
+		}
+	}
+
+	console.log(
+		`\n  ${bold(`Removed ${removed} skills`)} ${dim("·")} ${bold(`${(totalWaste / 1000).toFixed(1)}K`)} ${dim("reclaimed")}\n`,
+	);
+}

package/src/commands/scan.ts

@@ -0,0 +1,117 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+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 { bold, cyan, dim } from "../tui/colors";
+
+function detectSource(skillPath: string): "skills.sh" | "manual" {
+	const metaDir = join(skillPath, ".skills");
+	if (existsSync(metaDir)) return "skills.sh";
+
+	const skillMd = join(skillPath, "SKILL.md");
+	if (existsSync(skillMd)) {
+		try {
+			const entries = readdirSync(skillPath);
+			if (entries.includes(".git") || entries.includes(".gitmodules"))
+				return "skills.sh";
+		} catch {}
+	}
+	return "manual";
+}
+
+function countSessions(): number {
+	const projectsDir = join(homedir(), ".claude", "projects");
+	if (!existsSync(projectsDir)) return 0;
+
+	let count = 0;
+	const glob = new Bun.Glob("**/*.jsonl");
+	for (const _ of glob.scanSync({ cwd: projectsDir })) {
+		count++;
+	}
+	return count;
+}
+
+export async function runScan(): Promise<void> {
+	const db = getDb();
+
+	console.log(`\n  ${dim("Scanning ~/.claude/skills/ ...")}`);
+
+	const skills = scanInstalledSkills();
+
+	let skillsShCount = 0;
+	let manualCount = 0;
+
+	for (const skill of skills) {
+		const source = detectSource(skill.path);
+		if (source === "skills.sh") skillsShCount++;
+		else manualCount++;
+
+		upsertInstalledSkill(
+			db,
+			skill.name,
+			skill.path,
+			source,
+			undefined,
+			skill.size,
+		);
+	}
+
+	if (skills.length === 0) {
+		console.log(dim("  No skills found.\n"));
+		return;
+	}
+
+	const parts: string[] = [];
+	if (skillsShCount > 0) parts.push(`${skillsShCount} via skills.sh`);
+	if (manualCount > 0) parts.push(`${manualCount} manual`);
+
+	console.log(
+		`  ${bold(`Found ${skills.length} skills`)} ${dim(`(${parts.join(", ")})`)}`,
+	);
+
+	const localSkillsDir = join(process.cwd(), ".claude", "skills");
+	if (existsSync(localSkillsDir)) {
+		try {
+			const localEntries = readdirSync(localSkillsDir).filter((e) => {
+				try {
+					return statSync(join(localSkillsDir, e)).isDirectory();
+				} catch {
+					return false;
+				}
+			});
+			if (localEntries.length > 0) {
+				console.log(
+					dim(
+						`  + ${localEntries.length} project-local skills in .claude/skills/`,
+					),
+				);
+			}
+		} catch {}
+	}
+
+	console.log(dim("  Scanning sessions..."));
+
+	const sessionCount = countSessions();
+	const newInvocations = await scanAllSessions(db);
+	const totalRow = db
+		.query<{ count: number }, []>(
+			"SELECT COUNT(*) as count FROM skill_invocations",
+		)
+		.get();
+	const totalInvocations = totalRow?.count ?? 0;
+
+	console.log(
+		`  ${dim("Indexed")} ${bold(String(sessionCount))} ${dim("sessions")} ${cyan("·")} ${bold(totalInvocations.toLocaleString())} ${dim("invocations")}`,
+	);
+
+	if (newInvocations > 0) {
+		console.log(dim(`  (${newInvocations} new)`));
+	}
+
+	console.log(
+		`\n  ${dim("Ready. Run")} ${cyan("skillkit stats")} ${dim("to see usage.")}\n`,
+	);
+}

package/src/commands/stats.ts

@@ -35,7 +35,7 @@ export async function runStats(): Promise<void> {
 
 	if (stats.total === 0) {
 		console.log(`\n  ${yellow("No analytics data yet.")}`);
-		console.log(`  ${dim("Run: skill-kit analyze")}\n`);
+		console.log(`  ${dim("Run: skillkit scan")}\n`);
 		return;
 	}
 

package/src/db/schema.ts

@@ -3,7 +3,7 @@ import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-const DB_DIR = join(homedir(), ".skill-kit");
+const DB_DIR = join(homedir(), ".skillkit");
 const DB_PATH = join(DB_DIR, "analytics.db");
 
 export function getDb(): Database {

package/src/index.ts

@@ -1,5 +1,7 @@
 export { runHealth } from "./commands/health";
 export { runList } from "./commands/list";
+export { runPrune } from "./commands/prune";
+export { runScan } from "./commands/scan";
 export { runStats } from "./commands/stats";
 export {
 	getDailyUsage,

package/src/commands/find.ts

@@ -1,13 +0,0 @@
-import { execSync } from "node:child_process";
-import { dim } from "../tui/colors";
-
-export function runFind(args: string[]): void {
-	const query = args.join(" ");
-	console.log(`\n  ${dim("Searching skills.sh registry...")}\n`);
-	try {
-		const cmd = query ? `npx -y skills find ${query}` : "npx -y skills find";
-		execSync(cmd, { stdio: "inherit" });
-	} catch {
-		process.exit(1);
-	}
-}

package/src/commands/install.ts

@@ -1,21 +0,0 @@
-import { execSync } from "node:child_process";
-import { bold, dim, yellow } from "../tui/colors";
-
-export function runInstall(args: string[]): void {
-	const source = args.join(" ");
-	if (!source) {
-		console.error(`\n  ${yellow("Usage:")} skill-kit install <owner/repo>\n`);
-		console.log(`  ${dim("Examples:")}`);
-		console.log(`    skill-kit install vercel-labs/agent-skills`);
-		console.log(`    skill-kit install crafter-station/skill-kit\n`);
-		process.exit(1);
-	}
-	console.log(
-		`\n  ${dim("Installing via")} ${bold("skills.sh")}${dim("...")}\n`,
-	);
-	try {
-		execSync(`npx -y skills add ${source}`, { stdio: "inherit" });
-	} catch {
-		process.exit(1);
-	}
-}

package/src/commands/uninstall.ts

@@ -1,16 +0,0 @@
-import { execSync } from "node:child_process";
-import { dim, yellow } from "../tui/colors";
-
-export function runUninstall(args: string[]): void {
-	const name = args.join(" ");
-	if (!name) {
-		console.error(`\n  ${yellow("Usage:")} skill-kit uninstall <skill-name>\n`);
-		process.exit(1);
-	}
-	console.log(`\n  ${dim("Removing via skills.sh...")}\n`);
-	try {
-		execSync(`npx -y skills remove ${name}`, { stdio: "inherit" });
-	} catch {
-		process.exit(1);
-	}
-}

package/src/commands/update.ts

@@ -1,11 +0,0 @@
-import { execSync } from "node:child_process";
-import { dim } from "../tui/colors";
-
-export function runUpdate(): void {
-	console.log(`\n  ${dim("Checking for updates via skills.sh...")}\n`);
-	try {
-		execSync("npx -y skills update", { stdio: "inherit" });
-	} catch {
-		process.exit(1);
-	}
-}

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-	"extends": "../../tsconfig.base.json",
-	"compilerOptions": {
-		"outDir": "./dist",
-		"rootDir": "./src",
-		"types": ["bun-types"]
-	},
-	"include": ["src"]
-}