@skilltap/core 0.5.0 → 0.5.3

package/package.json

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

package/src/config.ts

@@ -92,7 +92,11 @@ enabled = ["skills.sh"]
 # name = "my-org"
 # url = "https://skills.example.com"
 
-# Tap definitions (repeatable section)
+# Built-in tap: the official skilltap-skills collection.
+# Set to false to opt out of the built-in tap entirely.
+builtin_tap = true
+
+# Additional tap definitions (repeatable section)
 # [[taps]]
 # name = "home"
 # url = "https://gitea.example.com/nathan/my-skills-tap"
@@ -160,9 +164,14 @@ export async function saveConfig(config: Config): Promise<Result<void>> {
 
 const _DEFAULT_INSTALLED: InstalledJson = { version: 1, skills: [] };
 
-export async function loadInstalled(): Promise<Result<InstalledJson>> {
-  const dir = getConfigDir();
-  const file = join(dir, "installed.json");
+function getInstalledPath(projectRoot?: string): string {
+  return projectRoot
+    ? join(projectRoot, ".agents", "installed.json")
+    : join(getConfigDir(), "installed.json");
+}
+
+export async function loadInstalled(projectRoot?: string): Promise<Result<InstalledJson>> {
+  const file = getInstalledPath(projectRoot);
 
   const f = Bun.file(file);
   const exists = await f.exists();
@@ -190,12 +199,20 @@ export async function loadInstalled(): Promise<Result<InstalledJson>> {
 
 export async function saveInstalled(
   installed: InstalledJson,
+  projectRoot?: string,
 ): Promise<Result<void>> {
-  const dir = getConfigDir();
-  const file = join(dir, "installed.json");
+  const file = getInstalledPath(projectRoot);
 
-  const dirsResult = await ensureDirs();
-  if (!dirsResult.ok) return dirsResult;
+  if (projectRoot) {
+    try {
+      await mkdir(join(projectRoot, ".agents"), { recursive: true });
+    } catch (e) {
+      return err(new UserError(`Failed to create .agents directory: ${e}`));
+    }
+  } else {
+    const dirsResult = await ensureDirs();
+    if (!dirsResult.ok) return dirsResult;
+  }
 
   try {
     await Bun.write(file, JSON.stringify(installed, null, 2));

package/src/doctor.ts

@@ -346,7 +346,6 @@ async function checkSkills(installed: InstalledJson): Promise<DoctorCheck> {
   const trackedNames = new Set<string>();
 
   for (const skill of installed.skills) {
-    if (skill.scope === "project") continue;
     trackedNames.add(skill.name);
 
     if (skill.scope === "linked") {
@@ -407,7 +406,7 @@ async function checkSkills(installed: InstalledJson): Promise<DoctorCheck> {
     }
   }
 
-  const total = installed.skills.filter((s) => s.scope !== "project").length;
+  const total = installed.skills.length;
   const missing = issues.filter((i) => i.fixable).length;
   const onDisk = total - missing;
 
@@ -434,7 +433,7 @@ async function checkSymlinks(installed: InstalledJson): Promise<DoctorCheck> {
   let valid = 0;
 
   for (const skill of installed.skills) {
-    if (skill.scope === "project" || skill.also.length === 0) continue;
+    if (skill.also.length === 0) continue;
 
     for (const agent of skill.also) {
       const agentRelDir = AGENT_PATHS[agent];

package/src/frontmatter.test.ts

@@ -0,0 +1,85 @@
+import { describe, test, expect } from "bun:test";
+import { parseSkillFrontmatter } from "./frontmatter";
+
+describe("parseSkillFrontmatter", () => {
+  test("parses simple single-line values", () => {
+    const content = `---
+name: my-skill
+description: A short description
+license: MIT
+---
+`;
+    const result = parseSkillFrontmatter(content);
+    expect(result).toEqual({
+      name: "my-skill",
+      description: "A short description",
+      license: "MIT",
+    });
+  });
+
+  test("returns null when no frontmatter", () => {
+    expect(parseSkillFrontmatter("No frontmatter here")).toBeNull();
+  });
+
+  test("coerces boolean values", () => {
+    const result = parseSkillFrontmatter("---\nfoo: true\nbar: false\n---\n");
+    expect(result?.foo).toBe(true);
+    expect(result?.bar).toBe(false);
+  });
+
+  test("coerces numeric values", () => {
+    const result = parseSkillFrontmatter("---\ncount: 42\n---\n");
+    expect(result?.count).toBe(42);
+  });
+
+  test("parses folded block scalar (>)", () => {
+    const content = `---
+name: my-skill
+description: >
+  This is a long description
+  that spans multiple lines.
+license: MIT
+---
+`;
+    const result = parseSkillFrontmatter(content);
+    expect(result?.description).toBe("This is a long description that spans multiple lines.");
+    expect(result?.license).toBe("MIT");
+  });
+
+  test("parses literal block scalar (|)", () => {
+    const content = `---
+name: my-skill
+description: |
+  Line one.
+  Line two.
+---
+`;
+    const result = parseSkillFrontmatter(content);
+    expect(result?.description).toBe("Line one.\nLine two.");
+  });
+
+  test("folded block scalar with single line", () => {
+    const content = `---
+description: >
+  Single line text.
+---
+`;
+    const result = parseSkillFrontmatter(content);
+    expect(result?.description).toBe("Single line text.");
+  });
+
+  test("block scalar followed by another key", () => {
+    const content = `---
+name: my-skill
+description: >
+  Multi-line
+  description here.
+license: Apache-2.0
+---
+`;
+    const result = parseSkillFrontmatter(content);
+    expect(result?.description).toBe("Multi-line description here.");
+    expect(result?.license).toBe("Apache-2.0");
+    expect(result?.name).toBe("my-skill");
+  });
+});

package/src/frontmatter.ts

@@ -1,6 +1,7 @@
 /**
  * Parse YAML-style frontmatter between leading --- delimiters.
  * Returns null if no frontmatter found.
+ * Supports block scalars: > (folded) and | (literal).
  */
 export function parseSkillFrontmatter(
   content: string,
@@ -10,16 +11,34 @@ export function parseSkillFrontmatter(
   // biome-ignore lint/style/noNonNullAssertion: match[1] is defined because the regex has a capturing group
   const block = match[1]!;
   const data: Record<string, unknown> = {};
-  for (const line of block.split("\n")) {
+  const lines = block.split("\n");
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i]!;
     const sep = line.indexOf(":");
-    if (sep === -1) continue;
+    if (sep === -1) { i++; continue; }
     const key = line.slice(0, sep).trim();
-    if (!key) continue;
+    if (!key) { i++; continue; }
     const raw = line.slice(sep + 1).trim();
-    if (raw === "true") data[key] = true;
-    else if (raw === "false") data[key] = false;
-    else if (raw !== "" && !Number.isNaN(Number(raw))) data[key] = Number(raw);
-    else data[key] = raw;
+    if (raw === ">" || raw === "|") {
+      const style = raw;
+      const parts: string[] = [];
+      i++;
+      while (i < lines.length) {
+        const next = lines[i]!;
+        if (next.length > 0 && (next[0] === " " || next[0] === "\t")) {
+          parts.push(next.trimStart());
+          i++;
+        } else break;
+      }
+      data[key] = style === ">" ? parts.join(" ").trim() : parts.join("\n").trimEnd();
+    } else {
+      if (raw === "true") data[key] = true;
+      else if (raw === "false") data[key] = false;
+      else if (raw !== "" && !Number.isNaN(Number(raw))) data[key] = Number(raw);
+      else data[key] = raw;
+      i++;
+    }
   }
   return data;
 }

package/src/install.npm.test.ts

@@ -439,7 +439,10 @@ describe("updateSkill — npm", () => {
           integrity: v2.integrity,
         });
 
-        const result = await updateSkill({ yes: true });
+        const result = await updateSkill(
+          { yes: true },
+          async () => ({ tier: "unverified" as const }),
+        );
         expect(result.ok).toBe(true);
         if (!result.ok) return;
 
@@ -464,5 +467,5 @@ describe("updateSkill — npm", () => {
       await removeTmpDir(tgzDir1);
       await removeTmpDir(tgzDir2);
     }
-  });
+  }, 30_000);
 });

package/src/install.test.ts

@@ -213,6 +213,59 @@ describe("installSkill — project scope", () => {
       await removeTmpDir(projectRoot);
     }
   });
+
+  test("saves to project installed.json, not global", async () => {
+    const repo = await createStandaloneSkillRepo();
+    const projectRoot = await makeTmpDir();
+    try {
+      await $`git -C ${projectRoot} init`.quiet();
+      await installSkill(repo.path, { scope: "project", projectRoot, skipScan: true });
+
+      // Project file should have the record
+      const projectInstalled = await loadInstalled(projectRoot);
+      expect(projectInstalled.ok).toBe(true);
+      if (!projectInstalled.ok) return;
+      expect(projectInstalled.value.skills.map((s) => s.name)).toContain("standalone-skill");
+
+      // Global file should be empty
+      const globalInstalled = await loadInstalled();
+      expect(globalInstalled.ok).toBe(true);
+      if (!globalInstalled.ok) return;
+      expect(globalInstalled.value.skills).toHaveLength(0);
+    } finally {
+      await repo.cleanup();
+      await removeTmpDir(projectRoot);
+    }
+  });
+
+  test("same skill in two projects coexist independently", async () => {
+    const repo = await createStandaloneSkillRepo();
+    const projectA = await makeTmpDir();
+    const projectB = await makeTmpDir();
+    try {
+      await $`git -C ${projectA} init`.quiet();
+      await $`git -C ${projectB} init`.quiet();
+
+      await installSkill(repo.path, { scope: "project", projectRoot: projectA, skipScan: true });
+      await installSkill(repo.path, { scope: "project", projectRoot: projectB, skipScan: true });
+
+      // Both project files have the record
+      const aInstalled = await loadInstalled(projectA);
+      const bInstalled = await loadInstalled(projectB);
+      expect(aInstalled.ok && aInstalled.value.skills).toHaveLength(1);
+      expect(bInstalled.ok && bInstalled.value.skills).toHaveLength(1);
+
+      // Global file is empty
+      const globalInstalled = await loadInstalled();
+      expect(globalInstalled.ok).toBe(true);
+      if (!globalInstalled.ok) return;
+      expect(globalInstalled.value.skills).toHaveLength(0);
+    } finally {
+      await repo.cleanup();
+      await removeTmpDir(projectA);
+      await removeTmpDir(projectB);
+    }
+  });
 });
 
 describe("removeSkill", () => {

package/src/install.ts

@@ -365,7 +365,8 @@ export async function installSkill(
   const allSemanticWarnings: SemanticWarning[] = [];
 
   // 1. Check already-installed
-  const installedResult = await loadInstalled();
+  const fileRoot = options.scope === "project" ? options.projectRoot : undefined;
+  const installedResult = await loadInstalled(fileRoot);
   if (!installedResult.ok) return installedResult;
   const installed = installedResult.value;
 
@@ -563,7 +564,7 @@ export async function installSkill(
 
     // 10. Save installed.json
     installed.skills.push(...newRecords);
-    const saveResult = await saveInstalled(installed);
+    const saveResult = await saveInstalled(installed, fileRoot);
     if (!saveResult.ok) return saveResult;
 
     return ok({

package/src/link.ts

@@ -38,7 +38,8 @@ export async function linkSkill(
   const skill = scanned[0]!;
 
   // 3. Load installed to check for conflicts
-  const installedResult = await loadInstalled();
+  const fileRoot = options.scope === "project" ? options.projectRoot : undefined;
+  const installedResult = await loadInstalled(fileRoot);
   if (!installedResult.ok) return installedResult;
   const installed = installedResult.value;
 
@@ -99,7 +100,7 @@ export async function linkSkill(
 
   // 8. Save installed.json
   installed.skills.push(record);
-  const saveResult = await saveInstalled(installed);
+  const saveResult = await saveInstalled(installed, fileRoot);
   if (!saveResult.ok) return saveResult;
 
   return ok(record);

package/src/remove.ts

@@ -17,7 +17,8 @@ export async function removeSkill(
   options: RemoveOptions = {},
 ): Promise<Result<void, UserError>> {
   debug("removeSkill", { name, scope: options.scope });
-  const installedResult = await loadInstalled();
+  const fileRoot = options.scope === "project" ? options.projectRoot : undefined;
+  const installedResult = await loadInstalled(fileRoot);
   if (!installedResult.ok) return installedResult;
   const installed = installedResult.value;
 
@@ -79,7 +80,7 @@ export async function removeSkill(
   }
 
   installed.skills.splice(idx, 1);
-  const saveResult = await saveInstalled(installed);
+  const saveResult = await saveInstalled(installed, fileRoot);
   if (!saveResult.ok) return saveResult;
 
   return ok(undefined);

package/src/schemas/config.ts

@@ -53,6 +53,8 @@ export const ConfigSchema = z.object({
   security: SecurityConfigSchema.prefault({}),
   "agent-mode": AgentModeSchema.prefault({}),
   registry: RegistryConfigSchema,
+  /** Whether the built-in skilltap-skills tap is enabled. Set to false to opt out. */
+  builtin_tap: z.boolean().default(true),
   taps: z
     .array(
       z.object({

package/src/symlink.ts

@@ -63,7 +63,7 @@ export async function removeAgentSymlinks(
   scope: "global" | "project" | "linked",
   projectRoot?: string,
 ): Promise<Result<void, UserError>> {
-  const effectiveScope = scope === "linked" ? "global" : scope;
+  const effectiveScope = scope === "linked" ? (projectRoot ? "project" : "global") : scope;
   for (const agent of agents) {
     const linkPath = symlinkPath(skillName, agent, effectiveScope, projectRoot);
     if (!linkPath) continue;

package/src/taps.ts

@@ -11,6 +11,12 @@ import type { Tap, TapSkill } from "./schemas/tap";
 import { TapSchema } from "./schemas/tap";
 import { err, type GitError, ok, type Result, UserError } from "./types";
 
+/** The built-in tap — always available unless explicitly opted out via config. */
+export const BUILTIN_TAP = {
+  name: "skilltap-skills",
+  url: "https://github.com/nklisch/skilltap-skills.git",
+} as const;
+
 export type TapEntry = { tapName: string; skill: TapSkill };
 
 export type UpdateTapResult = {
@@ -93,6 +99,27 @@ export function parseGitHubTapShorthand(
   };
 }
 
+/** Returns true if the built-in tap is already cloned locally. */
+export async function isBuiltinTapCloned(): Promise<boolean> {
+  return Bun.file(join(tapDir(BUILTIN_TAP.name), "tap.json")).exists();
+}
+
+/**
+ * Ensure the built-in tap is cloned locally. Idempotent — no-op if already present.
+ * Returns ok(undefined) whether freshly cloned or already present.
+ */
+export async function ensureBuiltinTap(): Promise<Result<void, UserError | GitError>> {
+  const dir = tapDir(BUILTIN_TAP.name);
+  const exists = await Bun.file(join(dir, "tap.json")).exists();
+  if (exists) return ok(undefined);
+
+  const gitCheck = await checkGitInstalled();
+  if (!gitCheck.ok) return gitCheck;
+
+  const cloneResult = await clone(BUILTIN_TAP.url, dir, { depth: 1 });
+  return cloneResult;
+}
+
 export async function addTap(
   name: string,
   url: string,
@@ -102,6 +129,15 @@ export async function addTap(
   if (!configResult.ok) return configResult;
   const config = configResult.value;
 
+  if (name === BUILTIN_TAP.name && config.builtin_tap !== false) {
+    return err(
+      new UserError(
+        `'${BUILTIN_TAP.name}' is the built-in tap and is already included.`,
+        "To disable it, set 'builtin_tap = false' in your config.toml.",
+      ),
+    );
+  }
+
   if (config.taps.some((t) => t.name === name)) {
     return err(
       new UserError(
@@ -153,6 +189,23 @@ export async function removeTap(
   if (!configResult.ok) return configResult;
   const config = configResult.value;
 
+  // Special case: disable the built-in tap
+  if (name === BUILTIN_TAP.name) {
+    if (config.builtin_tap === false) {
+      return err(
+        new UserError(
+          `Built-in tap '${BUILTIN_TAP.name}' is already disabled.`,
+          "Set 'builtin_tap = true' in config.toml to re-enable it.",
+        ),
+      );
+    }
+    config.builtin_tap = false;
+    const saveResult = await saveConfig(config);
+    if (!saveResult.ok) return saveResult;
+    await rm(tapDir(name), { recursive: true, force: true });
+    return ok(undefined);
+  }
+
   const idx = config.taps.findIndex((t) => t.name === name);
   if (idx === -1) {
     return err(
@@ -182,6 +235,46 @@ export async function updateTap(
   if (!configResult.ok) return configResult;
   const config = configResult.value;
 
+  const updated: Record<string, number> = {};
+  const http: string[] = [];
+
+  // Handle built-in tap: update if enabled and requested
+  if (name === BUILTIN_TAP.name) {
+    if (config.builtin_tap === false) {
+      return err(
+        new UserError(
+          `Tap '${BUILTIN_TAP.name}' is not configured.`,
+          "Set 'builtin_tap = true' in config.toml to re-enable it.",
+        ),
+      );
+    }
+    const dir = tapDir(BUILTIN_TAP.name);
+    if (!(await Bun.file(join(dir, "tap.json")).exists())) {
+      return err(
+        new UserError(
+          `Built-in tap '${BUILTIN_TAP.name}' is not yet cloned.`,
+          "Run 'skilltap tap install' to set it up.",
+        ),
+      );
+    }
+    const pullResult = await pull(dir);
+    if (!pullResult.ok) return pullResult;
+    const tapResult = await loadTapJson(dir, BUILTIN_TAP.name);
+    updated[BUILTIN_TAP.name] = tapResult.ok ? tapResult.value.skills.length : 0;
+    return ok({ updated, http });
+  }
+
+  // Update all: include built-in tap if enabled and cloned
+  if (!name && config.builtin_tap !== false) {
+    const dir = tapDir(BUILTIN_TAP.name);
+    if (await Bun.file(join(dir, "tap.json")).exists()) {
+      const pullResult = await pull(dir);
+      if (!pullResult.ok) return pullResult;
+      const tapResult = await loadTapJson(dir, BUILTIN_TAP.name);
+      updated[BUILTIN_TAP.name] = tapResult.ok ? tapResult.value.skills.length : 0;
+    }
+  }
+
   const targets = name
     ? config.taps.filter((t) => t.name === name)
     : config.taps;
@@ -195,9 +288,6 @@ export async function updateTap(
     );
   }
 
-  const updated: Record<string, number> = {};
-  const http: string[] = [];
-
   for (const tap of targets) {
     if (tap.type === "http") {
       http.push(tap.name);
@@ -223,6 +313,17 @@ export async function loadTaps(): Promise<Result<TapEntry[], UserError>> {
 
   const entries: TapEntry[] = [];
 
+  // Load built-in tap first (if enabled and already cloned)
+  if (config.builtin_tap !== false) {
+    const dir = tapDir(BUILTIN_TAP.name);
+    const tapResult = await loadTapJson(dir, BUILTIN_TAP.name);
+    if (tapResult.ok) {
+      for (const skill of tapResult.value.skills) {
+        entries.push({ tapName: BUILTIN_TAP.name, skill });
+      }
+    }
+  }
+
   for (const tap of config.taps) {
     if (tap.type === "http") {
       // HTTP registry: fetch skills from API

package/src/update.test.ts

@@ -314,4 +314,74 @@ describe("updateSkill — multi-skill", () => {
       await repo.cleanup();
     }
   });
+
+  test("both skills from same repo are checked when both installed", async () => {
+    const repo = await createMultiSkillRepo();
+    try {
+      // Install BOTH skills from the multi-skill repo
+      await installSkill(repo.path, { scope: "global", skipScan: true });
+
+      // Add a commit that changes BOTH skill paths
+      await addFileAndCommit(repo.path, ".agents/skills/skill-a/patch.md", "# Patch A");
+      await addFileAndCommit(repo.path, ".agents/skills/skill-b/patch.md", "# Patch B");
+
+      const result = await updateSkill({ yes: true });
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+
+      expect(result.value.updated).toContain("skill-a");
+      expect(result.value.updated).toContain("skill-b");
+    } finally {
+      await repo.cleanup();
+    }
+  });
+
+  test("skill with no path changes is upToDate even when repo has changes", async () => {
+    const repo = await createMultiSkillRepo();
+    try {
+      // Install BOTH skills from the multi-skill repo
+      await installSkill(repo.path, { scope: "global", skipScan: true });
+
+      // Add a commit that ONLY changes skill-a's path
+      await addFileAndCommit(repo.path, ".agents/skills/skill-a/only-a.md", "# Only A");
+
+      const result = await updateSkill({ yes: true });
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+
+      // skill-a has changes → updated
+      expect(result.value.updated).toContain("skill-a");
+      // skill-b has no path-specific changes → upToDate (not skipped, not updated)
+      expect(result.value.upToDate).toContain("skill-b");
+      expect(result.value.skipped).not.toContain("skill-b");
+    } finally {
+      await repo.cleanup();
+    }
+  });
+});
+
+describe("updateSkill — project scope", () => {
+  test("updates skills in project installed.json when projectRoot provided", async () => {
+    const repo = await createStandaloneSkillRepo();
+    const projectRoot = await makeTmpDir();
+    try {
+      await installSkill(repo.path, { scope: "project", projectRoot, skipScan: true });
+      await addFileAndCommit(repo.path, "new-file.md", "# New content");
+
+      const result = await updateSkill({ yes: true, projectRoot });
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+
+      expect(result.value.updated).toContain("standalone-skill");
+
+      // Project installed.json should have updated SHA
+      const projectInstalled = await loadInstalled(projectRoot);
+      expect(projectInstalled.ok).toBe(true);
+      if (!projectInstalled.ok) return;
+      expect(projectInstalled.value.skills[0]?.sha).toBeTruthy();
+    } finally {
+      await repo.cleanup();
+      await removeTmpDir(projectRoot);
+    }
+  });
 });

package/src/update.ts

@@ -14,7 +14,7 @@ import {
   resolveVersion,
 } from "./npm-registry";
 import { skillCacheDir, skillInstallDir } from "./paths";
-import type { InstalledSkill } from "./schemas/installed";
+import type { InstalledJson, InstalledSkill } from "./schemas/installed";
 import type { StaticWarning } from "./security";
 import { scanDiff, scanStatic } from "./security";
 import type { SemanticWarning } from "./security/semantic";
@@ -22,6 +22,8 @@ import { scanSemantic } from "./security/semantic";
 import { wrapShell } from "./shell";
 import { createAgentSymlinks, removeAgentSymlinks } from "./symlink";
 import { parseGitHubRepo, resolveTrust } from "./trust";
+
+type ResolveTrustFn = typeof resolveTrust;
 import type { Result } from "./types";
 import {
   err,
@@ -39,7 +41,7 @@ export type UpdateOptions = {
   yes?: boolean;
   /** Skip skills that have security warnings in their diff */
   strict?: boolean;
-  /** Project root for project-scoped symlink re-creation */
+  /** Project root — also processes project-scoped skills from {projectRoot}/.agents/installed.json */
   projectRoot?: string;
   onProgress?: (
     skillName: string,
@@ -172,6 +174,7 @@ async function updateNpmSkill(
   installed: { skills: InstalledSkill[] },
   options: UpdateOptions,
   result: UpdateResult,
+  _resolveTrust: ResolveTrustFn,
 ): Promise<Result<void, UserError | NetworkError | ScanError>> {
   // biome-ignore lint/style/noNonNullAssertion: caller checks record.repo?.startsWith("npm:")
   const { name: packageName } = parseNpmSource(record.repo!);
@@ -262,7 +265,7 @@ async function updateNpmSkill(
     await refreshAgentSymlinks(record, options.projectRoot);
 
     // Re-verify trust for the new version
-    const newTrust = await resolveTrust({
+    const newTrust = await _resolveTrust({
       adapter: "npm",
       url: record.repo!,
       tap: record.tap,
@@ -288,34 +291,19 @@ async function updateNpmSkill(
   }
 }
 
-/** Handle updates for git-sourced skills (SHA comparison, diff scanning). */
+/** Handle updates for standalone git skills (path === null; workDir is the install dir). */
 async function updateGitSkill(
   record: InstalledSkill,
   installed: { skills: InstalledSkill[] },
   options: UpdateOptions,
   result: UpdateResult,
+  _resolveTrust: ResolveTrustFn,
 ): Promise<Result<void, UserError | GitError | ScanError>> {
-  // Standalone: work dir is the install path. Multi-skill: work dir is the cache.
-  const isMulti = record.path !== null;
-  const workDir = isMulti
-    ? skillCacheDir(record.repo!)
-    : skillInstallDir(
-        record.name,
-        record.scope as "global" | "project",
-        options.projectRoot,
-      );
-
-  // For multi-skill, verify cache exists
-  if (isMulti) {
-    const cacheGitExists = await lstat(join(workDir, ".git"))
-      .then(() => true)
-      .catch(() => false);
-    if (!cacheGitExists) {
-      result.skipped.push(record.name);
-      options.onProgress?.(record.name, "skipped");
-      return ok(undefined);
-    }
-  }
+  const workDir = skillInstallDir(
+    record.name,
+    record.scope as "global" | "project",
+    options.projectRoot,
+  );
 
   const fetchResult = await fetch(workDir);
   if (!fetchResult.ok) return fetchResult;
@@ -334,69 +322,42 @@ async function updateGitSkill(
     return ok(undefined);
   }
 
-  // Get diff (path-filtered for multi-skill)
-  const pathSpec = record.path ?? undefined;
-  const diffResult = await diff(workDir, "HEAD", "FETCH_HEAD", pathSpec);
+  const diffResult = await diff(workDir, "HEAD", "FETCH_HEAD");
   if (!diffResult.ok) return diffResult;
-  const diffOutput = diffResult.value;
 
-  const statResult = await diffStat(workDir, "HEAD", "FETCH_HEAD", pathSpec);
+  const statResult = await diffStat(workDir, "HEAD", "FETCH_HEAD");
   if (!statResult.ok) return statResult;
   const stat = statResult.value;
 
-  // If skill-specific path has no changes, mark as up to date
-  if (stat.filesChanged === 0) {
-    result.upToDate.push(record.name);
-    options.onProgress?.(record.name, "upToDate");
-    return ok(undefined);
-  }
-
   options.onDiff?.(record.name, stat, localSha, remoteSha);
 
-  // Security scan on diff + confirmation
-  const warnings = scanDiff(diffOutput);
+  const warnings = scanDiff(diffResult.value);
   if (await shouldSkipUpdate(warnings, options, record.name)) {
     result.skipped.push(record.name);
     options.onProgress?.(record.name, "skipped");
     return ok(undefined);
   }
 
-  // Apply update
   const pullResult = await pull(workDir);
   if (!pullResult.ok) return pullResult;
 
-  if (isMulti) {
-    const recopyResult = await recopyMultiSkill(workDir, record, options.projectRoot);
-    if (!recopyResult.ok) return recopyResult;
-  }
-
-  const installDir = skillInstallDir(
-    record.name,
-    record.scope as "global" | "project",
-    options.projectRoot,
-  );
-
-  // Semantic scan on updated skill directory
-  if (await runUpdateSemanticScan(installDir, record.name, options)) {
+  if (await runUpdateSemanticScan(workDir, record.name, options)) {
     result.skipped.push(record.name);
     options.onProgress?.(record.name, "skipped");
     return ok(undefined);
   }
 
-  // Get new SHA
   const newShaResult = await revParse(workDir, "HEAD");
   if (!newShaResult.ok) return newShaResult;
 
-  // Re-verify trust for the updated skill
-  const newTrust = await resolveTrust({
+  const newTrust = await _resolveTrust({
     adapter: "git",
     url: record.repo ?? "",
     tap: record.tap,
-    skillDir: installDir,
+    skillDir: workDir,
     githubRepo: record.repo ? parseGitHubRepo(record.repo) : null,
   });
 
-  // Update the record in place
   patchRecord(installed, record, {
     sha: newShaResult.value,
     updatedAt: new Date().toISOString(),
@@ -410,18 +371,232 @@ async function updateGitSkill(
   return ok(undefined);
 }
 
+/** Handle updates for a group of skills sharing the same multi-skill git repo cache. */
+async function updateGitSkillGroup(
+  repo: string,
+  skills: InstalledSkill[],
+  installed: { skills: InstalledSkill[] },
+  options: UpdateOptions,
+  result: UpdateResult,
+  _resolveTrust: ResolveTrustFn,
+): Promise<Result<void, UserError | GitError | ScanError>> {
+  const workDir = skillCacheDir(repo);
+
+  // Verify cache exists
+  const cacheGitExists = await lstat(join(workDir, ".git"))
+    .then(() => true)
+    .catch(() => false);
+  if (!cacheGitExists) {
+    for (const skill of skills) {
+      result.skipped.push(skill.name);
+      options.onProgress?.(skill.name, "skipped");
+    }
+    return ok(undefined);
+  }
+
+  // Fetch once for the whole group
+  const fetchResult = await fetch(workDir);
+  if (!fetchResult.ok) return fetchResult;
+
+  // Capture SHAs BEFORE any pull
+  const localShaResult = await revParse(workDir, "HEAD");
+  if (!localShaResult.ok) return localShaResult;
+  const remoteShaResult = await revParse(workDir, "FETCH_HEAD");
+  if (!remoteShaResult.ok) return remoteShaResult;
+
+  const localSha = localShaResult.value;
+  const remoteSha = remoteShaResult.value;
+
+  // If the whole repo is up to date, all skills in the group are too
+  if (localSha === remoteSha) {
+    for (const skill of skills) {
+      result.upToDate.push(skill.name);
+      options.onProgress?.(skill.name, "upToDate");
+    }
+    return ok(undefined);
+  }
+
+  // Per-skill: check path-specific diff, scan, confirm
+  const toUpdate: InstalledSkill[] = [];
+  for (const skill of skills) {
+    options.onProgress?.(skill.name, "checking");
+
+    // biome-ignore lint/style/noNonNullAssertion: multi-skill records always have path
+    const pathSpec = skill.path!;
+
+    const statResult = await diffStat(workDir, "HEAD", "FETCH_HEAD", pathSpec);
+    if (!statResult.ok) return statResult;
+    const stat = statResult.value;
+
+    if (stat.filesChanged === 0) {
+      result.upToDate.push(skill.name);
+      options.onProgress?.(skill.name, "upToDate");
+      continue;
+    }
+
+    options.onDiff?.(skill.name, stat, localSha, remoteSha);
+
+    const diffResult = await diff(workDir, "HEAD", "FETCH_HEAD", pathSpec);
+    if (!diffResult.ok) return diffResult;
+
+    const warnings = scanDiff(diffResult.value);
+    if (await shouldSkipUpdate(warnings, options, skill.name)) {
+      result.skipped.push(skill.name);
+      options.onProgress?.(skill.name, "skipped");
+      continue;
+    }
+
+    toUpdate.push(skill);
+  }
+
+  if (toUpdate.length === 0) return ok(undefined);
+
+  // Pull once for the whole group
+  const pullResult = await pull(workDir);
+  if (!pullResult.ok) return pullResult;
+
+  const newShaResult = await revParse(workDir, "HEAD");
+  if (!newShaResult.ok) return newShaResult;
+  const newSha = newShaResult.value;
+
+  // Apply update to each confirmed skill
+  for (const skill of toUpdate) {
+    const recopyResult = await recopyMultiSkill(workDir, skill, options.projectRoot);
+    if (!recopyResult.ok) return recopyResult;
+
+    const installDir = skillInstallDir(
+      skill.name,
+      skill.scope as "global" | "project",
+      options.projectRoot,
+    );
+
+    if (await runUpdateSemanticScan(installDir, skill.name, options)) {
+      result.skipped.push(skill.name);
+      options.onProgress?.(skill.name, "skipped");
+      continue;
+    }
+
+    const newTrust = await _resolveTrust({
+      adapter: "git",
+      url: skill.repo ?? "",
+      tap: skill.tap,
+      skillDir: installDir,
+      githubRepo: skill.repo ? parseGitHubRepo(skill.repo) : null,
+    });
+
+    patchRecord(installed, skill, {
+      sha: newSha,
+      updatedAt: new Date().toISOString(),
+      trust: newTrust,
+    });
+
+    await refreshAgentSymlinks(skill, options.projectRoot);
+
+    result.updated.push(skill.name);
+    options.onProgress?.(skill.name, "updated");
+  }
+
+  return ok(undefined);
+}
+
+type SkillGroup =
+  | { type: "linked"; skill: InstalledSkill }
+  | { type: "npm"; skill: InstalledSkill }
+  | { type: "git-standalone"; skill: InstalledSkill }
+  | { type: "git-multi"; repo: string; skills: InstalledSkill[] };
+
+/** Group skills by update strategy. Multi-skill records sharing a repo cache are grouped together. */
+function groupSkillsByRepo(skills: InstalledSkill[]): SkillGroup[] {
+  const multiGroups = new Map<string, InstalledSkill[]>();
+  const solo: SkillGroup[] = [];
+
+  for (const skill of skills) {
+    if (skill.scope === "linked") {
+      solo.push({ type: "linked", skill });
+      continue;
+    }
+    if (skill.repo?.startsWith("npm:")) {
+      solo.push({ type: "npm", skill });
+      continue;
+    }
+    if (skill.path !== null && skill.repo) {
+      const existing = multiGroups.get(skill.repo);
+      if (existing) {
+        existing.push(skill);
+      } else {
+        multiGroups.set(skill.repo, [skill]);
+      }
+    } else {
+      solo.push({ type: "git-standalone", skill });
+    }
+  }
+
+  const groups: SkillGroup[] = [...solo];
+  for (const [repo, skills] of multiGroups) {
+    groups.push({ type: "git-multi", repo, skills });
+  }
+  return groups;
+}
+
+async function runUpdatePass(
+  skills: InstalledSkill[],
+  installed: InstalledJson,
+  options: UpdateOptions,
+  result: UpdateResult,
+  _resolveTrust: ResolveTrustFn,
+): Promise<Result<void, UserError | GitError | ScanError | NetworkError>> {
+  const groups = groupSkillsByRepo(skills);
+
+  for (const group of groups) {
+    if (group.type === "linked") {
+      options.onProgress?.(group.skill.name, "linked");
+      continue;
+    }
+
+    if (group.type === "npm") {
+      options.onProgress?.(group.skill.name, "checking");
+      const r = await updateNpmSkill(group.skill, installed, options, result, _resolveTrust);
+      if (!r.ok) return r;
+    } else if (group.type === "git-standalone") {
+      options.onProgress?.(group.skill.name, "checking");
+      const r = await updateGitSkill(group.skill, installed, options, result, _resolveTrust);
+      if (!r.ok) return r;
+    } else {
+      const r = await updateGitSkillGroup(group.repo, group.skills, installed, options, result, _resolveTrust);
+      if (!r.ok) return r;
+    }
+  }
+
+  return ok(undefined);
+}
+
 export async function updateSkill(
   options: UpdateOptions = {},
+  _resolveTrust: ResolveTrustFn = resolveTrust,
 ): 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;
 
-  let skills = installed.skills;
+  // Load global installed
+  const globalInstalledResult = await loadInstalled();
+  if (!globalInstalledResult.ok) return globalInstalledResult;
+  const globalInstalled = globalInstalledResult.value;
+
+  // Optionally load project installed
+  let projectInstalled: InstalledJson | null = null;
+  if (options.projectRoot) {
+    const r = await loadInstalled(options.projectRoot);
+    if (!r.ok) return r;
+    projectInstalled = r.value;
+  }
+
+  // Filter by name if specified — check both files
+  let globalSkills = globalInstalled.skills;
+  let projectSkills = projectInstalled?.skills ?? [];
+
   if (options.name) {
-    const found = skills.filter((s) => s.name === options.name);
-    if (found.length === 0) {
+    globalSkills = globalSkills.filter((s) => s.name === options.name);
+    projectSkills = projectSkills.filter((s) => s.name === options.name);
+    if (globalSkills.length === 0 && projectSkills.length === 0) {
       return err(
         new UserError(
           `Skill '${options.name}' is not installed.`,
@@ -429,31 +604,28 @@ export async function updateSkill(
         ),
       );
     }
-    skills = found;
   }
 
   const result: UpdateResult = { updated: [], skipped: [], upToDate: [] };
 
-  for (const record of skills) {
-    if (record.scope === "linked") {
-      options.onProgress?.(record.name, "linked");
-      continue;
-    }
+  // Process global skills
+  const globalPass = await runUpdatePass(globalSkills, globalInstalled, options, result, _resolveTrust);
+  if (!globalPass.ok) return globalPass;
 
-    options.onProgress?.(record.name, "checking");
-
-    // Dispatch to adapter-specific update handler
-    if (record.repo?.startsWith("npm:")) {
-      const npmResult = await updateNpmSkill(record, installed, options, result);
-      if (!npmResult.ok) return npmResult;
-    } else {
-      const gitResult = await updateGitSkill(record, installed, options, result);
-      if (!gitResult.ok) return gitResult;
-    }
+  // Process project skills
+  if (projectInstalled) {
+    const projectPass = await runUpdatePass(projectSkills, projectInstalled, { ...options, projectRoot: options.projectRoot }, result, _resolveTrust);
+    if (!projectPass.ok) return projectPass;
   }
 
-  const saveResult = await saveInstalled(installed);
-  if (!saveResult.ok) return saveResult;
+  // Save both files
+  const globalSave = await saveInstalled(globalInstalled);
+  if (!globalSave.ok) return globalSave;
+
+  if (projectInstalled && options.projectRoot) {
+    const projectSave = await saveInstalled(projectInstalled, options.projectRoot);
+    if (!projectSave.ok) return projectSave;
+  }
 
   return ok(result);
 }