@skilltap/core 0.3.9 → 0.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilltap/core",
-  "version": "0.3.9",
+  "version": "0.4.4",
   "description": "Core library for skilltap — agent skill management",
   "type": "module",
   "license": "MIT",

package/src/debug.test.ts

@@ -0,0 +1,102 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { debug, flushDebug, resetDebug } from "./debug";
+
+describe("debug", () => {
+  let tmpDir: string;
+  const origDebug = process.env.SKILLTAP_DEBUG;
+  const origXdg = process.env.XDG_CONFIG_HOME;
+
+  afterEach(async () => {
+    resetDebug();
+    if (origDebug === undefined) delete process.env.SKILLTAP_DEBUG;
+    else process.env.SKILLTAP_DEBUG = origDebug;
+    if (origXdg === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = origXdg;
+    if (tmpDir) await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  test("no-op when SKILLTAP_DEBUG is not set", async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "debug-test-"));
+    process.env.XDG_CONFIG_HOME = tmpDir;
+    delete process.env.SKILLTAP_DEBUG;
+
+    debug("should not write");
+    await flushDebug();
+
+    const logPath = join(tmpDir, "skilltap", "debug.log");
+    const exists = await Bun.file(logPath).exists();
+    expect(exists).toBe(false);
+  });
+
+  test("writes to debug.log when SKILLTAP_DEBUG=1", async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "debug-test-"));
+    process.env.XDG_CONFIG_HOME = tmpDir;
+    process.env.SKILLTAP_DEBUG = "1";
+
+    debug("hello world");
+    await flushDebug();
+
+    const logPath = join(tmpDir, "skilltap", "debug.log");
+    const content = await readFile(logPath, "utf-8");
+    expect(content).toContain("hello world");
+    expect(content).toMatch(/^\[\d{4}-\d{2}-\d{2}T/);
+  });
+
+  test("includes context as JSON", async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "debug-test-"));
+    process.env.XDG_CONFIG_HOME = tmpDir;
+    process.env.SKILLTAP_DEBUG = "1";
+
+    debug("test op", { exitCode: 18, stderr: "denied" });
+    await flushDebug();
+
+    const logPath = join(tmpDir, "skilltap", "debug.log");
+    const content = await readFile(logPath, "utf-8");
+    expect(content).toContain('"exitCode":18');
+    expect(content).toContain('"stderr":"denied"');
+  });
+
+  test("rotates when log exceeds 1 MB", async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "debug-test-"));
+    process.env.XDG_CONFIG_HOME = tmpDir;
+    process.env.SKILLTAP_DEBUG = "1";
+
+    const logDir = join(tmpDir, "skilltap");
+    const logPath = join(logDir, "debug.log");
+    const { mkdir } = await import("node:fs/promises");
+    await mkdir(logDir, { recursive: true });
+
+    // Write >1 MB of content
+    const bigContent = "X".repeat(1_200_000);
+    await writeFile(logPath, bigContent);
+
+    debug("after rotation");
+    await flushDebug();
+
+    const content = await readFile(logPath, "utf-8");
+    // Should be truncated to ~500KB + new line
+    expect(content.length).toBeLessThan(600_000);
+    expect(content).toContain("after rotation");
+  });
+
+  test("multiple writes are serialized", async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "debug-test-"));
+    process.env.XDG_CONFIG_HOME = tmpDir;
+    process.env.SKILLTAP_DEBUG = "1";
+
+    debug("line 1");
+    debug("line 2");
+    debug("line 3");
+    await flushDebug();
+
+    const logPath = join(tmpDir, "skilltap", "debug.log");
+    const content = await readFile(logPath, "utf-8");
+    const lines = content.trim().split("\n");
+    expect(lines).toHaveLength(3);
+    expect(lines[0]).toContain("line 1");
+    expect(lines[2]).toContain("line 3");
+  });
+});

package/src/debug.ts

@@ -0,0 +1,67 @@
+import { appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getConfigDir } from "./config";
+
+const MAX_LOG_SIZE = 1_048_576; // 1 MB
+const KEEP_BYTES = 524_288; // 500 KB
+
+let enabled: boolean | null = null;
+let logPath: string | null = null;
+let writeChain: Promise<void> = Promise.resolve();
+let rotationDone = false;
+
+function getLogPath(): string {
+  if (!logPath) logPath = join(getConfigDir(), "debug.log");
+  return logPath;
+}
+
+async function rotateIfNeeded(): Promise<void> {
+  if (rotationDone) return;
+  rotationDone = true;
+  try {
+    const path = getLogPath();
+    const s = await stat(path).catch(() => null);
+    if (s && s.size > MAX_LOG_SIZE) {
+      const content = await readFile(path);
+      await writeFile(path, content.slice(content.length - KEEP_BYTES));
+    }
+  } catch {
+    /* ignore rotation errors */
+  }
+}
+
+/** Write a timestamped debug message to the log file. No-op when SKILLTAP_DEBUG is not "1". */
+export function debug(msg: string, context?: Record<string, unknown>): void {
+  if (enabled === null) enabled = process.env.SKILLTAP_DEBUG === "1";
+  if (!enabled) return;
+
+  const ts = new Date().toISOString();
+  const ctx = context ? ` ${JSON.stringify(context)}` : "";
+  const line = `[${ts}] ${msg}${ctx}\n`;
+
+  writeChain = writeChain.then(async () => {
+    await rotateIfNeeded();
+    const path = getLogPath();
+    await mkdir(join(path, ".."), { recursive: true }).catch(() => {});
+    await appendFile(path, line).catch(() => {});
+  });
+}
+
+/**
+ * Flush pending debug writes. Only needed in tests — production code uses fire-and-forget.
+ * @internal
+ */
+export function flushDebug(): Promise<void> {
+  return writeChain;
+}
+
+/**
+ * Reset internal state. Only for tests.
+ * @internal
+ */
+export function resetDebug(): void {
+  enabled = null;
+  logPath = null;
+  writeChain = Promise.resolve();
+  rotationDone = false;
+}

package/src/git.ts

@@ -1,4 +1,6 @@
 import { $ } from "bun";
+import { debug } from "./debug";
+import { extractStderr } from "./shell";
 import type { Result } from "./types";
 import { err, GitError, ok } from "./types";
 
@@ -13,15 +15,6 @@ export type CloneOptions = {
   depth?: number;
 };
 
-function extractStderr(e: unknown): string {
-  if (e instanceof Error && "stderr" in e) {
-    const raw = (e as { stderr: unknown }).stderr;
-    if (raw instanceof Uint8Array) return new TextDecoder().decode(raw).trim();
-    return String(raw).trim();
-  }
-  return String(e);
-}
-
 async function wrapGit<T>(
   fn: () => Promise<T>,
   msg: string,
@@ -30,8 +23,10 @@ async function wrapGit<T>(
   try {
     return ok(await fn());
   } catch (e) {
+    const stderr = extractStderr(e);
+    debug(msg, { stderr });
     return err(
-      new GitError(`${msg}: ${extractStderr(e)}`, hint ? { hint } : undefined),
+      new GitError(`${msg}: ${stderr}`, hint ? { hint } : undefined),
     );
   }
 }
@@ -49,6 +44,7 @@ export async function clone(
   dest: string,
   opts?: CloneOptions,
 ): Promise<Result<void, GitError>> {
+  debug("git clone", { url, dest, branch: opts?.branch });
   const flags: string[] = ["--depth", String(opts?.depth ?? 1)];
   if (opts?.branch) flags.push("--branch", opts.branch);
   try {

package/src/index.ts

@@ -1,5 +1,6 @@
 import { version } from "../package.json";
 export const VERSION: string = version;
+export * from "./debug";
 export * from "./doctor";
 
 export * from "./adapters";
@@ -26,4 +27,5 @@ export * from "./trust";
 export * from "./policy";
 export * from "./validate";
 export * from "./self-update";
+export * from "./shell";
 export * from "./types";

package/src/install.ts

@@ -2,6 +2,7 @@ import { mkdir } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 import { $ } from "bun";
 import { resolveSource } from "./adapters";
+import { debug } from "./debug";
 import type { AgentAdapter } from "./agents/types";
 import { loadInstalled, saveInstalled } from "./config";
 import { makeTmpDir, removeTmpDir } from "./fs";
@@ -16,6 +17,7 @@ import type { StaticWarning } from "./security";
 import { scanStatic } from "./security";
 import type { SemanticWarning } from "./security/semantic";
 import { scanSemantic } from "./security/semantic";
+import { wrapShell } from "./shell";
 import { createAgentSymlinks } from "./symlink";
 import type { TapEntry } from "./taps";
 import { loadTaps } from "./taps";
@@ -218,7 +220,15 @@ async function buildPlacements(params: {
     // git multi-skill: move clone to cache first, then copy selected skills
     const cacheRoot = skillCacheDir(resolvedUrl);
     await mkdir(dirname(cacheRoot), { recursive: true });
-    await $`mv ${contentDir} ${cacheRoot}`.quiet();
+    const mvResult = await wrapShell(
+      () =>
+        $`cp -a ${contentDir} ${cacheRoot} && rm -rf ${contentDir}`
+          .quiet()
+          .then(() => undefined),
+      "Failed to move clone to cache",
+      "Check disk space and permissions.",
+    );
+    if (!mvResult.ok) throw mvResult.error;
     for (const skill of selected) {
       const skillSrcInCache = skill.path.replace(contentDir, cacheRoot);
       placements.push({
@@ -251,11 +261,18 @@ async function executePlacements(params: {
 
   for (const { skill, srcPath, relPath, destDir, useMove } of placements) {
     await mkdir(dirname(destDir), { recursive: true });
-    if (useMove) {
-      await $`mv ${srcPath} ${destDir}`.quiet();
-    } else {
-      await $`cp -r ${srcPath} ${destDir}`.quiet();
-    }
+    const op = useMove ? "move" : "copy";
+    const shellResult = await wrapShell(
+      () =>
+        useMove
+          ? $`cp -a ${srcPath} ${destDir} && rm -rf ${srcPath}`
+              .quiet()
+              .then(() => undefined)
+          : $`cp -r ${srcPath} ${destDir}`.quiet().then(() => undefined),
+      `Failed to ${op} skill '${skill.name}' to ${destDir}`,
+      "Check disk space and permissions.",
+    );
+    if (!shellResult.ok) throw shellResult.error;
     await createAgentSymlinks(skill.name, destDir, also, options.scope, options.projectRoot);
     records.push(
       makeRecord(skill, resolved, sha, relPath, options, also, now, effectiveTap, finalRef, trust, sourceKey),
@@ -342,6 +359,7 @@ export async function installSkill(
   source: string,
   options: InstallOptions,
 ): Promise<Result<InstallResult, UserError | GitError | ScanError | NetworkError>> {
+  debug("installSkill", { source, scope: options.scope });
   const also = options.also ?? [];
   const allWarnings: StaticWarning[] = [];
   const allSemanticWarnings: SemanticWarning[] = [];
@@ -409,6 +427,8 @@ export async function installSkill(
       sha = shaResult.value;
     }
 
+    debug("content fetched", { contentDir, sha, adapter: resolved.adapter });
+
     // 5. Scan for skills
     const scanned = await scan(contentDir, { onDeepScan: options.onDeepScan });
     if (scanned.length === 0) {
@@ -539,6 +559,8 @@ export async function installSkill(
       effectiveTap, finalRef, trust, sourceKey,
     });
 
+    debug("placements complete", { installed: newRecords.map((r) => r.name) });
+
     // 10. Save installed.json
     installed.skills.push(...newRecords);
     const saveResult = await saveInstalled(installed);

package/src/npm-registry.ts

@@ -1,6 +1,8 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { $ } from "bun";
+import { debug } from "./debug";
+import { extractStderr } from "./shell";
 import type { Result } from "./types";
 import { err, NetworkError, ok, UserError } from "./types";
 
@@ -156,6 +158,7 @@ export async function downloadAndExtract(
   dest: string,
   integrity?: string,
 ): Promise<Result<string, NetworkError>> {
+  debug("downloadAndExtract", { tarballUrl, dest });
   let response: Response;
   try {
     response = await fetch(tarballUrl);
@@ -184,6 +187,7 @@ export async function downloadAndExtract(
     const digest = hasher.digest("base64");
     const expected = integrity.slice("sha512-".length);
     if (digest !== expected) {
+      debug("integrity check failed", { expected, got: digest });
       return err(
         new NetworkError(
           "Tarball integrity check failed. The download may be corrupted.",
@@ -199,8 +203,10 @@ export async function downloadAndExtract(
   // Extract (npm tarballs always extract to a `package/` subdirectory)
   try {
     await $`tar -xzf ${tarPath} -C ${dest}`.quiet();
-  } catch {
-    return err(new NetworkError("Failed to extract npm package tarball."));
+  } catch (e) {
+    const detail = extractStderr(e);
+    debug("tar extraction failed", { tarballUrl, error: detail });
+    return err(new NetworkError(`Failed to extract npm package tarball: ${detail}`));
   }
 
   return ok(join(dest, "package"));

package/src/remove.ts

@@ -1,6 +1,8 @@
 import { $ } from "bun";
 import { loadInstalled, saveInstalled } from "./config";
+import { debug } from "./debug";
 import { skillCacheDir, skillInstallDir } from "./paths";
+import { wrapShell } from "./shell";
 import { removeAgentSymlinks } from "./symlink";
 import type { Result } from "./types";
 import { err, ok, UserError } from "./types";
@@ -14,6 +16,7 @@ export async function removeSkill(
   name: string,
   options: RemoveOptions = {},
 ): Promise<Result<void, UserError>> {
+  debug("removeSkill", { name, scope: options.scope });
   const installedResult = await loadInstalled();
   if (!installedResult.ok) return installedResult;
   const installed = installedResult.value;
@@ -51,7 +54,12 @@ export async function removeSkill(
           record.scope === "linked" ? "global" : record.scope,
           options.projectRoot,
         );
-  await $`rm -rf ${installPath}`.quiet();
+  const rmResult = await wrapShell(
+    () => $`rm -rf ${installPath}`.quiet().then(() => undefined),
+    `Failed to remove skill directory '${name}'`,
+    "Check file permissions.",
+  );
+  if (!rmResult.ok) return rmResult;
 
   // Remove cache if this was the last skill from the repo
   if (record.path !== null && record.repo) {
@@ -60,7 +68,13 @@ export async function removeSkill(
     );
     if (remainingFromSameRepo.length === 0) {
       const cacheRoot = skillCacheDir(record.repo);
-      await $`rm -rf ${cacheRoot}`.quiet();
+      const cacheResult = await wrapShell(
+        () => $`rm -rf ${cacheRoot}`.quiet().then(() => undefined),
+        `Failed to remove cache directory for '${name}'`,
+      );
+      if (!cacheResult.ok) {
+        debug("cache cleanup failed", { name, cacheRoot, error: cacheResult.error.message });
+      }
     }
   }
 

package/src/self-update.ts

@@ -1,5 +1,6 @@
 import { basename, join } from "node:path";
 import { getConfigDir } from "./config";
+import { extractStderr } from "./shell";
 import { err, NetworkError, ok, type Result, UserError } from "./types";
 
 export type UpdateType = "patch" | "minor" | "major";
@@ -163,13 +164,13 @@ export async function downloadAndInstall(
     const buffer = await response.arrayBuffer();
     await Bun.write(tmpPath, buffer);
     await Bun.$`chmod +x ${tmpPath}`.quiet();
-    await Bun.$`mv ${tmpPath} ${execPath}`.quiet();
+    await Bun.$`cp -a ${tmpPath} ${execPath} && rm -f ${tmpPath}`.quiet();
   } catch (e) {
     // Clean up temp file if possible
     Bun.$`rm -f ${tmpPath}`.quiet();
     return err(
       new UserError(
-        `Failed to replace binary: ${e}`,
+        `Failed to replace binary: ${extractStderr(e)}`,
         "Try running with sudo, or install via npm: npm install -g skilltap",
       ),
     );

package/src/shell.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import { extractExitCode, extractStderr, wrapShell } from "./shell";
+
+describe("extractStderr", () => {
+  test("extracts Uint8Array stderr", () => {
+    const e = Object.assign(new Error("fail"), {
+      stderr: new TextEncoder().encode("permission denied"),
+    });
+    expect(extractStderr(e)).toBe("permission denied");
+  });
+
+  test("extracts string stderr", () => {
+    const e = Object.assign(new Error("fail"), { stderr: "not found" });
+    expect(extractStderr(e)).toBe("not found");
+  });
+
+  test("falls back to String(e) for plain errors", () => {
+    const e = new Error("something broke");
+    expect(extractStderr(e)).toBe("Error: something broke");
+  });
+
+  test("handles non-Error values", () => {
+    expect(extractStderr("raw string")).toBe("raw string");
+    expect(extractStderr(42)).toBe("42");
+  });
+
+  test("trims whitespace from stderr", () => {
+    const e = Object.assign(new Error("fail"), { stderr: "  spaced  \n" });
+    expect(extractStderr(e)).toBe("spaced");
+  });
+});
+
+describe("extractExitCode", () => {
+  test("extracts exitCode from ShellError-like object", () => {
+    const e = Object.assign(new Error("fail"), { exitCode: 18 });
+    expect(extractExitCode(e)).toBe(18);
+  });
+
+  test("returns undefined for plain errors", () => {
+    expect(extractExitCode(new Error("nope"))).toBeUndefined();
+  });
+
+  test("returns undefined for non-Error values", () => {
+    expect(extractExitCode("string")).toBeUndefined();
+  });
+});
+
+describe("wrapShell", () => {
+  test("returns ok on success", async () => {
+    const result = await wrapShell(() => Promise.resolve(42), "test op");
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toBe(42);
+  });
+
+  test("returns err(UserError) with stderr on failure", async () => {
+    const shellError = Object.assign(new Error("Failed with exit code 1"), {
+      stderr: new TextEncoder().encode("No such file or directory"),
+      exitCode: 1,
+    });
+    const result = await wrapShell(
+      () => Promise.reject(shellError),
+      "Failed to copy skill",
+      "Check permissions.",
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toContain("Failed to copy skill");
+      expect(result.error.message).toContain("No such file or directory");
+      expect(result.error.hint).toBe("Check permissions.");
+    }
+  });
+
+  test("falls back to exit code when no stderr", async () => {
+    const shellError = Object.assign(new Error("Failed with exit code 18"), {
+      stderr: new Uint8Array(0),
+      exitCode: 18,
+    });
+    const result = await wrapShell(
+      () => Promise.reject(shellError),
+      "mv failed",
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toContain("exit code 18");
+    }
+  });
+});

package/src/shell.ts

@@ -0,0 +1,41 @@
+import { debug } from "./debug";
+import type { Result } from "./types";
+import { err, ok, UserError } from "./types";
+
+/** Extract stderr from a Bun ShellError. */
+export function extractStderr(e: unknown): string {
+  if (e instanceof Error && "stderr" in e) {
+    const raw = (e as { stderr: unknown }).stderr;
+    if (raw instanceof Uint8Array) return new TextDecoder().decode(raw).trim();
+    return String(raw).trim();
+  }
+  return String(e);
+}
+
+/** Extract exit code from a Bun ShellError. */
+export function extractExitCode(e: unknown): number | undefined {
+  if (e instanceof Error && "exitCode" in e) {
+    return (e as { exitCode: number }).exitCode;
+  }
+  return undefined;
+}
+
+/**
+ * Wrap a shell command with stderr extraction and debug logging.
+ * Returns Result<T, UserError> with a descriptive message on failure.
+ */
+export async function wrapShell<T>(
+  fn: () => Promise<T>,
+  msg: string,
+  hint?: string,
+): Promise<Result<T, UserError>> {
+  try {
+    return ok(await fn());
+  } catch (e) {
+    const stderr = extractStderr(e);
+    const exitCode = extractExitCode(e);
+    debug(msg, { stderr, exitCode });
+    const detail = stderr || `exit code ${exitCode ?? "unknown"}`;
+    return err(new UserError(`${msg}: ${detail}`, hint));
+  }
+}

package/src/taps.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { $ } from "bun";
 import { z } from "zod/v4";
 import { getConfigDir, loadConfig, saveConfig } from "./config";
+import { extractStderr } from "./shell";
 import { checkGitInstalled, clone, pull } from "./git";
 import type { RegistrySource } from "./registry";
 import { detectTapType, fetchSkillList } from "./registry";
@@ -292,9 +293,7 @@ export async function initTap(name: string): Promise<Result<void, UserError>> {
     return ok(undefined);
   } catch (e) {
     return err(
-      new UserError(
-        `Failed to initialize tap: ${e instanceof Error ? e.message : String(e)}`,
-      ),
+      new UserError(`Failed to initialize tap: ${extractStderr(e)}`),
     );
   }
 }

package/src/update.ts

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { $ } from "bun";
 import type { AgentAdapter } from "./agents/types";
 import { loadInstalled, saveInstalled } from "./config";
+import { debug } from "./debug";
 import { makeTmpDir, removeTmpDir } from "./fs";
 import type { DiffStat } from "./git";
 import { diff, diffStat, fetch, pull, revParse } from "./git";
@@ -18,6 +19,7 @@ import type { StaticWarning } from "./security";
 import { scanDiff, scanStatic } from "./security";
 import type { SemanticWarning } from "./security/semantic";
 import { scanSemantic } from "./security/semantic";
+import { wrapShell } from "./shell";
 import { createAgentSymlinks, removeAgentSymlinks } from "./symlink";
 import { parseGitHubRepo, resolveTrust } from "./trust";
 import type { Result } from "./types";
@@ -94,17 +96,27 @@ async function recopyMultiSkill(
   workDir: string,
   record: InstalledSkill,
   projectRoot?: string,
-): Promise<void> {
-  if (record.path === null) return;
+): Promise<Result<void, UserError>> {
+  if (record.path === null) return ok(undefined);
   const skillSrc = join(workDir, record.path);
   const destDir = skillInstallDir(
     record.name,
     record.scope as "global" | "project",
     projectRoot,
   );
-  await $`rm -rf ${destDir}`.quiet();
+  const rmResult = await wrapShell(
+    () => $`rm -rf ${destDir}`.quiet().then(() => undefined),
+    `Failed to remove old skill directory '${record.name}'`,
+  );
+  if (!rmResult.ok) return rmResult;
+
   await mkdir(dirname(destDir), { recursive: true });
-  await $`cp -r ${skillSrc} ${destDir}`.quiet();
+
+  return wrapShell(
+    () => $`cp -r ${skillSrc} ${destDir}`.quiet().then(() => undefined),
+    `Failed to copy updated skill '${record.name}'`,
+    "Check disk space and permissions.",
+  );
 }
 
 /** Remove and re-create agent symlinks for a skill (idempotent). */
@@ -225,9 +237,20 @@ async function updateNpmSkill(
       record.scope as "global" | "project",
       options.projectRoot,
     );
-    await $`rm -rf ${installDir}`.quiet();
+    const rmResult = await wrapShell(
+      () => $`rm -rf ${installDir}`.quiet().then(() => undefined),
+      `Failed to remove old skill directory '${record.name}'`,
+    );
+    if (!rmResult.ok) return rmResult;
+
     await mkdir(dirname(installDir), { recursive: true });
-    await $`cp -r ${newSkillDir} ${installDir}`.quiet();
+
+    const cpResult = await wrapShell(
+      () => $`cp -r ${newSkillDir} ${installDir}`.quiet().then(() => undefined),
+      `Failed to install updated skill '${record.name}'`,
+      "Check disk space and permissions.",
+    );
+    if (!cpResult.ok) return cpResult;
 
     // Semantic scan on updated content
     if (await runUpdateSemanticScan(installDir, record.name, options)) {
@@ -342,7 +365,10 @@ async function updateGitSkill(
   const pullResult = await pull(workDir);
   if (!pullResult.ok) return pullResult;
 
-  if (isMulti) await recopyMultiSkill(workDir, record, options.projectRoot);
+  if (isMulti) {
+    const recopyResult = await recopyMultiSkill(workDir, record, options.projectRoot);
+    if (!recopyResult.ok) return recopyResult;
+  }
 
   const installDir = skillInstallDir(
     record.name,
@@ -387,6 +413,7 @@ async function updateGitSkill(
 export async function updateSkill(
   options: UpdateOptions = {},
 ): Promise<Result<UpdateResult, UserError | GitError | ScanError | NetworkError>> {
+  debug("updateSkill", { name: options.name ?? "all" });
   const installedResult = await loadInstalled();
   if (!installedResult.ok) return installedResult;
   const installed = installedResult.value;