deepskill 0.1.0

package/bin/cli.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+import module from 'node:module';
+
+if (module.enableCompileCache && !process.env.NODE_DISABLE_COMPILE_CACHE) {
+  try {
+    module.enableCompileCache();
+  } catch {
+    // Ignore errors
+  }
+}
+
+await import('../dist/cli.mjs');

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,676 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
+import { basename, dirname, extname, join, relative } from "path";
+import { fileURLToPath } from "url";
+import pc from "picocolors";
+import { create, insert, load, save, search } from "@orama/orama";
+import { createHash } from "crypto";
+import matter from "gray-matter";
+//#region src/commands/init.ts
+const SKILL_TEMPLATE = (name) => `---
+name: ${name}
+description: >-
+  A brief description of what this skill does.
+  Use when the user asks about [topic].
+knowledge: true
+metadata:
+  author: your-name
+  version: "0.1.0"
+---
+
+# ${name}
+
+Instructions for the agent to follow when this skill is activated.
+
+## When to use
+
+Describe when this skill should be used.
+
+## Searching knowledge
+
+Run the search script to query the embedded knowledge base:
+
+\`\`\`bash
+bash scripts/search.sh "your query here"
+\`\`\`
+
+Always search before answering domain-specific questions.
+Do NOT rely on training data for specific rules or thresholds.
+Cite the source_file and section from search results.
+
+## Instructions
+
+1. First, search the knowledge base for relevant information
+2. Use the search results to ground your response
+3. Always cite the source file and section
+4. If no results found, say so explicitly
+`;
+const SEARCH_SCRIPT = `#!/bin/bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(dirname "$SCRIPT_DIR")"
+INDEX_PATH="$SKILL_DIR/knowledge/index.json"
+
+if [ ! -f "$INDEX_PATH" ]; then
+  echo '{"error": "No index found. Run: npx deepskill build"}'
+  exit 1
+fi
+
+if [ -z "$1" ]; then
+  echo '{"error": "Usage: search.sh <query>"}'
+  exit 1
+fi
+
+node --input-type=module -e "
+import { create, load, search } from '@orama/orama';
+import { readFileSync } from 'fs';
+
+const idx = JSON.parse(readFileSync('$INDEX_PATH', 'utf-8'));
+const db = create({
+  schema: {
+    title: 'string',
+    content: 'string',
+    source_file: 'string',
+    section: 'string',
+    tags: 'string',
+  },
+});
+load(db, idx);
+const r = search(db, { term: \\\`$1\\\`, limit: 5 });
+console.log(JSON.stringify(r.hits.map(h => ({
+  title: h.document.title,
+  content: h.document.content,
+  source: h.document.source_file,
+  section: h.document.section,
+  score: h.score,
+})), null, 2));
+"
+`;
+const DEEPSKILL_JSON_TEMPLATE = (name) => JSON.stringify({
+	name,
+	version: "0.1.0",
+	author: "",
+	description: "",
+	corpus: {
+		files: 0,
+		chunks: 0,
+		tokens: 0
+	},
+	index_hash: "",
+	built_at: ""
+}, null, 2);
+function runInit(args) {
+	const cwd = process.cwd();
+	const name = args[0] || basename(cwd);
+	const hasName = args[0] !== void 0;
+	const skillDir = hasName ? join(cwd, name) : cwd;
+	if (hasName && existsSync(skillDir)) {
+		console.log(pc.red(`  Directory already exists: ${name}/`));
+		return;
+	}
+	const skillFile = join(skillDir, "SKILL.md");
+	if (existsSync(skillFile)) {
+		console.log(pc.yellow(`  SKILL.md already exists in ${hasName ? name + "/" : "./"}`));
+		return;
+	}
+	mkdirSync(join(skillDir, "knowledge", "corpus"), { recursive: true });
+	mkdirSync(join(skillDir, "scripts"), { recursive: true });
+	writeFileSync(skillFile, SKILL_TEMPLATE(name));
+	writeFileSync(join(skillDir, "knowledge", "corpus", ".gitkeep"), "");
+	writeFileSync(join(skillDir, "scripts", "search.sh"), SEARCH_SCRIPT, { mode: 493 });
+	writeFileSync(join(skillDir, "deepskill.json"), DEEPSKILL_JSON_TEMPLATE(name));
+	const prefix = hasName ? `${name}/` : "";
+	console.log(pc.white(`  Created ${hasName ? name + "/" : "deep skill"}`));
+	console.log();
+	console.log(pc.dim("  Files:"));
+	console.log(`    ${prefix}SKILL.md`);
+	console.log(`    ${prefix}knowledge/corpus/          ${pc.dim("(drop your .md, .csv, .txt, .json files here)")}`);
+	console.log(`    ${prefix}scripts/search.sh          ${pc.dim("(pre-wired search bridge for agents)")}`);
+	console.log(`    ${prefix}deepskill.json`);
+	console.log();
+	console.log(pc.dim("  Next steps:"));
+	console.log(`    1. Edit ${pc.white("SKILL.md")} with your skill instructions`);
+	console.log(`    2. Add documents to ${pc.white("knowledge/corpus/")}`);
+	console.log(`    3. Run: ${pc.white("npx deepskill build")}`);
+	console.log(`    4. Test: ${pc.white("npx deepskill search \"your query\"")}`);
+	console.log();
+}
+//#endregion
+//#region src/chunkers/markdown.ts
+const HEADING_RE = /^(#{1,6})\s+(.+)$/;
+function extractKeywords$1(text) {
+	const words = text.toLowerCase().replace(/[^a-z0-9\s-]/g, "").split(/\s+/).filter((w) => w.length > 3);
+	const freq = /* @__PURE__ */ new Map();
+	for (const w of words) freq.set(w, (freq.get(w) ?? 0) + 1);
+	return [...freq.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([w]) => w).join(", ");
+}
+function chunkMarkdown(content, sourceFile) {
+	const lines = content.split("\n");
+	const chunks = [];
+	const headingStack = [];
+	let currentTitle = "";
+	let currentLines = [];
+	function flush() {
+		const body = currentLines.join("\n").trim();
+		if (!body) return;
+		const section = headingStack.join(" > ");
+		chunks.push({
+			title: currentTitle || sourceFile,
+			content: body,
+			source_file: sourceFile,
+			section,
+			tags: extractKeywords$1(body)
+		});
+	}
+	for (const line of lines) {
+		const match = HEADING_RE.exec(line);
+		if (match) {
+			flush();
+			currentLines = [];
+			const level = match[1].length;
+			const text = match[2].trim();
+			while (headingStack.length >= level) headingStack.pop();
+			headingStack.push(text);
+			currentTitle = text;
+		} else currentLines.push(line);
+	}
+	flush();
+	return chunks;
+}
+//#endregion
+//#region src/chunkers/csv.ts
+function parseCsvLine(line) {
+	const cells = [];
+	let current = "";
+	let inQuotes = false;
+	for (let i = 0; i < line.length; i++) {
+		const char = line[i];
+		if (char === "\"") if (inQuotes && line[i + 1] === "\"") {
+			current += "\"";
+			i++;
+		} else inQuotes = !inQuotes;
+		else if (char === "," && !inQuotes) {
+			cells.push(current.trim());
+			current = "";
+		} else current += char;
+	}
+	cells.push(current.trim());
+	return cells;
+}
+function chunkCsv(content, sourceFile) {
+	const lines = content.split("\n").filter((l) => l.trim());
+	if (lines.length < 2) return [];
+	const headers = parseCsvLine(lines[0]);
+	const chunks = [];
+	for (let i = 1; i < lines.length; i++) {
+		const cells = parseCsvLine(lines[i]);
+		const title = cells[0] ?? `Row ${i}`;
+		const pairs = headers.map((h, j) => `${h}: ${cells[j] ?? ""}`);
+		chunks.push({
+			title,
+			content: pairs.join("\n"),
+			source_file: sourceFile,
+			section: `Row ${i}`,
+			tags: headers.slice(0, 5).join(", ")
+		});
+	}
+	return chunks;
+}
+//#endregion
+//#region src/chunkers/text.ts
+const WINDOW_CHARS = 2048;
+const OVERLAP_CHARS = 256;
+function extractKeywords(text) {
+	const words = text.toLowerCase().replace(/[^a-z0-9\s-]/g, "").split(/\s+/).filter((w) => w.length > 3);
+	const freq = /* @__PURE__ */ new Map();
+	for (const w of words) freq.set(w, (freq.get(w) ?? 0) + 1);
+	return [...freq.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([w]) => w).join(", ");
+}
+function chunkText(content, sourceFile) {
+	const chunks = [];
+	let offset = 0;
+	let chunkIndex = 0;
+	while (offset < content.length) {
+		const window = content.slice(offset, offset + WINDOW_CHARS);
+		const firstLine = window.split("\n")[0]?.trim() || `Chunk ${chunkIndex + 1}`;
+		chunks.push({
+			title: firstLine.slice(0, 120),
+			content: window.trim(),
+			source_file: sourceFile,
+			section: `Chunk ${chunkIndex + 1}`,
+			tags: extractKeywords(window)
+		});
+		offset += WINDOW_CHARS - OVERLAP_CHARS;
+		chunkIndex++;
+	}
+	return chunks;
+}
+//#endregion
+//#region src/chunkers/json.ts
+function chunkJson(content, sourceFile) {
+	let parsed;
+	try {
+		parsed = JSON.parse(content);
+	} catch {
+		return chunkText(content, sourceFile);
+	}
+	if (Array.isArray(parsed)) return parsed.flatMap((item, i) => {
+		const str = JSON.stringify(item, null, 2);
+		return [{
+			title: (typeof item === "object" && item !== null && "name" in item ? String(item.name) : null) ?? (typeof item === "object" && item !== null && "title" in item ? String(item.title) : null) ?? `Item ${i + 1}`,
+			content: str,
+			source_file: sourceFile,
+			section: `Item ${i + 1}`,
+			tags: ""
+		}];
+	});
+	return chunkText(JSON.stringify(parsed, null, 2), sourceFile);
+}
+//#endregion
+//#region src/chunkers/index.ts
+const SUPPORTED_EXTENSIONS = new Set([
+	".md",
+	".csv",
+	".txt",
+	".json"
+]);
+function isSupportedFile(filePath) {
+	return SUPPORTED_EXTENSIONS.has(extname(filePath).toLowerCase());
+}
+function chunkFile(content, sourceFile) {
+	switch (extname(sourceFile).toLowerCase()) {
+		case ".md": return chunkMarkdown(content, sourceFile);
+		case ".csv": return chunkCsv(content, sourceFile);
+		case ".json": return chunkJson(content, sourceFile);
+		default: return chunkText(content, sourceFile);
+	}
+}
+//#endregion
+//#region src/indexer/schema.ts
+const SKILL_SCHEMA = {
+	title: "string",
+	content: "string",
+	source_file: "string",
+	section: "string",
+	tags: "string"
+};
+//#endregion
+//#region src/indexer/build.ts
+function buildIndex(chunks) {
+	const db = create({ schema: SKILL_SCHEMA });
+	for (const chunk of chunks) insert(db, {
+		title: chunk.title,
+		content: chunk.content,
+		source_file: chunk.source_file,
+		section: chunk.section,
+		tags: chunk.tags
+	});
+	return save(db);
+}
+//#endregion
+//#region src/utils/hash.ts
+function sha256(data) {
+	return createHash("sha256").update(data).digest("hex");
+}
+//#endregion
+//#region src/utils/tokens.ts
+/**
+* Naive token count: ~4 characters per token.
+* Good enough for corpus stats without pulling in a tokenizer.
+*/
+function countTokens(text) {
+	return Math.ceil(text.length / 4);
+}
+//#endregion
+//#region src/commands/build.ts
+function walkDir(dir) {
+	const results = [];
+	if (!existsSync(dir)) return results;
+	const entries = readdirSync(dir);
+	for (const entry of entries) {
+		const full = join(dir, entry);
+		if (statSync(full).isDirectory()) results.push(...walkDir(full));
+		else if (isSupportedFile(full)) results.push(full);
+	}
+	return results;
+}
+async function runBuild() {
+	const cwd = process.cwd();
+	const corpusDir = join(cwd, "knowledge", "corpus");
+	const indexPath = join(cwd, "knowledge", "index.json");
+	const metaPath = join(cwd, "deepskill.json");
+	if (!existsSync(corpusDir)) {
+		console.log(pc.red("  No knowledge/corpus/ directory found."));
+		console.log(pc.dim("  Run \"npx deepskill init\" first, or create knowledge/corpus/ manually."));
+		return;
+	}
+	const files = walkDir(corpusDir);
+	if (files.length === 0) {
+		console.log(pc.yellow("  No supported files in knowledge/corpus/"));
+		console.log(pc.dim("  Add .md, .csv, .txt, or .json files and try again."));
+		return;
+	}
+	console.log(pc.white("  Building search index..."));
+	console.log();
+	const allChunks = [];
+	let totalTokens = 0;
+	for (const file of files) {
+		const relPath = relative(cwd, file);
+		const content = readFileSync(file, "utf-8");
+		const chunks = chunkFile(content, relative(join(cwd, "knowledge"), file));
+		const tokens = countTokens(content);
+		totalTokens += tokens;
+		allChunks.push(...chunks);
+		console.log(`    ${pc.dim("+")} ${relPath} ${pc.dim(`(${chunks.length} chunks, ~${tokens} tokens)`)}`);
+	}
+	console.log();
+	if (allChunks.length === 0) {
+		console.log(pc.yellow("  No chunks produced. Check your corpus files."));
+		return;
+	}
+	const indexData = buildIndex(allChunks);
+	const indexJson = JSON.stringify(indexData);
+	writeFileSync(indexPath, indexJson);
+	const indexHash = sha256(indexJson);
+	const indexSizeMB = (Buffer.byteLength(indexJson) / (1024 * 1024)).toFixed(1);
+	let meta = {};
+	if (existsSync(metaPath)) try {
+		meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+	} catch {}
+	meta.corpus = {
+		files: files.length,
+		chunks: allChunks.length,
+		tokens: totalTokens
+	};
+	meta.index_hash = indexHash;
+	meta.built_at = (/* @__PURE__ */ new Date()).toISOString();
+	writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+	console.log(pc.white("  Build complete"));
+	console.log();
+	console.log(`    Files:  ${pc.white(String(files.length))}   Chunks: ${pc.white(String(allChunks.length))}   Tokens: ${pc.white(`~${totalTokens}`)}   Index:  ${pc.white(`${indexSizeMB}MB`)}`);
+	console.log();
+	console.log(`  ${pc.dim("Test it:")} npx deepskill search "your query"`);
+	console.log();
+}
+//#endregion
+//#region src/indexer/search.ts
+function searchIndex(indexData, query, limit = 5) {
+	const db = create({ schema: SKILL_SCHEMA });
+	load(db, indexData);
+	const start = performance.now();
+	const result = search(db, {
+		term: query,
+		limit
+	});
+	const elapsed = performance.now() - start;
+	return {
+		count: result.count,
+		elapsed_ms: Math.round(elapsed * 100) / 100,
+		results: result.hits.map((hit) => {
+			const doc = hit.document;
+			const fileName = doc.source_file.replace(/^corpus\//, "");
+			const sectionSlug = doc.section.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+			return {
+				title: doc.title,
+				content: doc.content,
+				source_file: doc.source_file,
+				section: doc.section,
+				score: hit.score,
+				citation: sectionSlug ? `${fileName}#${sectionSlug}` : fileName
+			};
+		})
+	};
+}
+//#endregion
+//#region src/commands/search.ts
+async function runSearch(args) {
+	const query = args.join(" ").trim();
+	if (!query) {
+		console.log(pc.yellow("Usage: deepskill search <query>"));
+		console.log(pc.dim("  Example: deepskill search \"transfer limits\""));
+		return;
+	}
+	const indexPath = join(process.cwd(), "knowledge", "index.json");
+	if (!existsSync(indexPath)) {
+		console.log(pc.red("No index found at knowledge/index.json"));
+		console.log(pc.dim("Run \"npx deepskill build\" first."));
+		return;
+	}
+	let indexData;
+	try {
+		indexData = JSON.parse(readFileSync(indexPath, "utf-8"));
+	} catch {
+		console.log(pc.red("Failed to parse knowledge/index.json"));
+		return;
+	}
+	const limitArg = args.find((a) => a.startsWith("--limit="));
+	const limit = limitArg ? parseInt(limitArg.split("=")[1], 10) : 5;
+	const queryText = args.filter((a) => !a.startsWith("--")).join(" ").trim();
+	const response = searchIndex(indexData, queryText || query, limit);
+	if (response.results.length === 0) {
+		console.log();
+		console.log(pc.yellow(`  No results for "${queryText || query}"`));
+		console.log();
+		return;
+	}
+	console.log();
+	console.log(pc.dim(`  ${response.count} result(s) in ${response.elapsed_ms}ms`));
+	console.log();
+	for (let i = 0; i < response.results.length; i++) {
+		const r = response.results[i];
+		const num = pc.dim(`  ${i + 1}.`);
+		console.log(`${num} ${pc.white(pc.bold(r.title))}`);
+		console.log(`     ${pc.dim("source:")} ${r.source_file}  ${pc.dim("section:")} ${r.section}  ${pc.dim("score:")} ${r.score.toFixed(2)}`);
+		const snippet = r.content.replace(/\n/g, " ").slice(0, 200);
+		console.log(`     ${pc.dim(snippet)}${r.content.length > 200 ? pc.dim("...") : ""}`);
+		console.log(`     ${pc.dim("cite:")} ${r.citation}`);
+		console.log();
+	}
+}
+//#endregion
+//#region src/commands/validate.ts
+function countFiles(dir) {
+	if (!existsSync(dir)) return 0;
+	let count = 0;
+	const entries = readdirSync(dir);
+	for (const entry of entries) {
+		const full = join(dir, entry);
+		if (statSync(full).isDirectory()) count += countFiles(full);
+		else if (isSupportedFile(full)) count++;
+	}
+	return count;
+}
+async function runValidate() {
+	const cwd = process.cwd();
+	const skillPath = join(cwd, "SKILL.md");
+	const indexPath = join(cwd, "knowledge", "index.json");
+	const corpusDir = join(cwd, "knowledge", "corpus");
+	const metaPath = join(cwd, "deepskill.json");
+	let errors = 0;
+	let warnings = 0;
+	function pass(msg) {
+		console.log(`  ${pc.green("✓")} ${msg}`);
+	}
+	function fail(msg) {
+		console.log(`  ${pc.red("✗")} ${msg}`);
+		errors++;
+	}
+	function warn(msg) {
+		console.log(`  ${pc.yellow("!")} ${msg}`);
+		warnings++;
+	}
+	if (!existsSync(skillPath)) {
+		fail("SKILL.md not found");
+		console.log();
+		console.log(pc.dim("  Run \"npx deepskill init\" to create one."));
+		console.log();
+		return;
+	}
+	pass("SKILL.md exists");
+	const skillContent = readFileSync(skillPath, "utf-8");
+	let frontmatter;
+	try {
+		frontmatter = matter(skillContent).data;
+		pass("Frontmatter is valid YAML");
+	} catch (e) {
+		fail(`Frontmatter parse error: ${e instanceof Error ? e.message : "unknown"}`);
+		console.log();
+		return;
+	}
+	if (frontmatter.name && typeof frontmatter.name === "string") pass(`Name: ${frontmatter.name}`);
+	else fail("Missing \"name\" in frontmatter");
+	if (frontmatter.description && typeof frontmatter.description === "string") {
+		const desc = frontmatter.description;
+		if (desc.length < 10) warn(`Description is very short (${desc.length} chars)`);
+		else pass(`Description: ${desc.slice(0, 80)}${desc.length > 80 ? "..." : ""}`);
+	} else fail("Missing \"description\" in frontmatter");
+	if (frontmatter.knowledge === true) pass("knowledge: true");
+	else warn("knowledge: true not set in frontmatter (this is a thin skill)");
+	if (existsSync(corpusDir)) {
+		const fileCount = countFiles(corpusDir);
+		if (fileCount > 0) pass(`Corpus: ${fileCount} file(s) in knowledge/corpus/`);
+		else warn("knowledge/corpus/ exists but has no supported files");
+	} else if (frontmatter.knowledge === true) fail("knowledge/corpus/ not found (required when knowledge: true)");
+	else pass(pc.dim("No knowledge/corpus/ (thin skill)"));
+	if (existsSync(indexPath)) try {
+		const indexData = JSON.parse(readFileSync(indexPath, "utf-8"));
+		load(create({ schema: SKILL_SCHEMA }), indexData);
+		pass("knowledge/index.json loads successfully");
+	} catch (e) {
+		fail(`knowledge/index.json failed to load: ${e instanceof Error ? e.message : "unknown"}`);
+	}
+	else if (frontmatter.knowledge === true) warn("knowledge/index.json not found — run \"npx deepskill build\"");
+	if (existsSync(metaPath)) try {
+		const corpus = JSON.parse(readFileSync(metaPath, "utf-8")).corpus;
+		if (corpus) pass(`deepskill.json: ${corpus.files ?? 0} files, ${corpus.chunks ?? 0} chunks, ~${corpus.tokens ?? 0} tokens`);
+		else pass("deepskill.json exists");
+	} catch {
+		warn("deepskill.json exists but is not valid JSON");
+	}
+	else warn("deepskill.json not found");
+	console.log();
+	if (errors === 0 && warnings === 0) console.log(pc.green("  All checks passed"));
+	else if (errors === 0) console.log(pc.yellow(`  Passed with ${warnings} warning(s)`));
+	else console.log(pc.red(`  ${errors} error(s), ${warnings} warning(s)`));
+	console.log();
+}
+//#endregion
+//#region src/cli.ts
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function getVersion() {
+	try {
+		const pkgPath = join(__dirname, "..", "package.json");
+		return JSON.parse(readFileSync(pkgPath, "utf-8")).version;
+	} catch {
+		return "0.1.0";
+	}
+}
+const VERSION = getVersion();
+const LOGO_LINES = [
+	"██████╗ ███████╗███████╗██████╗ ███████╗██╗  ██╗██╗██╗     ██╗     ",
+	"██╔══██╗██╔════╝██╔════╝██╔══██╗██╔════╝██║ ██╔╝██║██║     ██║     ",
+	"██║  ██║█████╗  █████╗  ██████╔╝███████╗█████╔╝ ██║██║     ██║     ",
+	"██║  ██║██╔══╝  ██╔══╝  ██╔═══╝ ╚════██║██╔═██╗ ██║██║     ██║     ",
+	"██████╔╝███████╗███████╗██║     ███████║██║  ██╗██║███████╗███████╗",
+	"╚═════╝ ╚══════╝╚══════╝╚═╝     ╚══════╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝"
+];
+const GRAYS = [
+	"\x1B[38;5;250m",
+	"\x1B[38;5;248m",
+	"\x1B[38;5;245m",
+	"\x1B[38;5;243m",
+	"\x1B[38;5;240m",
+	"\x1B[38;5;238m"
+];
+const RESET = "\x1B[0m";
+function showLogo() {
+	console.log();
+	LOGO_LINES.forEach((line, i) => {
+		console.log(`${GRAYS[i]}${line}${RESET}`);
+	});
+}
+function showBanner() {
+	showLogo();
+	console.log();
+	console.log(pc.dim("  Agent skills with searchable knowledge"));
+	console.log();
+	console.log(`  ${pc.dim("$")} ${pc.white("npx deepskill init")} ${pc.dim("<name>")}        ${pc.dim("Create a new deep skill")}`);
+	console.log(`  ${pc.dim("$")} ${pc.white("npx deepskill build")}               ${pc.dim("Build search index from corpus")}`);
+	console.log(`  ${pc.dim("$")} ${pc.white("npx deepskill search")} ${pc.dim("<query>")}     ${pc.dim("Search the knowledge base")}`);
+	console.log(`  ${pc.dim("$")} ${pc.white("npx deepskill validate")}            ${pc.dim("Validate skill structure")}`);
+	console.log();
+	console.log(`  ${pc.dim("try:")} npx deepskill init my-skill`);
+	console.log();
+	console.log(`  ${pc.dim(`v${VERSION}`)}  ${pc.white("https://deepskill.sh")}`);
+	console.log();
+}
+function showHelp() {
+	console.log(`
+${pc.bold("Usage:")} deepskill <command> [options]
+
+${pc.bold("Commands:")}
+  init <name>        Create a new deep skill with knowledge directory
+  build              Chunk corpus and build Orama search index
+  search <query>     Query the local knowledge index
+  validate           Check skill structure, frontmatter, and index
+
+${pc.bold("Options:")}
+  --help, -h         Show this help message
+  --version, -v      Show version number
+
+${pc.bold("Examples:")}
+  ${pc.dim("$")} deepskill init compliance-checker
+  ${pc.dim("$")} deepskill build
+  ${pc.dim("$")} deepskill search "transfer limits"
+  ${pc.dim("$")} deepskill validate
+
+${pc.dim(`v${VERSION}`)}  ${pc.white("https://deepskill.sh")}
+`);
+}
+async function main() {
+	const args = process.argv.slice(2);
+	if (args.length === 0) {
+		showBanner();
+		return;
+	}
+	const command = args[0];
+	const restArgs = args.slice(1);
+	switch (command) {
+		case "init":
+			showLogo();
+			console.log();
+			runInit(restArgs);
+			break;
+		case "build":
+			showLogo();
+			console.log();
+			await runBuild();
+			break;
+		case "search":
+		case "s":
+			await runSearch(restArgs);
+			break;
+		case "validate":
+		case "check":
+			showLogo();
+			console.log();
+			await runValidate();
+			break;
+		case "--help":
+		case "-h":
+			showHelp();
+			break;
+		case "--version":
+		case "-v":
+			console.log(VERSION);
+			break;
+		default:
+			console.log(`Unknown command: ${command}`);
+			console.log(`Run ${pc.bold("deepskill --help")} for usage.`);
+			process.exit(1);
+	}
+}
+main();
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "deepskill",
+  "version": "0.1.0",
+  "description": "Agent skills that carry their own searchable knowledge",
+  "type": "module",
+  "bin": {
+    "deepskill": "./bin/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "obuild",
+    "dev": "node --import tsx src/cli.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "cli",
+    "agent-skills",
+    "skills",
+    "ai-agents",
+    "knowledge-base",
+    "search",
+    "orama",
+    "deepskill"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepskill/dskill.git"
+  },
+  "homepage": "https://deepskill.sh",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "obuild": "^0.4.22",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@orama/orama": "^3.1.18",
+    "gray-matter": "^4.0.3",
+    "picocolors": "^1.1.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@10.17.1"
+}