@electric-ax/agents 0.1.0 → 0.1.3

package/dist/index.js

@@ -1,11 +1,11 @@
-import { createEntityRegistry, createRuntimeHandler } from "@electric-ax/agents-runtime";
 import path, { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createEntityRegistry, createRuntimeHandler, db } from "@electric-ax/agents-runtime";
 import fsSync from "node:fs";
 import pino from "pino";
 import Anthropic from "@anthropic-ai/sdk";
 import { createHash } from "node:crypto";
 import fs, { mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
 import Database from "better-sqlite3";
 import { Type } from "@sinclair/typebox";
 import { load } from "sqlite-vec";
@@ -237,12 +237,12 @@ function createFingerprint(entries) {
 	}
 	return hash.digest(`hex`);
 }
-function getMeta(db, key) {
-	const row = db.prepare(`select value from index_meta where key = ?`).get(key);
+function getMeta(db$1, key) {
+	const row = db$1.prepare(`select value from index_meta where key = ?`).get(key);
 	return row?.value ?? null;
 }
-function setMeta(db, key, value) {
-	db.prepare(`insert into index_meta(key, value) values(?, ?)
+function setMeta(db$1, key, value) {
+	db$1.prepare(`insert into index_meta(key, value) values(?, ?)
      on conflict(key) do update set value = excluded.value`).run(key, value);
 }
 function reciprocalRank(rank, k = 60) {
@@ -310,11 +310,11 @@ var DocsKnowledgeBase = class {
 	openDatabase() {
 		fsSync.mkdirSync(path.dirname(this.dbPath), { recursive: true });
 		try {
-			const db = new Database(this.dbPath);
-			load(db);
-			db.pragma(`journal_mode = WAL`);
-			db.pragma(`synchronous = NORMAL`);
-			return db;
+			const db$1 = new Database(this.dbPath);
+			load(db$1);
+			db$1.pragma(`journal_mode = WAL`);
+			db$1.pragma(`synchronous = NORMAL`);
+			return db$1;
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			console.warn(`${this.logPrefix} falling back to in-memory docs index: ${message}`);
@@ -407,17 +407,17 @@ var DocsKnowledgeBase = class {
 			console.log(`${this.logPrefix} indexed ${stats$1.docCount} docs into ${stats$1.chunkCount} chunks (${stats$1.fingerprint.slice(0, 12)}...)`);
 			return stats$1;
 		}
-		const db = this.db;
-		const currentFingerprint = getMeta(db, DOCS_FINGERPRINT_KEY);
-		const currentVersion = getMeta(db, INDEX_VERSION_KEY);
+		const db$1 = this.db;
+		const currentFingerprint = getMeta(db$1, DOCS_FINGERPRINT_KEY);
+		const currentVersion = getMeta(db$1, INDEX_VERSION_KEY);
 		if (currentFingerprint === fingerprint && currentVersion === INDEX_VERSION && this.stats().chunkCount > 0) return this.stats();
-		const insertDoc = db.prepare(`insert into docs(path, title, content) values(?, ?, ?)`);
-		const insertChunk = db.prepare(`insert into chunks(doc_path, title, heading, chunk_index, content, embedding)
+		const insertDoc = db$1.prepare(`insert into docs(path, title, content) values(?, ?, ?)`);
+		const insertChunk = db$1.prepare(`insert into chunks(doc_path, title, heading, chunk_index, content, embedding)
        values(?, ?, ?, ?, ?, vec_f32(?))`);
-		const insertFts = db.prepare(`insert into chunks_fts(rowid, doc_path, title, heading, content)
+		const insertFts = db$1.prepare(`insert into chunks_fts(rowid, doc_path, title, heading, content)
        values(?, ?, ?, ?, ?)`);
-		const reset = db.transaction(() => {
-			db.exec(`
+		const reset = db$1.transaction(() => {
+			db$1.exec(`
         delete from chunks_fts;
         delete from chunks;
         delete from docs;
@@ -436,8 +436,8 @@ var DocsKnowledgeBase = class {
 					insertFts.run(Number(result.lastInsertRowid), chunk.docPath, chunk.title, chunk.heading, chunk.content);
 				}
 			}
-			setMeta(db, DOCS_FINGERPRINT_KEY, fingerprint);
-			setMeta(db, INDEX_VERSION_KEY, INDEX_VERSION);
+			setMeta(db$1, DOCS_FINGERPRINT_KEY, fingerprint);
+			setMeta(db$1, INDEX_VERSION_KEY, INDEX_VERSION);
 		});
 		reset();
 		const stats = this.stats();
@@ -660,6 +660,184 @@ function createHortonDocsSupport(workingDirectory, opts = {}) {
 	};
 }
 
+//#endregion
+//#region src/skills/tools.ts
+function skillContextId(name) {
+	return `skill:${name}`;
+}
+function createSkillTools(registry, ctx) {
+	const useSkill = {
+		name: `use_skill`,
+		label: `Use Skill`,
+		description: `Load a skill into your context. Call with a skill name to load it. Pass args if the skill accepts arguments.`,
+		parameters: Type.Object({
+			name: Type.String({ description: `Name of the skill to load` }),
+			args: Type.Optional(Type.String({ description: `Arguments to pass to the skill (space-separated, or quoted for multi-word values)` }))
+		}),
+		execute: async (_toolCallId, params) => {
+			const { name, args } = params;
+			const meta = registry.catalog.get(name);
+			if (!meta) {
+				const available = Array.from(registry.catalog.keys()).join(`, `);
+				return {
+					content: [{
+						type: `text`,
+						text: `Skill "${name}" not found. Available skills: ${available || `none`}`
+					}],
+					details: { loaded: false }
+				};
+			}
+			const contextId = skillContextId(name);
+			if (ctx.getContext(contextId)) return {
+				content: [{
+					type: `text`,
+					text: `Skill "${name}" is already loaded.`
+				}],
+				details: {
+					loaded: false,
+					alreadyLoaded: true
+				}
+			};
+			let content = await registry.readContent(name);
+			if (content === null) return {
+				content: [{
+					type: `text`,
+					text: `Error: could not read skill file for "${name}".`
+				}],
+				details: { loaded: false }
+			};
+			let truncated = false;
+			if (content.length > meta.max) {
+				truncated = true;
+				content = content.slice(0, meta.max);
+			}
+			if (args) content = substituteArgs(content, args, meta.arguments);
+			ctx.insertContext(contextId, {
+				name: `skill_instructions`,
+				attrs: {
+					skill: name,
+					type: `directive`
+				},
+				content
+			});
+			const skillDir = path.join(path.dirname(meta.source), name);
+			const truncNote = truncated ? `\n\nWARNING: Content was truncated from ${meta.charCount.toLocaleString()} to ${meta.max.toLocaleString()} chars. Inform the user.` : ``;
+			const allRefFiles = listRefFiles(skillDir);
+			const mdFiles = allRefFiles.filter((f) => f.endsWith(`.md`));
+			const refContents = [];
+			for (const f of mdFiles) try {
+				const refContent = await fs.readFile(path.join(skillDir, f), `utf-8`);
+				const refId = `${skillContextId(name)}:${f}`;
+				ctx.insertContext(refId, {
+					name: `skill_reference`,
+					attrs: {
+						skill: name,
+						file: f
+					},
+					content: refContent
+				});
+				refContents.push(`--- ${f} ---\n${refContent}`);
+			} catch {}
+			const hasRefDir = allRefFiles.length > 0;
+			const dirNote = hasRefDir ? `\nSkill directory: ${skillDir}` : ``;
+			const refSection = refContents.length > 0 ? `\n\n${refContents.join(`\n\n`)}` : ``;
+			const toolResult = `SKILL ACTIVATED: "${name}". The instructions below override your default behavior. Follow them exactly. Do not read any files to find this content — it is all here.\n${dirNote}${truncNote}\n\n${content}${refSection}`;
+			return {
+				content: [{
+					type: `text`,
+					text: toolResult
+				}],
+				details: {
+					loaded: true,
+					truncated,
+					chars: content.length
+				}
+			};
+		}
+	};
+	const removeSkill = {
+		name: `remove_skill`,
+		label: `Remove Skill`,
+		description: `Unload a previously loaded skill from your context.`,
+		parameters: Type.Object({ name: Type.String({ description: `Name of the skill to remove` }) }),
+		execute: async (_toolCallId, params) => {
+			const { name } = params;
+			ctx.removeContext(skillContextId(name));
+			const meta = registry.catalog.get(name);
+			if (meta) {
+				const skillDir = path.join(path.dirname(meta.source), name);
+				for (const f of listRefFiles(skillDir)) ctx.removeContext(`${skillContextId(name)}:${f}`);
+			}
+			return {
+				content: [{
+					type: `text`,
+					text: `Skill "${name}" removed from context.`
+				}],
+				details: { removed: true }
+			};
+		}
+	};
+	return [useSkill, removeSkill];
+}
+function parseArgs(raw) {
+	const args = [];
+	let current = ``;
+	let inQuote = false;
+	let quoteChar = ``;
+	for (const ch of raw) if (inQuote) if (ch === quoteChar) inQuote = false;
+	else current += ch;
+	else if (ch === `"` || ch === `'`) {
+		inQuote = true;
+		quoteChar = ch;
+	} else if (ch === ` ` || ch === `\t`) {
+		if (current.length > 0) {
+			args.push(current);
+			current = ``;
+		}
+	} else current += ch;
+	if (current.length > 0) args.push(current);
+	return args;
+}
+function substituteArgs(content, rawArgs, argNames) {
+	const parsed = parseArgs(rawArgs);
+	let result = content;
+	let matched = false;
+	if (argNames) for (let i = 0; i < argNames.length && i < parsed.length; i++) {
+		const pattern = new RegExp(`\\$${argNames[i]}\\b`, `g`);
+		if (pattern.test(result)) {
+			result = result.replace(pattern, parsed[i]);
+			matched = true;
+		}
+	}
+	for (let i = 0; i < parsed.length; i++) {
+		const pattern = new RegExp(`\\$${i}\\b`, `g`);
+		if (pattern.test(result)) {
+			result = result.replace(pattern, parsed[i]);
+			matched = true;
+		}
+	}
+	if (result.includes(`$ARGUMENTS`)) {
+		result = result.replace(/\$ARGUMENTS/g, rawArgs);
+		matched = true;
+	}
+	if (!matched) result += `\n\nArguments: ${rawArgs}`;
+	return result;
+}
+function listRefFiles(dir, prefix = ``) {
+	try {
+		const results = [];
+		for (const entry of fsSync.readdirSync(dir)) {
+			const full = path.join(dir, entry);
+			const rel = prefix ? `${prefix}/${entry}` : entry;
+			if (fsSync.statSync(full).isDirectory()) results.push(...listRefFiles(full, rel));
+			else results.push(rel);
+		}
+		return results;
+	} catch {
+		return [];
+	}
+}
+
 //#endregion
 //#region src/tools/bash.ts
 const TIMEOUT_MS = 3e4;
@@ -1257,7 +1435,22 @@ async function generateTitle(userMessage, llmCall = defaultHaikuCall) {
 }
 function buildHortonSystemPrompt(workingDirectory, opts = {}) {
 	const docsTools = opts.hasDocsSupport ? `\n- search_durable_agents_docs: hybrid search over the built-in Durable Agents docs index` : ``;
+	const skillsTools = opts.hasSkills ? `\n- use_skill: load a skill (knowledge, instructions, or a tutorial) into your context to help with the user's request\n- remove_skill: unload a skill from context when you're done with it` : ``;
 	const docsGuidance = opts.hasDocsSupport ? `\n- You have built-in Durable Agents docs context plus a docs search tool. Use that before broad web search when the question is about this repo, Electric Agents, or Durable Agents.\n- The docs TOC and docs search results include concrete file paths under the docs tree. Use the normal read tool with those returned paths.\n- Use repo read/bash tools for non-doc files or when you need to inspect exact implementation code in the workspace.` : ``;
+	const skillsGuidance = opts.hasSkills ? `\n# Skills\nYou have access to skills — specialized knowledge and guided workflows you can load on demand. Your context includes a skills catalog listing what's available. When the user's request matches a skill's description or keywords, load it with use_skill.
+
+Some skills are user-invocable — the user can trigger them with a slash command like \`/tutorial\`. When you see a message starting with \`/\` followed by a skill name, load that skill immediately with use_skill. Pass any text after the skill name as args.
+
+## IMPORTANT: How to use a loaded skill
+
+When you load a skill, it becomes your primary directive for that interaction. Follow the skill's instructions exactly:
+
+1. **Read all reference files first.** The use_skill tool response lists reference files with absolute paths. Read ALL of them with your read tool before responding to the user. These files contain the actual content the skill needs — without them you're guessing.
+2. **Follow the skill's conversation flow.** If the skill defines steps, follow them in order. Do not improvise your own approach.
+3. **Adopt the skill's persona and teaching style.** The skill defines how to interact — follow it.
+4. **Unload when done.** Use remove_skill to free context space when the skill's workflow is complete.
+
+Do NOT load a skill and then ignore its instructions. The skill is there because it contains a tested, specific workflow. Your job is to execute it faithfully.` : ``;
 	return `You are Horton, a friendly and capable assistant. You can chat, research the web, read and edit code, run shell commands, and dispatch subagents (workers) for isolated subtasks. Be warm and engaging in conversation; be precise and concrete when working with code.
 
 # Tools
@@ -1268,13 +1461,13 @@ function buildHortonSystemPrompt(workingDirectory, opts = {}) {
 - brave_search: search the web
 - fetch_url: fetch and convert a URL to markdown
 - spawn_worker: dispatch a subagent for an isolated task
-${docsTools}
+${docsTools}${skillsTools}
 
 # Working with files
 - Prefer edit over write when modifying existing files.
 - You must read a file before you can edit it.
 - Use absolute paths or paths relative to the current working directory.
-${docsGuidance}
+${docsGuidance}${skillsGuidance}
 
 # Risky actions
 Pause and confirm with the user before:
@@ -1325,10 +1518,15 @@ function extractFirstUserMessage(events) {
 	return null;
 }
 function createAssistantHandler(options) {
-	const { workingDirectory, streamFn, docsSupport, docsSearchTool } = options;
+	const { workingDirectory, streamFn, docsSupport, docsSearchTool, skillsRegistry } = options;
+	const hasSkills = Boolean(skillsRegistry && skillsRegistry.catalog.size > 0);
 	return async function assistantHandler(ctx, wake) {
 		const readSet = new Set();
-		const tools = [...ctx.electricTools, ...createHortonTools(workingDirectory, ctx, readSet, { docsSearchTool })];
+		const tools = [
+			...ctx.electricTools,
+			...createHortonTools(workingDirectory, ctx, readSet, { docsSearchTool }),
+			...skillsRegistry && skillsRegistry.catalog.size > 0 ? createSkillTools(skillsRegistry, ctx) : []
+		];
 		if (docsSupport) ctx.useContext({
 			sourceBudget: 1e5,
 			sources: {
@@ -1342,6 +1540,25 @@ function createAssistantHandler(options) {
 					max: 6e3,
 					cache: `volatile`
 				},
+				conversation: {
+					content: () => ctx.timelineMessages(),
+					cache: `volatile`
+				},
+				...skillsRegistry && skillsRegistry.catalog.size > 0 ? { skills_catalog: {
+					content: () => skillsRegistry.renderCatalog(2e3),
+					max: 2e3,
+					cache: `stable`
+				} } : {}
+			}
+		});
+		else if (skillsRegistry && skillsRegistry.catalog.size > 0) ctx.useContext({
+			sourceBudget: 1e5,
+			sources: {
+				skills_catalog: {
+					content: () => skillsRegistry.renderCatalog(2e3),
+					max: 2e3,
+					cache: `stable`
+				},
 				conversation: {
 					content: () => ctx.timelineMessages(),
 					cache: `volatile`
@@ -1349,7 +1566,10 @@ function createAssistantHandler(options) {
 			}
 		});
 		ctx.useAgent({
-			systemPrompt: buildHortonSystemPrompt(workingDirectory, { hasDocsSupport: Boolean(docsSupport) }),
+			systemPrompt: buildHortonSystemPrompt(workingDirectory, {
+				hasDocsSupport: Boolean(docsSupport),
+				hasSkills
+			}),
 			model: HORTON_MODEL,
 			tools,
 			...streamFn && { streamFn }
@@ -1375,7 +1595,7 @@ function createAssistantHandler(options) {
 	};
 }
 function registerHorton(registry, options) {
-	const { workingDirectory, streamFn } = options;
+	const { workingDirectory, streamFn, skillsRegistry = null } = options;
 	const docsSupport = createHortonDocsSupport(workingDirectory);
 	const docsSearchTool = docsSupport?.createSearchTool();
 	docsSupport?.ensureReady().catch((error) => {
@@ -1385,7 +1605,8 @@ function registerHorton(registry, options) {
 		workingDirectory,
 		streamFn,
 		docsSupport,
-		docsSearchTool
+		docsSearchTool,
+		skillsRegistry
 	});
 	registry.define(`horton`, {
 		description: `Friendly capable assistant — chat, code, research, dispatch`,
@@ -1407,18 +1628,33 @@ function registerHorton(registry, options) {
 function isWorkerToolName(value) {
 	return typeof value === `string` && WORKER_TOOL_NAMES.includes(value);
 }
+function isRecord(value) {
+	return value !== null && typeof value === `object`;
+}
 function parseWorkerArgs(value) {
 	if (typeof value.systemPrompt !== `string` || value.systemPrompt.length === 0) throw new Error(`[worker] systemPrompt is required`);
-	if (!Array.isArray(value.tools) || value.tools.length === 0) throw new Error(`[worker] tools must be a non-empty array`);
 	const tools = [];
-	for (const t of value.tools) {
+	if (Array.isArray(value.tools)) for (const t of value.tools) {
 		if (!isWorkerToolName(t)) throw new Error(`[worker] unknown tool name: ${JSON.stringify(t)}. Valid tools: ${WORKER_TOOL_NAMES.join(`, `)}`);
 		if (!tools.includes(t)) tools.push(t);
 	}
-	return {
+	const args = {
 		systemPrompt: value.systemPrompt,
 		tools
 	};
+	if (value.sharedDbToolMode === `full` || value.sharedDbToolMode === `write-only`) args.sharedDbToolMode = value.sharedDbToolMode;
+	if (value.sharedDb !== void 0) {
+		if (!isRecord(value.sharedDb)) throw new Error(`[worker] sharedDb must be an object`);
+		const { id, schema } = value.sharedDb;
+		if (typeof id !== `string` || id.length === 0) throw new Error(`[worker] sharedDb.id must be a non-empty string`);
+		if (!isRecord(schema)) throw new Error(`[worker] sharedDb.schema must be an object`);
+		args.sharedDb = {
+			id,
+			schema
+		};
+	}
+	if (tools.length === 0 && !args.sharedDb) throw new Error(`[worker] must provide tools and/or sharedDb`);
+	return args;
 }
 function buildToolsForWorker(tools, workingDirectory, ctx, readSet) {
 	const out = [];
@@ -1451,18 +1687,115 @@ const WORKER_PROMPT_FOOTER = `
 
 # Reporting back
 When you finish, respond with a concise report covering what was done and any key findings. The caller will relay this to the user, so it only needs the essentials.`;
+function buildSharedStateTools(shared, schema, mode) {
+	const tools = [];
+	for (const [collectionName] of Object.entries(schema)) {
+		if (collectionName === `id`) continue;
+		const handle = shared[collectionName];
+		if (!handle) continue;
+		tools.push({
+			name: `write_${collectionName}`,
+			label: `Write ${collectionName}`,
+			description: `Write an entry to the shared ${collectionName} collection. The data must include a unique 'key' field.`,
+			parameters: Type.Object({ data: Type.Record(Type.String(), Type.Unknown(), { description: `The data object to write` }) }),
+			execute: async (_id, params) => {
+				const { data } = params;
+				handle.insert(data);
+				return {
+					content: [{
+						type: `text`,
+						text: `Written to ${collectionName}: ${JSON.stringify(data)}`
+					}],
+					details: {}
+				};
+			}
+		});
+		if (mode === `write-only`) continue;
+		tools.push({
+			name: `read_${collectionName}`,
+			label: `Read ${collectionName}`,
+			description: `Read all entries from the shared ${collectionName} collection.`,
+			parameters: Type.Object({}),
+			execute: async () => {
+				const entries = handle.toArray;
+				return {
+					content: [{
+						type: `text`,
+						text: JSON.stringify(entries, null, 2)
+					}],
+					details: {}
+				};
+			}
+		});
+		tools.push({
+			name: `update_${collectionName}`,
+			label: `Update ${collectionName}`,
+			description: `Update an existing entry in the shared ${collectionName} collection by key.`,
+			parameters: Type.Object({
+				key: Type.String({ description: `The key of the entry to update` }),
+				data: Type.Record(Type.String(), Type.Unknown(), { description: `The fields to update` })
+			}),
+			execute: async (_id, params) => {
+				const { key, data } = params;
+				try {
+					handle.update(key, (draft) => {
+						Object.assign(draft, data);
+					});
+				} catch (err) {
+					return {
+						content: [{
+							type: `text`,
+							text: `Failed to update ${collectionName} entry "${key}": ${err instanceof Error ? err.message : String(err)}`
+						}],
+						details: {}
+					};
+				}
+				return {
+					content: [{
+						type: `text`,
+						text: `Updated ${collectionName} entry "${key}"`
+					}],
+					details: {}
+				};
+			}
+		});
+		tools.push({
+			name: `delete_${collectionName}`,
+			label: `Delete ${collectionName}`,
+			description: `Delete an entry from the shared ${collectionName} collection by key.`,
+			parameters: Type.Object({ key: Type.String({ description: `The key of the entry to delete` }) }),
+			execute: async (_id, params) => {
+				const { key } = params;
+				handle.delete(key);
+				return {
+					content: [{
+						type: `text`,
+						text: `Deleted ${collectionName} entry "${key}"`
+					}],
+					details: {}
+				};
+			}
+		});
+	}
+	return tools;
+}
 function registerWorker(registry, options) {
 	const { workingDirectory, streamFn } = options;
 	registry.define(`worker`, {
-		description: `Internal — generic worker spawned by other agents. Configure via spawn args (systemPrompt + tools).`,
+		description: `Internal — generic worker spawned by other agents. Configure via spawn args (systemPrompt + tools + optional sharedDb).`,
 		async handler(ctx) {
 			const args = parseWorkerArgs(ctx.args);
 			const readSet = new Set();
-			const tools = buildToolsForWorker(args.tools, workingDirectory, ctx, readSet);
+			const builtinTools = buildToolsForWorker(args.tools, workingDirectory, ctx, readSet);
+			const sharedStateTools = [];
+			if (args.sharedDb) {
+				const shared = await ctx.observe(db(args.sharedDb.id, args.sharedDb.schema));
+				sharedStateTools.push(...buildSharedStateTools(shared, args.sharedDb.schema, args.sharedDbToolMode ?? `full`));
+			}
 			ctx.useAgent({
 				systemPrompt: `${args.systemPrompt}${WORKER_PROMPT_FOOTER}`,
 				model: HORTON_MODEL,
-				tools,
+				tools: [...builtinTools, ...sharedStateTools],
 				...streamFn && { streamFn }
 			});
 			await ctx.agent.run();
@@ -1470,20 +1803,289 @@ function registerWorker(registry, options) {
 	});
 }
 
+//#endregion
+//#region src/skills/preamble.ts
+function parsePreamble(content) {
+	const lines = content.split(`\n`);
+	if (lines[0]?.trim() !== `---`) return {};
+	let closingIndex = -1;
+	for (let i = 1; i < Math.min(lines.length, 25); i++) if (lines[i]?.trim() === `---`) {
+		closingIndex = i;
+		break;
+	}
+	if (closingIndex === -1) return {};
+	const result = {};
+	for (let i = 1; i < closingIndex; i++) {
+		const line = lines[i];
+		const colonIndex = line.indexOf(`:`);
+		if (colonIndex === -1) continue;
+		const key = line.slice(0, colonIndex).trim();
+		const rawValue = line.slice(colonIndex + 1).trim();
+		switch (key) {
+			case `description`:
+				result.description = stripQuotes(rawValue);
+				break;
+			case `whenToUse`:
+				result.whenToUse = stripQuotes(rawValue);
+				break;
+			case `keywords`: {
+				if (rawValue.length === 0) {
+					const items = [];
+					for (let j = i + 1; j < closingIndex; j++) {
+						const next = lines[j];
+						const match = next.match(/^\s+-\s+(.+)$/);
+						if (match) {
+							items.push(match[1].trim());
+							i = j;
+						} else break;
+					}
+					result.keywords = items;
+				} else result.keywords = parseKeywords(rawValue);
+				break;
+			}
+			case `arguments`: {
+				if (rawValue.length === 0) {
+					const items = [];
+					for (let j = i + 1; j < closingIndex; j++) {
+						const next = lines[j];
+						const match = next.match(/^\s+-\s+(.+)$/);
+						if (match) {
+							items.push(match[1].trim());
+							i = j;
+						} else break;
+					}
+					result.arguments = items;
+				} else result.arguments = parseKeywords(rawValue);
+				break;
+			}
+			case `argument-hint`:
+				result.argumentHint = stripQuotes(rawValue);
+				break;
+			case `user-invocable`:
+				result.userInvocable = rawValue === `true`;
+				break;
+			case `max`: {
+				const num = parseInt(rawValue, 10);
+				if (!Number.isNaN(num) && num > 0) result.max = num;
+				break;
+			}
+		}
+	}
+	return result;
+}
+function parseKeywords(raw) {
+	const stripped = raw.replace(/^\[/, ``).replace(/\]$/, ``);
+	return stripped.split(`,`).map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function stripQuotes(value) {
+	if (value.length >= 2 && value.startsWith(`"`) && value.endsWith(`"`)) return value.slice(1, -1);
+	return value;
+}
+
+//#endregion
+//#region src/skills/extract-meta.ts
+const EXTRACT_MODEL = `claude-haiku-4-5-20251001`;
+const DEFAULT_MAX = 1e4;
+async function extractSkillMeta(name, content) {
+	const preamble = parsePreamble(content);
+	if (preamble.description && preamble.whenToUse && preamble.keywords) return {
+		description: preamble.description,
+		whenToUse: preamble.whenToUse,
+		keywords: preamble.keywords,
+		...preamble.arguments && { arguments: preamble.arguments },
+		...preamble.argumentHint && { argumentHint: preamble.argumentHint },
+		...preamble.userInvocable && { userInvocable: true },
+		max: preamble.max ?? DEFAULT_MAX
+	};
+	if (process.env.ANTHROPIC_API_KEY) try {
+		return await llmExtract(name, content, preamble);
+	} catch (err) {
+		serverLog.warn(`[skills] LLM metadata extraction failed for "${name}": ${err instanceof Error ? err.message : String(err)}`);
+	}
+	return {
+		description: preamble.description ?? humanize(name),
+		whenToUse: preamble.whenToUse ?? `User asks about ${humanize(name).toLowerCase()}`,
+		keywords: preamble.keywords ?? [name],
+		max: preamble.max ?? DEFAULT_MAX
+	};
+}
+async function llmExtract(name, content, partial) {
+	const client = new Anthropic();
+	const truncated = content.slice(0, 8e3);
+	const prompt = `Analyze this skill document and extract metadata. The skill is named "${name}".
+
+<skill>
+${truncated}
+</skill>
+
+Return ONLY a JSON object with these fields:
+- "description": one-line summary of what this skill provides (max 100 chars)
+- "whenToUse": when should an AI agent load this skill (max 200 chars)
+- "keywords": array of 3-8 relevant keywords
+
+Return raw JSON, no markdown fences.`;
+	const res = await client.messages.create({
+		model: EXTRACT_MODEL,
+		max_tokens: 256,
+		messages: [{
+			role: `user`,
+			content: prompt
+		}]
+	});
+	const text = res.content[0]?.type === `text` ? res.content[0].text : ``;
+	const parsed = JSON.parse(text);
+	return {
+		description: partial.description ?? parsed.description ?? humanize(name),
+		whenToUse: partial.whenToUse ?? parsed.whenToUse ?? `User asks about ${name}`,
+		keywords: partial.keywords ?? parsed.keywords ?? [name],
+		max: partial.max ?? DEFAULT_MAX
+	};
+}
+function humanize(name) {
+	return name.replace(/[-_]/g, ` `).replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+//#endregion
+//#region src/skills/registry.ts
+const CACHE_FILENAME = `skills-cache.json`;
+async function createSkillsRegistry(opts) {
+	const { baseSkillsDir, appSkillsDir, cacheDir } = opts;
+	const cachePath = path.join(cacheDir, CACHE_FILENAME);
+	const existingCache = await loadCache(cachePath);
+	const files = new Map();
+	await scanDir(baseSkillsDir, files);
+	if (appSkillsDir) await scanDir(appSkillsDir, files);
+	const catalog = new Map();
+	for (const [name, filePath] of files) {
+		const content = await fs.readFile(filePath, `utf-8`);
+		const hash = sha256(content);
+		const cached = existingCache[name];
+		if (cached && cached.contentHash === hash && cached.source === filePath) {
+			catalog.set(name, cached);
+			continue;
+		}
+		serverLog.info(`[skills] extracting metadata for "${name}"`);
+		const meta = await extractSkillMeta(name, content);
+		const entry = {
+			name,
+			...meta,
+			charCount: content.length,
+			contentHash: hash,
+			source: filePath
+		};
+		catalog.set(name, entry);
+	}
+	await saveCache(cachePath, catalog, cacheDir);
+	return {
+		catalog,
+		renderCatalog(budget) {
+			if (catalog.size === 0) return ``;
+			const skills = Array.from(catalog.values());
+			const full = renderSkillList(skills, `full`);
+			if (!budget || full.length <= budget) return full;
+			const compact = renderSkillList(skills, `compact`);
+			if (compact.length <= budget) return compact;
+			return renderSkillList(skills, `names`);
+		},
+		async readContent(name) {
+			const meta = catalog.get(name);
+			if (!meta) return null;
+			try {
+				return await fs.readFile(meta.source, `utf-8`);
+			} catch {
+				return null;
+			}
+		}
+	};
+}
+async function scanDir(dir, out) {
+	let entries;
+	try {
+		entries = await fs.readdir(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		if (!entry.isFile() || !entry.name.endsWith(`.md`)) continue;
+		const name = entry.name.slice(0, -3);
+		out.set(name, path.resolve(dir, entry.name));
+	}
+}
+async function loadCache(cachePath) {
+	try {
+		const raw = await fs.readFile(cachePath, `utf-8`);
+		return JSON.parse(raw);
+	} catch {
+		return {};
+	}
+}
+async function saveCache(cachePath, catalog, cacheDir) {
+	const obj = {};
+	for (const [name, meta] of catalog) obj[name] = meta;
+	fsSync.mkdirSync(cacheDir, { recursive: true });
+	await fs.writeFile(cachePath, JSON.stringify(obj, null, 2), `utf-8`);
+}
+function sha256(content) {
+	return createHash(`sha256`).update(content).digest(`hex`);
+}
+function renderSkillList(skills, mode) {
+	const invocable = skills.filter((s) => s.userInvocable);
+	const others = skills.filter((s) => !s.userInvocable);
+	const lines = [`Available skills:`];
+	if (invocable.length > 0 && mode !== `names`) {
+		lines.push(`\nUser-invocable (the user can trigger these directly):`);
+		for (const meta of invocable) {
+			const hint = meta.argumentHint ? ` ${meta.argumentHint}` : ``;
+			lines.push(`- /${meta.name}${hint} — ${mode === `compact` ? truncate(meta.description, 100) : meta.description}`);
+		}
+		if (others.length > 0) lines.push(``);
+	}
+	const all = mode === `names` ? skills : others.length > 0 ? others : invocable.length === 0 ? skills : [];
+	for (const meta of all) {
+		if (mode === `names`) {
+			const prefix = meta.userInvocable ? `/${meta.name}` : meta.name;
+			lines.push(`- ${prefix}: ${truncate(meta.description, 60)}`);
+			continue;
+		}
+		lines.push(`- ${meta.name} (${meta.charCount.toLocaleString()} chars): ${mode === `compact` ? truncate(meta.description, 100) : meta.description}`);
+		lines.push(`  Use when: ${meta.whenToUse}`);
+		if (mode === `full`) lines.push(`  Keywords: ${meta.keywords.join(`, `)}`);
+		if (meta.argumentHint) lines.push(`  Usage: use_skill("${meta.name}", "${meta.argumentHint}")`);
+	}
+	return lines.join(`\n`);
+}
+function truncate(str, max) {
+	return str.length <= max ? str : str.slice(0, max - 3) + `...`;
+}
+
 //#endregion
 //#region src/bootstrap.ts
 const DEFAULT_BUILTIN_AGENT_HANDLER_PATH = `/_electric/builtin-agent-handler`;
-function createBuiltinAgentHandler(options) {
+async function createBuiltinAgentHandler(options) {
 	const { agentServerUrl, serveEndpoint = `${agentServerUrl}${DEFAULT_BUILTIN_AGENT_HANDLER_PATH}`, workingDirectory, streamFn, createElectricTools } = options;
 	if (!streamFn && !process.env.ANTHROPIC_API_KEY) {
 		serverLog.warn(`[builtin-agents] ANTHROPIC_API_KEY not set — skipping built-in agent registration`);
 		return null;
 	}
 	const cwd = workingDirectory ?? process.cwd();
+	const here = path.dirname(fileURLToPath(import.meta.url));
+	const baseSkillsDir = path.resolve(here, `../skills`);
+	let skillsRegistry = null;
+	try {
+		skillsRegistry = await createSkillsRegistry({
+			baseSkillsDir,
+			appSkillsDir: path.resolve(cwd, `skills`),
+			cacheDir: path.resolve(cwd, `.electric-agents`)
+		});
+		if (skillsRegistry.catalog.size > 0) serverLog.info(`[electric-agents] ${skillsRegistry.catalog.size} skill(s) loaded: ${Array.from(skillsRegistry.catalog.keys()).join(`, `)}`);
+	} catch (err) {
+		serverLog.warn(`[electric-agents] skills registry failed to initialize: ${err instanceof Error ? err.message : String(err)}`);
+	}
 	const registry = createEntityRegistry();
 	const typeNames = registerHorton(registry, {
 		workingDirectory: cwd,
-		streamFn
+		streamFn,
+		skillsRegistry
 	});
 	registerWorker(registry, {
 		workingDirectory: cwd,
@@ -1502,10 +2104,11 @@ function createBuiltinAgentHandler(options) {
 		handler: runtime.onEnter,
 		runtime,
 		registry,
-		typeNames
+		typeNames,
+		skillsRegistry
 	};
 }
-function createAgentHandler(agentServerUrl, workingDirectory, streamFn, createElectricTools, serveEndpoint) {
+async function createAgentHandler(agentServerUrl, workingDirectory, streamFn, createElectricTools, serveEndpoint) {
 	return createBuiltinAgentHandler({
 		agentServerUrl,
 		serveEndpoint,
@@ -1564,7 +2167,7 @@ var BuiltinAgentsServer = class {
 					this.publicBaseUrl = this.options.baseUrl ?? this._url;
 					const webhookPath = this.options.webhookPath ?? DEFAULT_BUILTIN_AGENT_HANDLER_PATH;
 					const serveEndpoint = new URL(webhookPath, this.publicBaseUrl.endsWith(`/`) ? this.publicBaseUrl : `${this.publicBaseUrl}/`).toString();
-					this.bootstrap = createBuiltinAgentHandler({
+					this.bootstrap = await createBuiltinAgentHandler({
 						agentServerUrl: this.options.agentServerUrl,
 						serveEndpoint,
 						workingDirectory: this.options.workingDirectory,