@vellumai/assistant 0.4.41 → 0.4.43

package/src/daemon/handlers/skills.ts

@@ -1,5 +1,4 @@
 import { existsSync, rmSync } from "node:fs";
-import * as net from "node:net";
 import { join } from "node:path";
 
 import {
@@ -24,6 +23,7 @@ import {
 import {
   clawhubCheckUpdates,
   clawhubInspect,
+  type ClawhubInspectResult,
   clawhubInstall,
   clawhubSearch,
   clawhubUpdate,
@@ -48,7 +48,7 @@ import type {
   SkillsSearchRequest,
   SkillsUninstallRequest,
   SkillsUpdateRequest,
-} from "../ipc-protocol.js";
+} from "../message-protocol.js";
 import {
   CONFIG_RELOAD_DEBOUNCE_MS,
   defineHandlers,
@@ -57,6 +57,20 @@ import {
   log,
 } from "./shared.js";
 
+// ─── Shared context for standalone functions ─────────────────────────────────
+
+/**
+ * Minimal context needed by the standalone skill business-logic functions.
+ * HandlerContext satisfies this interface, but HTTP routes can also provide
+ * a compatible object without coupling to IPC internals.
+ */
+export interface SkillOperationContext {
+  debounceTimers: HandlerContext["debounceTimers"];
+  setSuppressConfigReload(value: boolean): void;
+  updateConfigFingerprint(): void;
+  broadcast: HandlerContext["broadcast"];
+}
+
 // ─── Provenance resolution ──────────────────────────────────────────────────
 
 interface SkillProvenance {
@@ -103,17 +117,147 @@ function resolveProvenance(summary: SkillSummary): SkillProvenance {
   return { kind: "local" };
 }
 
-export function handleSkillsList(
-  socket: net.Socket,
-  ctx: HandlerContext,
+// ─── Frontmatter parsing ─────────────────────────────────────────────────────
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+interface ParsedFrontmatter {
+  skillId?: string;
+  name?: string;
+  description?: string;
+  emoji?: string;
+  body: string;
+}
+
+function parseFrontmatter(sourceText: string): ParsedFrontmatter {
+  const match = FRONTMATTER_RE.exec(sourceText);
+  if (!match) return { body: sourceText };
+
+  const yamlBlock = match[1];
+  const body = match[2].replace(/\r\n/g, "\n");
+
+  const result: ParsedFrontmatter = { body };
+
+  // Simple YAML key-value extraction (handles quoted and unquoted values)
+  for (const line of yamlBlock.split(/\r?\n/)) {
+    const kvMatch = /^(\w[\w-]*):\s*(.+)$/.exec(line.trim());
+    if (!kvMatch) continue;
+    const key = kvMatch[1];
+    // Strip surrounding quotes
+    let value = kvMatch[2].trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    switch (key) {
+      case "skill-id":
+      case "skillId":
+      case "id":
+        result.skillId = value;
+        break;
+      case "name":
+        result.name = value;
+        break;
+      case "description":
+        result.description = value;
+        break;
+      case "emoji":
+        result.emoji = value;
+        break;
+    }
+  }
+
+  return result;
+}
+
+// ─── Slug normalization ──────────────────────────────────────────────────────
+
+function toSkillSlug(raw: string): string {
+  return raw
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-") // replace non-valid chars with hyphens
+    .replace(/^[^a-z0-9]+/, "") // must start with alphanumeric
+    .replace(/-+/g, "-") // collapse multiple hyphens
+    .slice(0, 50)
+    .replace(/-$/, ""); // no trailing hyphen (after truncation)
+}
+
+// ─── Deterministic heuristic draft ───────────────────────────────────────────
+
+function heuristicDraft(body: string): {
+  skillId: string;
+  name: string;
+  description: string;
+  emoji: string;
+} {
+  const lines = body.split("\n").filter((l) => l.trim());
+  const firstLine = lines[0]?.trim() ?? "";
+  const name =
+    firstLine.replace(/^#+\s*/, "").slice(0, 100) || "Untitled Skill";
+  const skillId = toSkillSlug(name) || "untitled-skill";
+  const description = body.trim().slice(0, 200) || "No description provided";
+  return { skillId, name, description, emoji: "\u{1F4DD}" };
+}
+
+const LLM_DRAFT_TIMEOUT_MS = 15_000;
+
+// ─── Standalone business-logic functions ─────────────────────────────────────
+// These are consumed by both the IPC handlers below and the HTTP route layer.
+
+/** Helper: suppress config reload, save, debounce, and update fingerprint. */
+function saveConfigWithSuppression(
+  raw: Record<string, unknown>,
+  ctx: SkillOperationContext,
 ): void {
+  ctx.setSuppressConfigReload(true);
+  try {
+    saveRawConfig(raw);
+  } catch (err) {
+    ctx.setSuppressConfigReload(false);
+    throw err;
+  }
+  invalidateConfigCache();
+
+  ctx.debounceTimers.schedule(
+    "__suppress_reset__",
+    () => {
+      ctx.setSuppressConfigReload(false);
+    },
+    CONFIG_RELOAD_DEBOUNCE_MS,
+  );
+
+  ctx.updateConfigFingerprint();
+}
+
+export interface SkillListItem {
+  id: string;
+  name: string;
+  description: string;
+  emoji?: string;
+  homepage?: string;
+  source: "bundled" | "managed" | "workspace" | "clawhub" | "extra";
+  state: "enabled" | "disabled" | "available";
+  degraded: boolean;
+  missingRequirements?: {
+    bins?: string[];
+    env?: string[];
+    permissions?: string[];
+  };
+  updateAvailable: boolean;
+  userInvocable: boolean;
+  provenance: SkillProvenance;
+}
+
+export function listSkills(_ctx: SkillOperationContext): SkillListItem[] {
   const config = getConfig();
   const catalog = loadSkillCatalog();
   const resolved = resolveSkillStates(catalog, config);
 
-  const skills = resolved.map((r) => ({
+  return resolved.map((r) => ({
     id: r.summary.id,
-    name: r.summary.name,
+    name: r.summary.displayName,
     description: r.summary.description,
     emoji: r.summary.emoji,
     homepage: r.summary.homepage,
@@ -128,340 +272,169 @@ export function handleSkillsList(
     userInvocable: r.summary.userInvocable,
     provenance: resolveProvenance(r.summary),
   }));
-
-  ctx.send(socket, { type: "skills_list_response", skills });
 }
 
-export function handleSkillsEnable(
-  msg: SkillsEnableRequest,
-  socket: net.Socket,
-  ctx: HandlerContext,
-): void {
+export function enableSkill(
+  skillId: string,
+  ctx: SkillOperationContext,
+): { success: true } | { success: false; error: string } {
   try {
     const raw = loadRawConfig();
-    ensureSkillEntry(raw, msg.name).enabled = true;
-
-    ctx.setSuppressConfigReload(true);
-    try {
-      saveRawConfig(raw);
-    } catch (err) {
-      ctx.setSuppressConfigReload(false);
-      throw err;
-    }
-    invalidateConfigCache();
-
-    ctx.debounceTimers.schedule(
-      "__suppress_reset__",
-      () => {
-        ctx.setSuppressConfigReload(false);
-      },
-      CONFIG_RELOAD_DEBOUNCE_MS,
-    );
-
-    ctx.updateConfigFingerprint();
-
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "enable",
-      success: true,
-    });
+    ensureSkillEntry(raw, skillId).enabled = true;
+    saveConfigWithSuppression(raw, ctx);
     ctx.broadcast({
       type: "skills_state_changed",
-      name: msg.name,
+      name: skillId,
       state: "enabled",
     });
+    return { success: true };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Failed to enable skill");
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "enable",
-      success: false,
-      error: message,
-    });
+    return { success: false, error: message };
   }
 }
 
-export function handleSkillsDisable(
-  msg: SkillsDisableRequest,
-  socket: net.Socket,
-  ctx: HandlerContext,
-): void {
+export function disableSkill(
+  skillId: string,
+  ctx: SkillOperationContext,
+): { success: true } | { success: false; error: string } {
   try {
     const raw = loadRawConfig();
-    ensureSkillEntry(raw, msg.name).enabled = false;
-
-    ctx.setSuppressConfigReload(true);
-    try {
-      saveRawConfig(raw);
-    } catch (err) {
-      ctx.setSuppressConfigReload(false);
-      throw err;
-    }
-    invalidateConfigCache();
-
-    ctx.debounceTimers.schedule(
-      "__suppress_reset__",
-      () => {
-        ctx.setSuppressConfigReload(false);
-      },
-      CONFIG_RELOAD_DEBOUNCE_MS,
-    );
-
-    ctx.updateConfigFingerprint();
-
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "disable",
-      success: true,
-    });
+    ensureSkillEntry(raw, skillId).enabled = false;
+    saveConfigWithSuppression(raw, ctx);
     ctx.broadcast({
       type: "skills_state_changed",
-      name: msg.name,
+      name: skillId,
       state: "disabled",
     });
+    return { success: true };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Failed to disable skill");
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "disable",
-      success: false,
-      error: message,
-    });
+    return { success: false, error: message };
   }
 }
 
-export function handleSkillsConfigure(
-  msg: SkillsConfigureRequest,
-  socket: net.Socket,
-  ctx: HandlerContext,
-): void {
+export function configureSkill(
+  skillId: string,
+  config: { env?: Record<string, string>; apiKey?: string; config?: Record<string, unknown> },
+  ctx: SkillOperationContext,
+): { success: true } | { success: false; error: string } {
   try {
     const raw = loadRawConfig();
-
-    const entry = ensureSkillEntry(raw, msg.name);
-    if (msg.env) {
-      entry.env = msg.env;
-    }
-    if (msg.apiKey !== undefined) {
-      entry.apiKey = msg.apiKey;
-    }
-    if (msg.config) {
-      entry.config = msg.config;
-    }
-
-    ctx.setSuppressConfigReload(true);
-    try {
-      saveRawConfig(raw);
-    } catch (err) {
-      ctx.setSuppressConfigReload(false);
-      throw err;
-    }
-    invalidateConfigCache();
-
-    ctx.debounceTimers.schedule(
-      "__suppress_reset__",
-      () => {
-        ctx.setSuppressConfigReload(false);
-      },
-      CONFIG_RELOAD_DEBOUNCE_MS,
-    );
-
-    ctx.updateConfigFingerprint();
-
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "configure",
-      success: true,
-    });
+    const entry = ensureSkillEntry(raw, skillId);
+    if (config.env) entry.env = config.env;
+    if (config.apiKey !== undefined) entry.apiKey = config.apiKey;
+    if (config.config) entry.config = config.config;
+    saveConfigWithSuppression(raw, ctx);
+    return { success: true };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Failed to configure skill");
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "configure",
-      success: false,
-      error: message,
-    });
+    return { success: false, error: message };
   }
 }
 
-export async function handleSkillsInstall(
-  msg: SkillsInstallRequest,
-  socket: net.Socket,
-  ctx: HandlerContext,
-): Promise<void> {
+export async function installSkill(
+  spec: { slug: string; version?: string },
+  ctx: SkillOperationContext,
+): Promise<{ success: true } | { success: false; error: string }> {
   try {
     // Bundled skills are already available — no install needed
     const catalog = loadSkillCatalog();
     const bundled = catalog.find(
-      (s) => s.id === msg.slug && s.source === "bundled",
+      (s) => s.id === spec.slug && s.source === "bundled",
     );
     if (bundled) {
       // Auto-enable the bundled skill so it's immediately usable
-      let autoEnabled = false;
       try {
         const raw = loadRawConfig();
-        ensureSkillEntry(raw, msg.slug).enabled = true;
-        ctx.setSuppressConfigReload(true);
-        try {
-          saveRawConfig(raw);
-        } catch (err) {
-          ctx.setSuppressConfigReload(false);
-          throw err;
-        }
-        invalidateConfigCache();
-        ctx.debounceTimers.schedule(
-          "__suppress_reset__",
-          () => {
-            ctx.setSuppressConfigReload(false);
-          },
-          CONFIG_RELOAD_DEBOUNCE_MS,
-        );
-        ctx.updateConfigFingerprint();
-        autoEnabled = true;
-      } catch (err) {
-        log.warn(
-          { err, skillId: msg.slug },
-          "Failed to auto-enable bundled skill",
-        );
-      }
-
-      ctx.send(socket, {
-        type: "skills_operation_response",
-        operation: "install",
-        success: true,
-      });
-      if (autoEnabled) {
+        ensureSkillEntry(raw, spec.slug).enabled = true;
+        saveConfigWithSuppression(raw, ctx);
         ctx.broadcast({
           type: "skills_state_changed",
-          name: msg.slug,
+          name: spec.slug,
           state: "enabled",
         });
+      } catch (err) {
+        log.warn(
+          { err, skillId: spec.slug },
+          "Failed to auto-enable bundled skill",
+        );
       }
-      return;
+      return { success: true };
     }
 
     // Install from clawhub (community)
-    const result = await clawhubInstall(msg.slug, { version: msg.version });
+    const result = await clawhubInstall(spec.slug, { version: spec.version });
     if (!result.success) {
-      ctx.send(socket, {
-        type: "skills_operation_response",
-        operation: "install",
-        success: false,
-        error: result.error ?? "Unknown error",
-      });
-      return;
+      return { success: false, error: result.error ?? "Unknown error" };
     }
-    const rawId = result.skillName ?? msg.slug;
+    const rawId = result.skillName ?? spec.slug;
     const skillId = rawId.includes("/") ? rawId.split("/").pop()! : rawId;
 
     // Reload skill catalog so the newly installed skill is picked up
     loadSkillCatalog();
 
-    // Auto-enable the newly installed skill so it's immediately usable.
-    let autoEnabled = false;
+    // Auto-enable the newly installed skill
     try {
       const raw = loadRawConfig();
       ensureSkillEntry(raw, skillId).enabled = true;
-      ctx.setSuppressConfigReload(true);
-      try {
-        saveRawConfig(raw);
-      } catch (err) {
-        ctx.setSuppressConfigReload(false);
-        throw err;
-      }
-      invalidateConfigCache();
-      ctx.debounceTimers.schedule(
-        "__suppress_reset__",
-        () => {
-          ctx.setSuppressConfigReload(false);
-        },
-        CONFIG_RELOAD_DEBOUNCE_MS,
-      );
-      ctx.updateConfigFingerprint();
-      autoEnabled = true;
-    } catch (err) {
-      log.warn({ err, skillId }, "Failed to auto-enable installed skill");
-    }
-
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "install",
-      success: true,
-    });
-    if (autoEnabled) {
+      saveConfigWithSuppression(raw, ctx);
       ctx.broadcast({
         type: "skills_state_changed",
         name: skillId,
         state: "enabled",
       });
+    } catch (err) {
+      log.warn({ err, skillId }, "Failed to auto-enable installed skill");
     }
+
+    return { success: true };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Failed to install skill");
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "install",
-      success: false,
-      error: message,
-    });
+    return { success: false, error: message };
   }
 }
 
-export async function handleSkillsUninstall(
-  msg: SkillsUninstallRequest,
-  socket: net.Socket,
-  ctx: HandlerContext,
-): Promise<void> {
+export async function uninstallSkill(
+  skillId: string,
+  ctx: SkillOperationContext,
+): Promise<{ success: true } | { success: false; error: string }> {
   // Validate skill name to prevent path traversal while allowing namespaced slugs (org/name)
   const validNamespacedSlug =
     /^[a-zA-Z0-9][a-zA-Z0-9._-]*\/[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
   const validSimpleName = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
   if (
-    msg.name.includes("..") ||
-    msg.name.includes("\\") ||
-    !(validSimpleName.test(msg.name) || validNamespacedSlug.test(msg.name))
+    skillId.includes("..") ||
+    skillId.includes("\\") ||
+    !(validSimpleName.test(skillId) || validNamespacedSlug.test(skillId))
   ) {
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "uninstall",
-      success: false,
-      error: "Invalid skill name",
-    });
-    return;
+    return { success: false, error: "Invalid skill name" };
   }
 
   try {
     // Use shared managed-store logic for simple managed skill IDs
-    const isManagedId = !validateManagedSkillId(msg.name);
+    const isManagedId = !validateManagedSkillId(skillId);
     if (isManagedId) {
-      const result = deleteManagedSkill(msg.name);
+      const result = deleteManagedSkill(skillId);
       if (!result.deleted) {
-        ctx.send(socket, {
-          type: "skills_operation_response",
-          operation: "uninstall",
+        return {
           success: false,
           error: result.error ?? "Failed to delete managed skill",
-        });
-        return;
+        };
       }
     } else {
       // Namespaced slug (org/name) — direct filesystem removal
-      const skillDir = join(getWorkspaceSkillsDir(), msg.name);
+      const skillDir = join(getWorkspaceSkillsDir(), skillId);
       if (!existsSync(skillDir)) {
-        ctx.send(socket, {
-          type: "skills_operation_response",
-          operation: "uninstall",
-          success: false,
-          error: "Skill not found",
-        });
-        return;
+        return { success: false, error: "Skill not found" };
       }
       rmSync(skillDir, { recursive: true });
       try {
-        removeSkillsIndexEntry(msg.name);
+        removeSkillsIndexEntry(skillId);
       } catch {
         /* best effort */
       }
@@ -471,288 +444,110 @@ export async function handleSkillsUninstall(
     const raw = loadRawConfig();
     const skills = raw.skills as Record<string, unknown> | undefined;
     const entries = skills?.entries as Record<string, unknown> | undefined;
-    if (entries?.[msg.name]) {
-      delete entries[msg.name];
-
-      ctx.setSuppressConfigReload(true);
-      try {
-        saveRawConfig(raw);
-      } catch (err) {
-        ctx.setSuppressConfigReload(false);
-        throw err;
-      }
-      invalidateConfigCache();
-
-      ctx.debounceTimers.schedule(
-        "__suppress_reset__",
-        () => {
-          ctx.setSuppressConfigReload(false);
-        },
-        CONFIG_RELOAD_DEBOUNCE_MS,
-      );
-
-      ctx.updateConfigFingerprint();
+    if (entries?.[skillId]) {
+      delete entries[skillId];
+      saveConfigWithSuppression(raw, ctx);
     }
 
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "uninstall",
-      success: true,
-    });
     ctx.broadcast({
       type: "skills_state_changed",
-      name: msg.name,
+      name: skillId,
       state: "uninstalled",
     });
+
+    return { success: true };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Failed to uninstall skill");
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "uninstall",
-      success: false,
-      error: message,
-    });
+    return { success: false, error: message };
   }
 }
 
-export async function handleSkillsUpdate(
-  msg: SkillsUpdateRequest,
-  socket: net.Socket,
-  ctx: HandlerContext,
-): Promise<void> {
+export async function updateSkill(
+  skillId: string,
+  _ctx: SkillOperationContext,
+): Promise<{ success: true } | { success: false; error: string }> {
   try {
-    const result = await clawhubUpdate(msg.name);
+    const result = await clawhubUpdate(skillId);
     if (!result.success) {
-      ctx.send(socket, {
-        type: "skills_operation_response",
-        operation: "update",
-        success: false,
-        error: result.error ?? "Unknown error",
-      });
-      return;
+      return { success: false, error: result.error ?? "Unknown error" };
     }
-
     // Reload skill catalog to pick up updated skill
     loadSkillCatalog();
-
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "update",
-      success: true,
-    });
+    return { success: true };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Failed to update skill");
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "update",
-      success: false,
-      error: message,
-    });
+    return { success: false, error: message };
   }
 }
 
-export async function handleSkillsCheckUpdates(
-  _msg: SkillsCheckUpdatesRequest,
-  socket: net.Socket,
-  ctx: HandlerContext,
-): Promise<void> {
+export async function checkSkillUpdates(
+  _ctx: SkillOperationContext,
+): Promise<{ success: true; data: unknown } | { success: false; error: string }> {
   try {
     const updates = await clawhubCheckUpdates();
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "check_updates",
-      success: true,
-      data: updates,
-    });
+    return { success: true, data: updates };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Failed to check for skill updates");
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "check_updates",
-      success: false,
-      error: message,
-    });
+    return { success: false, error: message };
   }
 }
 
-export async function handleSkillsSearch(
-  msg: SkillsSearchRequest,
-  socket: net.Socket,
-  ctx: HandlerContext,
-): Promise<void> {
+export async function searchSkills(
+  query: string,
+  _ctx: SkillOperationContext,
+): Promise<{ success: true; data: unknown } | { success: false; error: string }> {
   try {
-    const result = await clawhubSearch(msg.query);
-
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "search",
-      success: true,
-      data: result,
-    });
+    const result = await clawhubSearch(query);
+    return { success: true, data: result };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Failed to search skills");
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "search",
-      success: false,
-      error: message,
-    });
+    return { success: false, error: message };
   }
 }
 
-export async function handleSkillsInspect(
-  msg: SkillsInspectRequest,
-  socket: net.Socket,
-  ctx: HandlerContext,
-): Promise<void> {
+export async function inspectSkill(
+  skillId: string,
+  _ctx: SkillOperationContext,
+): Promise<{ slug: string; data?: ClawhubInspectResult; error?: string }> {
   try {
-    const result = await clawhubInspect(msg.slug);
-    ctx.send(socket, {
-      type: "skills_inspect_response",
-      slug: msg.slug,
+    const result = await clawhubInspect(skillId);
+    return {
+      slug: skillId,
       ...(result.data ? { data: result.data } : {}),
       ...(result.error ? { error: result.error } : {}),
-    });
+    };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Failed to inspect skill");
-    ctx.send(socket, {
-      type: "skills_inspect_response",
-      slug: msg.slug,
-      error: message,
-    });
-  }
-}
-
-export async function handleSkillDetail(
-  msg: SkillDetailRequest,
-  socket: net.Socket,
-  ctx: HandlerContext,
-): Promise<void> {
-  const result = loadSkillBySelector(msg.skillId);
-  if (result.skill) {
-    const icon = await ensureSkillIcon(
-      result.skill.directoryPath,
-      result.skill.name,
-      result.skill.description,
-    );
-    ctx.send(socket, {
-      type: "skill_detail_response",
-      skillId: result.skill.id,
-      body: result.skill.body,
-      ...(icon ? { icon } : {}),
-    });
-  } else {
-    ctx.send(socket, {
-      type: "skill_detail_response",
-      skillId: msg.skillId,
-      body: "",
-      error: result.error ?? "Skill not found",
-    });
+    return { slug: skillId, error: message };
   }
 }
 
-// ─── Frontmatter parsing ─────────────────────────────────────────────────────
-
-const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
-
-interface ParsedFrontmatter {
-  skillId?: string;
-  name?: string;
-  description?: string;
-  emoji?: string;
-  body: string;
+export interface DraftResult {
+  success: boolean;
+  draft?: {
+    skillId: string;
+    name: string;
+    description: string;
+    emoji?: string;
+    bodyMarkdown: string;
+  };
+  warnings?: string[];
+  error?: string;
 }
 
-function parseFrontmatter(sourceText: string): ParsedFrontmatter {
-  const match = FRONTMATTER_RE.exec(sourceText);
-  if (!match) return { body: sourceText };
-
-  const yamlBlock = match[1];
-  const body = match[2].replace(/\r\n/g, "\n");
-
-  const result: ParsedFrontmatter = { body };
-
-  // Simple YAML key-value extraction (handles quoted and unquoted values)
-  for (const line of yamlBlock.split(/\r?\n/)) {
-    const kvMatch = /^(\w[\w-]*):\s*(.+)$/.exec(line.trim());
-    if (!kvMatch) continue;
-    const key = kvMatch[1];
-    // Strip surrounding quotes
-    let value = kvMatch[2].trim();
-    if (
-      (value.startsWith('"') && value.endsWith('"')) ||
-      (value.startsWith("'") && value.endsWith("'"))
-    ) {
-      value = value.slice(1, -1);
-    }
-    switch (key) {
-      case "skill-id":
-      case "skillId":
-      case "id":
-        result.skillId = value;
-        break;
-      case "name":
-        result.name = value;
-        break;
-      case "description":
-        result.description = value;
-        break;
-      case "emoji":
-        result.emoji = value;
-        break;
-    }
-  }
-
-  return result;
-}
-
-// ─── Slug normalization ──────────────────────────────────────────────────────
-
-function toSkillSlug(raw: string): string {
-  return raw
-    .toLowerCase()
-    .replace(/[^a-z0-9._-]+/g, "-") // replace non-valid chars with hyphens
-    .replace(/^[^a-z0-9]+/, "") // must start with alphanumeric
-    .replace(/-+/g, "-") // collapse multiple hyphens
-    .slice(0, 50)
-    .replace(/-$/, ""); // no trailing hyphen (after truncation)
-}
-
-// ─── Deterministic heuristic draft ───────────────────────────────────────────
-
-function heuristicDraft(body: string): {
-  skillId: string;
-  name: string;
-  description: string;
-  emoji: string;
-} {
-  const lines = body.split("\n").filter((l) => l.trim());
-  const firstLine = lines[0]?.trim() ?? "";
-  const name =
-    firstLine.replace(/^#+\s*/, "").slice(0, 100) || "Untitled Skill";
-  const skillId = toSkillSlug(name) || "untitled-skill";
-  const description = body.trim().slice(0, 200) || "No description provided";
-  return { skillId, name, description, emoji: "\u{1F4DD}" };
-}
-
-// ─── Draft handler ───────────────────────────────────────────────────────────
-
-const LLM_DRAFT_TIMEOUT_MS = 15_000;
-
-export async function handleSkillsDraft(
-  msg: SkillsDraftRequest,
-  socket: net.Socket,
-  ctx: HandlerContext,
-): Promise<void> {
+export async function draftSkill(
+  params: { sourceText: string },
+  _ctx: SkillOperationContext,
+): Promise<DraftResult> {
   try {
     const warnings: string[] = [];
-    const parsed = parseFrontmatter(msg.sourceText);
-    const body = parsed.body.trim() || msg.sourceText.trim();
+    const parsed = parseFrontmatter(params.sourceText);
+    const body = parsed.body.trim() || params.sourceText.trim();
 
     let { skillId, name, description, emoji } = parsed;
 
@@ -870,8 +665,7 @@ export async function handleSkillsDraft(
       );
     }
 
-    ctx.send(socket, {
-      type: "skills_draft_response",
+    return {
       success: true,
       draft: {
         skillId: skillId!,
@@ -881,102 +675,257 @@ export async function handleSkillsDraft(
         bodyMarkdown: body,
       },
       ...(warnings.length > 0 ? { warnings } : {}),
-    });
+    };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Failed to generate skill draft");
-    ctx.send(socket, {
-      type: "skills_draft_response",
-      success: false,
-      error: message,
-    });
+    return { success: false, error: message };
   }
 }
 
-// ─── Create handler ──────────────────────────────────────────────────────────
+export interface CreateSkillParams {
+  skillId: string;
+  name: string;
+  description: string;
+  emoji?: string;
+  bodyMarkdown: string;
+  userInvocable?: boolean;
+  disableModelInvocation?: boolean;
+  overwrite?: boolean;
+}
 
-export async function handleSkillsCreate(
-  msg: SkillsCreateRequest,
-  socket: net.Socket,
-  ctx: HandlerContext,
-): Promise<void> {
+export async function createSkill(
+  params: CreateSkillParams,
+  ctx: SkillOperationContext,
+): Promise<{ success: true } | { success: false; error: string }> {
   try {
     const result = createManagedSkill({
-      id: msg.skillId,
-      name: msg.name,
-      description: msg.description,
-      emoji: msg.emoji,
-      bodyMarkdown: msg.bodyMarkdown,
-      userInvocable: msg.userInvocable,
-      disableModelInvocation: msg.disableModelInvocation,
-      overwrite: msg.overwrite,
+      id: params.skillId,
+      name: params.name,
+      description: params.description,
+      emoji: params.emoji,
+      bodyMarkdown: params.bodyMarkdown,
+      userInvocable: params.userInvocable,
+      disableModelInvocation: params.disableModelInvocation,
+      overwrite: params.overwrite,
     });
 
     if (!result.created) {
-      ctx.send(socket, {
-        type: "skills_operation_response",
-        operation: "create",
+      return {
         success: false,
         error: result.error ?? "Failed to create managed skill",
-      });
-      return;
+      };
     }
 
     // Auto-enable the newly created skill
-    let autoEnabled = false;
     try {
       const raw = loadRawConfig();
-      ensureSkillEntry(raw, msg.skillId).enabled = true;
-      ctx.setSuppressConfigReload(true);
-      try {
-        saveRawConfig(raw);
-      } catch (err) {
-        ctx.setSuppressConfigReload(false);
-        throw err;
-      }
-      invalidateConfigCache();
-      ctx.debounceTimers.schedule(
-        "__suppress_reset__",
-        () => {
-          ctx.setSuppressConfigReload(false);
-        },
-        CONFIG_RELOAD_DEBOUNCE_MS,
-      );
-      ctx.updateConfigFingerprint();
-      autoEnabled = true;
+      ensureSkillEntry(raw, params.skillId).enabled = true;
+      saveConfigWithSuppression(raw, ctx);
+      ctx.broadcast({
+        type: "skills_state_changed",
+        name: params.skillId,
+        state: "enabled",
+      });
     } catch (err) {
       log.warn(
-        { err, skillId: msg.skillId },
+        { err, skillId: params.skillId },
         "Failed to auto-enable created skill",
       );
     }
 
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "create",
-      success: true,
-    });
-    if (autoEnabled) {
-      ctx.broadcast({
-        type: "skills_state_changed",
-        name: msg.skillId,
-        state: "enabled",
-      });
-    }
+    return { success: true };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Failed to create skill");
-    ctx.send(socket, {
-      type: "skills_operation_response",
-      operation: "create",
-      success: false,
-      error: message,
+    return { success: false, error: message };
+  }
+}
+
+// ─── IPC handlers (thin wrappers) ───────────────────────────────────────────
+
+export function handleSkillsList(
+  ctx: HandlerContext,
+): void {
+  const skills = listSkills(ctx);
+  ctx.send({ type: "skills_list_response", skills });
+}
+
+export function handleSkillsEnable(
+  msg: SkillsEnableRequest,
+  ctx: HandlerContext,
+): void {
+  const result = enableSkill(msg.name, ctx);
+  ctx.send({
+    type: "skills_operation_response",
+    operation: "enable",
+    ...result,
+  });
+}
+
+export function handleSkillsDisable(
+  msg: SkillsDisableRequest,
+  ctx: HandlerContext,
+): void {
+  const result = disableSkill(msg.name, ctx);
+  ctx.send({
+    type: "skills_operation_response",
+    operation: "disable",
+    ...result,
+  });
+}
+
+export function handleSkillsConfigure(
+  msg: SkillsConfigureRequest,
+  ctx: HandlerContext,
+): void {
+  const result = configureSkill(
+    msg.name,
+    { env: msg.env, apiKey: msg.apiKey, config: msg.config },
+    ctx,
+  );
+  ctx.send({
+    type: "skills_operation_response",
+    operation: "configure",
+    ...result,
+  });
+}
+
+export async function handleSkillsInstall(
+  msg: SkillsInstallRequest,
+  ctx: HandlerContext,
+): Promise<void> {
+  const result = await installSkill(
+    { slug: msg.slug, version: msg.version },
+    ctx,
+  );
+  ctx.send({
+    type: "skills_operation_response",
+    operation: "install",
+    ...result,
+  });
+}
+
+export async function handleSkillsUninstall(
+  msg: SkillsUninstallRequest,
+  ctx: HandlerContext,
+): Promise<void> {
+  const result = await uninstallSkill(msg.name, ctx);
+  ctx.send({
+    type: "skills_operation_response",
+    operation: "uninstall",
+    ...result,
+  });
+}
+
+export async function handleSkillsUpdate(
+  msg: SkillsUpdateRequest,
+  ctx: HandlerContext,
+): Promise<void> {
+  const result = await updateSkill(msg.name, ctx);
+  ctx.send({
+    type: "skills_operation_response",
+    operation: "update",
+    ...result,
+  });
+}
+
+export async function handleSkillsCheckUpdates(
+  _msg: SkillsCheckUpdatesRequest,
+  ctx: HandlerContext,
+): Promise<void> {
+  const result = await checkSkillUpdates(ctx);
+  ctx.send({
+    type: "skills_operation_response",
+    operation: "check_updates",
+    ...result,
+  });
+}
+
+export async function handleSkillsSearch(
+  msg: SkillsSearchRequest,
+  ctx: HandlerContext,
+): Promise<void> {
+  const result = await searchSkills(msg.query, ctx);
+  ctx.send({
+    type: "skills_operation_response",
+    operation: "search",
+    ...result,
+  });
+}
+
+export async function handleSkillsInspect(
+  msg: SkillsInspectRequest,
+  ctx: HandlerContext,
+): Promise<void> {
+  const result = await inspectSkill(msg.slug, ctx);
+  ctx.send({
+    type: "skills_inspect_response",
+    ...result,
+  });
+}
+
+export async function handleSkillDetail(
+  msg: SkillDetailRequest,
+  ctx: HandlerContext,
+): Promise<void> {
+  const result = loadSkillBySelector(msg.skillId);
+  if (result.skill) {
+    const icon = await ensureSkillIcon(
+      result.skill.directoryPath,
+      result.skill.displayName,
+      result.skill.description,
+    );
+    ctx.send({
+      type: "skill_detail_response",
+      skillId: result.skill.id,
+      body: result.skill.body,
+      ...(icon ? { icon } : {}),
+    });
+  } else {
+    ctx.send({
+      type: "skill_detail_response",
+      skillId: msg.skillId,
+      body: "",
+      error: result.error ?? "Skill not found",
     });
   }
 }
 
+export async function handleSkillsDraft(
+  msg: SkillsDraftRequest,
+  ctx: HandlerContext,
+): Promise<void> {
+  const result = await draftSkill({ sourceText: msg.sourceText }, ctx);
+  ctx.send({ type: "skills_draft_response", ...result });
+}
+
+export async function handleSkillsCreate(
+  msg: SkillsCreateRequest,
+  ctx: HandlerContext,
+): Promise<void> {
+  const result = await createSkill(
+    {
+      skillId: msg.skillId,
+      name: msg.name,
+      description: msg.description,
+      emoji: msg.emoji,
+      bodyMarkdown: msg.bodyMarkdown,
+      userInvocable: msg.userInvocable,
+      disableModelInvocation: msg.disableModelInvocation,
+      overwrite: msg.overwrite,
+    },
+    ctx,
+  );
+  ctx.send({
+    type: "skills_operation_response",
+    operation: "create",
+    ...result,
+  });
+}
+
 export const skillHandlers = defineHandlers({
-  skills_list: (_msg, socket, ctx) => handleSkillsList(socket, ctx),
+  skills_list: (_msg, ctx) => handleSkillsList(ctx),
   skill_detail: handleSkillDetail,
   skills_enable: handleSkillsEnable,
   skills_disable: handleSkillsDisable,