@dealdeploy/skl 1.1.1 → 1.3.0

package/add.ts

@@ -16,11 +16,12 @@ const CATALOG = catalogDir();
 
 const allFlag = process.argv.includes("--all");
 const repoArg = process.argv.slice(3).find((a) => !a.startsWith("-")) ?? "";
-const repo = parseRepoArg(repoArg);
-if (!repo) {
+const repoParsed = parseRepoArg(repoArg);
+if (!repoParsed) {
   console.error("Usage: skl add owner/repo [--all]");
   process.exit(1);
 }
+const repo: string = repoParsed;
 
 // ── Helpers ──────────────────────────────────────────────────────────
 

package/index.ts

@@ -4,16 +4,23 @@ import { createCliRenderer } from "@opentui/core";
 import { existsSync, rmSync, mkdirSync, readdirSync, statSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
-import { getCatalogSkills, removeFromLock, catalogDir, buildAddArgs } from "./lib.ts";
+import { getCatalogSkills, removeFromLock, catalogDir, buildAddArgs, readLock, detectProjectAgents } from "./lib.ts";
 import { createTui, type ColId } from "./tui.ts";
+import { checkForUpdate } from "./update-check.ts";
 
 // @ts-ignore - bun supports JSON imports
 const { version: VERSION } = await import("./package.json");
 
+// Fire update check in background (non-blocking)
+const updateMsg = checkForUpdate(VERSION);
+
 // ── Flags ────────────────────────────────────────────────────────────
+const debug = process.argv.includes("--debug");
 const arg = process.argv[2];
 if (arg === "-v" || arg === "--version") {
   console.log(`skl ${VERSION}`);
+  const msg = await updateMsg;
+  if (msg) console.log(msg);
   process.exit(0);
 }
 if (arg === "-h" || arg === "--help" || arg === "help") {
@@ -24,21 +31,36 @@ Usage:
   skl add <repo>     Add skills from a GitHub repo (interactive)
   skl add <repo> --all  Add all skills from a repo (non-interactive)
   skl update         Update all remote skills
+  skl migrate        Migrate old symlinks to use the catalog
+  skl migrate -l     Migrate local project symlinks
   skl help           Show this help message
 
 Options:
   -h, --help         Show this help message
-  -v, --version      Show version`);
+  -v, --version      Show version
+  --debug            Show full error output on failures`);
   process.exit(0);
 }
 
 // ── Subcommand routing ───────────────────────────────────────────────
+async function printUpdateMsg() {
+  const msg = await updateMsg;
+  if (msg) console.log(`\n${msg}`);
+}
+
 if (arg === "add") {
   await import("./add.ts");
+  await printUpdateMsg();
   process.exit(0);
 }
 if (arg === "update") {
   await import("./update.ts");
+  await printUpdateMsg();
+  process.exit(0);
+}
+if (arg === "migrate") {
+  await import("./migrate.ts");
+  await printUpdateMsg();
   process.exit(0);
 }
 
@@ -64,27 +86,47 @@ function readInstalledSkills(dir: string): Set<string> {
 const globalInstalled = readInstalledSkills(join(homedir(), ".claude/skills"));
 const localInstalled = readInstalledSkills(join(process.cwd(), ".claude/skills"));
 
+// Always install to .agents/skills (universal), plus any other agent dirs found in the project.
+const projectAgents = [...new Set(["universal", ...detectProjectAgents(process.cwd())])];
+
 // ── Create TUI ──────────────────────────────────────────────────────
 
 const renderer = await createCliRenderer({ exitOnCtrlC: true });
 
+const allSkills = getCatalogSkills();
+const lock = readLock();
+const skillRepos = new Map<string, string | null>();
+for (const name of allSkills) {
+  skillRepos.set(name, lock.skills[name]?.source || null);
+}
+
 const tui = createTui(renderer, {
-  allSkills: getCatalogSkills(),
+  allSkills,
+  skillRepos,
   globalInstalled,
   localInstalled,
   catalogPath: CATALOG,
 
   async onToggle(col: ColId, name: string, enable: boolean) {
     const isGlobal = col === "global";
+    const agentArgs = isGlobal ? [] : ["--agent", ...projectAgents];
     const args = enable
-      ? buildAddArgs(CATALOG, name, isGlobal)
-      : ["remove", name, "-y", ...(isGlobal ? ["-g"] : [])];
+      ? buildAddArgs(CATALOG, name, isGlobal, projectAgents)
+      : ["remove", name, "-y", ...agentArgs, ...(isGlobal ? ["-g"] : [])];
     const proc = Bun.spawn(["npx", "-y", "skills", ...args], {
       stdout: "pipe",
       stderr: "pipe",
     });
-    const code = await proc.exited;
-    return code === 0;
+    const [code, stdout, stderr] = await Promise.all([
+      proc.exited,
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    if (code === 0) return true;
+    if (debug) {
+      return (stderr || stdout).trim() || `exit code ${code}`;
+    }
+    return false;
   },
 
   async onDelete(name: string) {
@@ -98,7 +140,7 @@ const tui = createTui(renderer, {
     }
     if (localInstalled.has(name)) {
       procs.push(
-        Bun.spawn(["npx", "-y", "skills", "remove", name, "-y"], {
+        Bun.spawn(["npx", "-y", "skills", "remove", name, "-y", "--agent", ...projectAgents], {
           stdout: "pipe", stderr: "pipe",
         })
       );
@@ -123,8 +165,9 @@ const tui = createTui(renderer, {
     process.exit(0);
   },
 
-  onQuit() {
+  async onQuit() {
     renderer.destroy();
+    await printUpdateMsg();
     process.exit(0);
   },
 });

package/lib.test.ts

@@ -16,6 +16,7 @@ import {
   findSkillEntries,
   parseRepoArg,
   buildAddArgs,
+  detectProjectAgents,
   parseSkillsListOutput,
   planUpdates,
   groupByRepo,
@@ -287,7 +288,7 @@ describe("parseRepoArg", () => {
 // ── buildAddArgs ────────────────────────────────────────────────────
 
 describe("buildAddArgs", () => {
-  test("uses lock entry sourceUrl for remote skill", () => {
+  test("uses lock entry sourceUrl for remote skill with project agents", () => {
     const entry: LockEntry = {
       source: "owner/repo",
       sourceUrl: "https://github.com/owner/repo",
@@ -297,11 +298,11 @@ describe("buildAddArgs", () => {
     };
     addToLock("myskill", entry);
 
-    const args = buildAddArgs("/catalog", "myskill", false);
-    expect(args).toEqual(["add", "https://github.com/owner/repo", "--skill", "myskill", "-y"]);
+    const args = buildAddArgs("/catalog", "myskill", false, ["claude-code", "roo"]);
+    expect(args).toEqual(["add", "https://github.com/owner/repo", "--skill", "myskill", "-y", "--agent", "claude-code", "roo"]);
   });
 
-  test("adds -g flag for global remote skill", () => {
+  test("global install does not pass --agent", () => {
     const entry: LockEntry = {
       source: "owner/repo",
       sourceUrl: "https://github.com/owner/repo",
@@ -311,14 +312,14 @@ describe("buildAddArgs", () => {
     };
     addToLock("myskill", entry);
 
-    const args = buildAddArgs("/catalog", "myskill", true);
+    const args = buildAddArgs("/catalog", "myskill", true, ["claude-code"]);
     expect(args).toContain("-g");
+    expect(args).not.toContain("--agent");
   });
 
-  test("uses catalog path for hand-authored skill", () => {
-    // No lock entry for this skill
-    const args = buildAddArgs("/my/catalog", "custom-skill", false);
-    expect(args).toEqual(["add", "/my/catalog/custom-skill", "-y"]);
+  test("uses catalog path for hand-authored skill with project agents", () => {
+    const args = buildAddArgs("/my/catalog", "custom-skill", false, ["claude-code"]);
+    expect(args).toEqual(["add", "/my/catalog/custom-skill", "-y", "--agent", "claude-code"]);
   });
 
   test("adds -g flag for global hand-authored skill", () => {
@@ -327,6 +328,45 @@ describe("buildAddArgs", () => {
   });
 });
 
+// ── detectProjectAgents ─────────────────────────────────────────────
+
+describe("detectProjectAgents", () => {
+  test("detects .claude directory", () => {
+    const dir = mkdtempSync(join(tmpdir(), "skl-detect-"));
+    mkdirSync(join(dir, ".claude"));
+    const agents = detectProjectAgents(dir);
+    expect(agents).toEqual(["claude-code"]);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("detects multiple agent directories", () => {
+    const dir = mkdtempSync(join(tmpdir(), "skl-detect-"));
+    mkdirSync(join(dir, ".claude"));
+    mkdirSync(join(dir, ".roo"));
+    const agents = detectProjectAgents(dir);
+    expect(agents).toContain("claude-code");
+    expect(agents).toContain("roo");
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("returns empty array when no agent dirs exist (caller decides fallback)", () => {
+    const dir = mkdtempSync(join(tmpdir(), "skl-detect-"));
+    const agents = detectProjectAgents(dir);
+    expect(agents).toEqual([]);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("detects .agents dir and maps to universal agents", () => {
+    const dir = mkdtempSync(join(tmpdir(), "skl-detect-"));
+    mkdirSync(join(dir, ".agents"));
+    const agents = detectProjectAgents(dir);
+    expect(agents).toContain("cursor");
+    expect(agents).toContain("codex");
+    expect(agents).toContain("opencode");
+    rmSync(dir, { recursive: true, force: true });
+  });
+});
+
 // ── parseSkillsListOutput ───────────────────────────────────────────
 
 describe("parseSkillsListOutput", () => {

package/lib.ts

@@ -112,19 +112,71 @@ export function parseRepoArg(input: string): string | null {
   return repo;
 }
 
+// ── Agent detection ─────────────────────────────────────────────────
+// Maps local project directories to skills CLI agent names.
+// Synced from: vercel-labs/skills src/agents.ts
+const DIR_TO_AGENTS: Record<string, string[]> = {
+  ".agents":      ["amp", "cline", "codex", "cursor", "gemini-cli", "github-copilot", "kimi-cli", "opencode", "replit", "universal"],
+  ".agent":       ["antigravity"],
+  ".augment":     ["augment"],
+  ".claude":      ["claude-code"],
+  ".codebuddy":   ["codebuddy"],
+  ".commandcode": ["command-code"],
+  ".continue":    ["continue"],
+  ".cortex":      ["cortex"],
+  ".crush":       ["crush"],
+  ".factory":     ["droid"],
+  ".goose":       ["goose"],
+  ".iflow":       ["iflow-cli"],
+  ".junie":       ["junie"],
+  ".kilocode":    ["kilo"],
+  ".kiro":        ["kiro-cli"],
+  ".kode":        ["kode"],
+  ".mcpjam":      ["mcpjam"],
+  ".mux":         ["mux"],
+  ".neovate":     ["neovate"],
+  ".openhands":   ["openhands"],
+  ".pi":          ["pi"],
+  ".pochi":       ["pochi"],
+  ".qoder":       ["qoder"],
+  ".qwen":        ["qwen-code"],
+  ".roo":         ["roo"],
+  ".trae":        ["trae", "trae-cn"],
+  ".vibe":        ["mistral-vibe"],
+  ".windsurf":    ["windsurf"],
+  ".zencoder":    ["zencoder"],
+  ".adal":        ["adal"],
+  "skills":       ["openclaw"],
+};
+
+/** Detect which agent directories exist in a project directory. */
+export function detectProjectAgents(cwd: string): string[] {
+  const agents: string[] = [];
+  for (const [dir, names] of Object.entries(DIR_TO_AGENTS)) {
+    if (existsSync(join(cwd, dir))) {
+      agents.push(...names);
+    }
+  }
+  return agents;
+}
+
 /** Build npx skills add args for a skill. */
 export function buildAddArgs(
   catalogPath: string,
   name: string,
   isGlobal: boolean,
+  projectAgents?: string[],
 ): string[] {
   const lockEntry = getLockEntry(name);
+  const agentArgs = !isGlobal && projectAgents
+    ? ["--agent", ...projectAgents]
+    : [];
   if (lockEntry) {
-    const args = ["add", lockEntry.sourceUrl, "--skill", name, "-y"];
+    const args = ["add", lockEntry.sourceUrl, "--skill", name, "-y", ...agentArgs];
     if (isGlobal) args.push("-g");
     return args;
   }
-  const args = ["add", join(catalogPath, name), "-y"];
+  const args = ["add", join(catalogPath, name), "-y", ...agentArgs];
   if (isGlobal) args.push("-g");
   return args;
 }

package/migrate.ts

@@ -0,0 +1,153 @@
+import { readdirSync, lstatSync, readlinkSync, rmSync } from "fs";
+import { join, resolve } from "path";
+import { homedir } from "os";
+import { catalogDir, buildAddArgs, getCatalogSkills, detectProjectAgents } from "./lib.ts";
+
+// ── Parse flags ──────────────────────────────────────────────────────
+const args = process.argv.slice(3);
+const localMode = args.includes("-l") || args.includes("--local");
+const dryRun = args.includes("--dry-run");
+
+const CATALOG = catalogDir();
+const catalogResolved = resolve(CATALOG);
+const catalogSkills = new Set(getCatalogSkills());
+
+// ── Determine directories ────────────────────────────────────────────
+const home = homedir();
+const dirsToScan = localMode
+  ? [join(process.cwd(), ".claude/skills"), join(process.cwd(), ".agents/skills")]
+  : [join(home, ".agents/skills"), join(home, ".claude/skills")];
+
+const isGlobal = !localMode;
+const projectAgents = localMode
+  ? [...new Set(["universal", ...detectProjectAgents(process.cwd())])]
+  : [];
+
+// ── Find stale symlinks ─────────────────────────────────────────────
+type StaleLink = { name: string; target: string; dir: string };
+
+function findStaleSymlinks(dir: string): StaleLink[] {
+  const stale: StaleLink[] = [];
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return stale;
+  }
+  for (const name of entries) {
+    const full = join(dir, name);
+    try {
+      const stat = lstatSync(full);
+      if (!stat.isSymbolicLink()) continue;
+      const target = resolve(dir, readlinkSync(full));
+      if (!target.startsWith(catalogResolved + "/")) {
+        stale.push({ name, target, dir });
+      }
+    } catch {
+      continue;
+    }
+  }
+  return stale;
+}
+
+// ── Collect and deduplicate ──────────────────────────────────────────
+const allStale: StaleLink[] = [];
+for (const dir of dirsToScan) {
+  allStale.push(...findStaleSymlinks(dir));
+}
+
+// Deduplicate by skill name (same skill may appear in multiple dirs)
+const byName = new Map<string, StaleLink[]>();
+for (const link of allStale) {
+  const list = byName.get(link.name) ?? [];
+  list.push(link);
+  byName.set(link.name, list);
+}
+
+if (byName.size === 0) {
+  console.log("No stale symlinks found. Everything is using the catalog.");
+  process.exit(0);
+}
+
+const inCatalog: string[] = [];
+const notInCatalog: string[] = [];
+for (const name of byName.keys()) {
+  if (catalogSkills.has(name)) {
+    inCatalog.push(name);
+  } else {
+    notInCatalog.push(name);
+  }
+}
+
+console.log(
+  `Found ${byName.size} stale symlink(s): ${inCatalog.length} in catalog, ${notInCatalog.length} missing from catalog`
+);
+
+if (dryRun) {
+  console.log("\nDry run — no changes will be made:\n");
+}
+
+// ── Migrate skills that are in the catalog ───────────────────────────
+let migrated = 0;
+let failed = 0;
+
+for (const name of inCatalog.sort()) {
+  const links = byName.get(name)!;
+  if (dryRun) {
+    console.log(`  ${name}: would migrate (${links.map((l) => l.dir).join(", ")})`);
+    continue;
+  }
+
+  process.stdout.write(`  ${name}...`);
+
+  // Remove all old symlinks for this skill
+  for (const link of links) {
+    rmSync(join(link.dir, link.name), { force: true });
+  }
+
+  // Reinstall from catalog (try lock-based source first, fall back to local catalog path)
+  const addArgs = buildAddArgs(CATALOG, name, isGlobal, isGlobal ? undefined : projectAgents);
+  let proc = Bun.spawn(["npx", "-y", "skills", ...addArgs], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  let code = await proc.exited;
+
+  // If remote source failed, fall back to local catalog path
+  if (code !== 0) {
+    const localArgs = ["add", join(CATALOG, name), "-y", ...(isGlobal ? ["-g"] : ["--agent", ...projectAgents])];
+    proc = Bun.spawn(["npx", "-y", "skills", ...localArgs], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    code = await proc.exited;
+  }
+
+  if (code === 0) {
+    console.log(" migrated");
+    migrated++;
+  } else {
+    const stderr = await new Response(proc.stderr).text();
+    console.log(` failed (exit ${code})`);
+    if (stderr.trim()) console.log(`    ${stderr.trim()}`);
+    failed++;
+  }
+}
+
+// ── Warn about skills not in catalog ─────────────────────────────────
+if (notInCatalog.length > 0) {
+  console.log(`\nNot in catalog (run \`skl add <repo>\` first):`);
+  for (const name of notInCatalog.sort()) {
+    const links = byName.get(name)!;
+    console.log(`  ${name} → ${links[0].target}`);
+  }
+}
+
+// ── Summary ──────────────────────────────────────────────────────────
+if (!dryRun) {
+  const parts: string[] = [];
+  if (migrated > 0) parts.push(`Migrated ${migrated} skill(s)`);
+  if (failed > 0) parts.push(`${failed} failed`);
+  if (notInCatalog.length > 0) parts.push(`${notInCatalog.length} need \`skl add\` first`);
+  console.log(`\n${parts.join(", ")}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dealdeploy/skl",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "TUI skill manager for Claude Code agents",
   "module": "index.ts",
   "bin": {

package/tsconfig.json

@@ -25,5 +25,6 @@
     "noUnusedLocals": false,
     "noUnusedParameters": false,
     "noPropertyAccessFromIndexSignature": false
-  }
+  },
+  "exclude": ["opensrc", "node_modules"]
 }

package/tui.test.ts

@@ -1,6 +1,6 @@
 import { test, expect, beforeEach, afterEach } from "bun:test";
 import { createTestRenderer } from "@opentui/core/testing";
-import { createTui, type ColId } from "./tui.ts";
+import { createTui, type ColId, type DisplayItem } from "./tui.ts";
 
 const WIDTH = 80;
 const HEIGHT = 20;
@@ -12,8 +12,10 @@ function setup(opts?: {
   skills?: string[];
   globalInstalled?: string[];
   localInstalled?: string[];
+  skillRepos?: Map<string, string | null>;
 }) {
   const skills = opts?.skills ?? ["alpha", "beta", "gamma"];
+  const skillRepos = opts?.skillRepos ?? new Map(skills.map((s) => [s, null]));
   const globalInstalled = new Set(opts?.globalInstalled ?? []);
   const localInstalled = new Set(opts?.localInstalled ?? []);
 
@@ -40,6 +42,7 @@ function setup(opts?: {
     makeDeps() {
       return {
         allSkills: skills,
+        skillRepos,
         globalInstalled,
         localInstalled,
         catalogPath: "/tmp/test-catalog",
@@ -64,6 +67,7 @@ function setup(opts?: {
     makeDepsImmediate(toggleResult = true) {
       return {
         allSkills: skills,
+        skillRepos,
         globalInstalled,
         localInstalled,
         catalogPath: "/tmp/test-catalog",
@@ -563,3 +567,159 @@ test("empty catalog renders without crashing", async () => {
 
   renderer.destroy();
 });
+
+// ── Repo grouping tests ───────────────────────────────────────────────
+
+test("renders repo section headers", async () => {
+  const skills = ["alpha", "beta"];
+  const skillRepos = new Map<string, string | null>([
+    ["alpha", "owner/repo-a"],
+    ["beta", "owner/repo-a"],
+  ]);
+  const ctx = setup({ skills, skillRepos });
+  const { renderer, renderOnce, captureCharFrame } =
+    await createTestRenderer({ width: WIDTH, height: HEIGHT });
+
+  createTui(renderer, ctx.makeDepsImmediate());
+  await renderOnce();
+
+  const frame = captureCharFrame();
+  expect(frame).toContain("owner/repo-a");
+  expect(frame).toContain("alpha");
+  expect(frame).toContain("beta");
+
+  renderer.destroy();
+});
+
+test("groups skills under their repo header", async () => {
+  const skills = ["alpha", "beta", "gamma"];
+  const skillRepos = new Map<string, string | null>([
+    ["alpha", "owner/repo-b"],
+    ["beta", "owner/repo-a"],
+    ["gamma", "owner/repo-b"],
+  ]);
+  const ctx = setup({ skills, skillRepos });
+  const { renderer, renderOnce } =
+    await createTestRenderer({ width: WIDTH, height: HEIGHT });
+
+  const tui = createTui(renderer, ctx.makeDepsImmediate());
+  await renderOnce();
+
+  const items = tui.state.displayItems;
+  // Repos sorted alphabetically: repo-a then repo-b
+  expect(items[0]).toEqual({ type: "header", repo: "owner/repo-a" });
+  expect(items[1]).toMatchObject({ type: "skill", name: "beta" });
+  expect(items[2]).toEqual({ type: "header", repo: "owner/repo-b" });
+  expect(items[3]).toMatchObject({ type: "skill", name: "alpha" });
+  expect(items[4]).toMatchObject({ type: "skill", name: "gamma" });
+
+  renderer.destroy();
+});
+
+test("cursor skips header rows", async () => {
+  const skills = ["alpha", "beta"];
+  const skillRepos = new Map<string, string | null>([
+    ["alpha", "owner/repo-a"],
+    ["beta", "owner/repo-b"],
+  ]);
+  const ctx = setup({ skills, skillRepos });
+  const { renderer, mockInput, renderOnce } =
+    await createTestRenderer({ width: WIDTH, height: HEIGHT });
+
+  const tui = createTui(renderer, ctx.makeDepsImmediate());
+
+  // Enter grid
+  mockInput.pressArrow("down");
+  await renderOnce();
+  expect(tui.state.focusArea).toBe("grid");
+  expect(tui.state.cursor).toBe(0);
+  // First skill should be alpha (repo-a comes first)
+  expect(tui.state.currentSkillIndex()).not.toBeNull();
+  const firstName = skills[tui.state.currentSkillIndex()!];
+  expect(firstName).toBe("alpha");
+
+  // Move down — should land on beta, skipping repo-b header
+  mockInput.pressArrow("down");
+  await renderOnce();
+  expect(tui.state.cursor).toBe(1);
+  const secondName = skills[tui.state.currentSkillIndex()!];
+  expect(secondName).toBe("beta");
+
+  renderer.destroy();
+});
+
+test("search hides groups with no matching skills", async () => {
+  const skills = ["alpha", "beta", "gamma"];
+  const skillRepos = new Map<string, string | null>([
+    ["alpha", "owner/repo-a"],
+    ["beta", "owner/repo-a"],
+    ["gamma", "owner/repo-b"],
+  ]);
+  const ctx = setup({ skills, skillRepos });
+  const { renderer, mockInput, renderOnce, captureCharFrame } =
+    await createTestRenderer({ width: WIDTH, height: HEIGHT });
+
+  createTui(renderer, ctx.makeDepsImmediate());
+  await renderOnce();
+
+  // Search for "gamma" — only repo-b should be visible
+  mockInput.typeText("gamma");
+  await renderOnce();
+
+  const frame = captureCharFrame();
+  expect(frame).toContain("gamma");
+  expect(frame).toContain("owner/repo-b");
+  expect(frame).not.toContain("alpha");
+  expect(frame).not.toContain("beta");
+  // repo-a header should be hidden
+  expect(frame).not.toContain("owner/repo-a");
+
+  renderer.destroy();
+});
+
+test("ungrouped skills appear first with no header", async () => {
+  const skills = ["alpha", "beta", "gamma"];
+  const skillRepos = new Map<string, string | null>([
+    ["alpha", null],
+    ["beta", "owner/repo-a"],
+    ["gamma", null],
+  ]);
+  const ctx = setup({ skills, skillRepos });
+  const { renderer, renderOnce } =
+    await createTestRenderer({ width: WIDTH, height: HEIGHT });
+
+  const tui = createTui(renderer, ctx.makeDepsImmediate());
+  await renderOnce();
+
+  const items = tui.state.displayItems;
+  // Ungrouped first: alpha, gamma (in original order)
+  expect(items[0]).toMatchObject({ type: "skill", name: "alpha" });
+  expect(items[1]).toMatchObject({ type: "skill", name: "gamma" });
+  // Then grouped with header
+  expect(items[2]).toEqual({ type: "header", repo: "owner/repo-a" });
+  expect(items[3]).toMatchObject({ type: "skill", name: "beta" });
+
+  renderer.destroy();
+});
+
+test("groups sorted alphabetically by repo name", async () => {
+  const skills = ["alpha", "beta", "gamma"];
+  const skillRepos = new Map<string, string | null>([
+    ["alpha", "z-org/zebra"],
+    ["beta", "a-org/apple"],
+    ["gamma", "m-org/mango"],
+  ]);
+  const ctx = setup({ skills, skillRepos });
+  const { renderer, renderOnce } =
+    await createTestRenderer({ width: WIDTH, height: HEIGHT });
+
+  const tui = createTui(renderer, ctx.makeDepsImmediate());
+  await renderOnce();
+
+  const headers = tui.state.displayItems
+    .filter((item): item is Extract<typeof item, { type: "header" }> => item.type === "header")
+    .map((h) => h.repo);
+  expect(headers).toEqual(["a-org/apple", "m-org/mango", "z-org/zebra"]);
+
+  renderer.destroy();
+});

package/tui.ts

@@ -14,11 +14,12 @@ export type ColId = "global" | "local";
 
 export type TuiDeps = {
   allSkills: string[];
+  skillRepos: Map<string, string | null>;
   globalInstalled: Set<string>;
   localInstalled: Set<string>;
   catalogPath: string;
-  /** Called when a skill toggle is requested. Return true on success. */
-  onToggle: (col: ColId, name: string, enable: boolean) => Promise<boolean>;
+  /** Called when a skill toggle is requested. Return true on success, false or error string on failure. */
+  onToggle: (col: ColId, name: string, enable: boolean) => Promise<boolean | string>;
   /** Called when a skill delete is requested. */
   onDelete: (name: string) => Promise<void>;
   /** Called when edit is requested. Return false to stay in TUI. */
@@ -27,6 +28,10 @@ export type TuiDeps = {
   onQuit: () => void;
 };
 
+export type DisplayItem =
+  | { type: "skill"; name: string; skillIndex: number }
+  | { type: "header"; repo: string };
+
 export function createTui(renderer: CliRenderer, deps: TuiDeps) {
   const {
     allSkills,
@@ -44,6 +49,42 @@ export function createTui(renderer: CliRenderer, deps: TuiDeps) {
     return `${text.slice(0, max - 1)}\u2026`;
   }
 
+  // ── Build display list ─────────────────────────────────────────────
+
+  const displayItems: DisplayItem[] = [];
+  const skillIndexToDisplayIndex = new Map<number, number>();
+
+  {
+    const ungrouped: number[] = [];
+    const grouped = new Map<string, number[]>();
+
+    for (let i = 0; i < allSkills.length; i++) {
+      const repo = deps.skillRepos.get(allSkills[i]!) ?? null;
+      if (repo === null) {
+        ungrouped.push(i);
+      } else {
+        const list = grouped.get(repo) ?? [];
+        list.push(i);
+        grouped.set(repo, list);
+      }
+    }
+
+    for (const si of ungrouped) {
+      skillIndexToDisplayIndex.set(si, displayItems.length);
+      displayItems.push({ type: "skill", name: allSkills[si]!, skillIndex: si });
+    }
+
+    const sortedRepos = [...grouped.keys()].sort();
+    for (const repo of sortedRepos) {
+      displayItems.push({ type: "header", repo });
+      const skills = grouped.get(repo)!;
+      for (const si of skills) {
+        skillIndexToDisplayIndex.set(si, displayItems.length);
+        displayItems.push({ type: "skill", name: allSkills[si]!, skillIndex: si });
+      }
+    }
+  }
+
   // ── State ───────────────────────────────────────────────────────────
 
   let cursor = 0;
@@ -53,7 +94,9 @@ export function createTui(renderer: CliRenderer, deps: TuiDeps) {
   let pendingDelete: number | null = null;
   const deletedSkills = new Set<number>();
   let searchQuery = "";
-  let filteredIndices: number[] = allSkills.map((_, i) => i);
+  let filteredDisplayIndices: number[] = displayItems
+    .map((item, di) => (item.type === "skill" ? di : -1))
+    .filter((di) => di >= 0);
   const COL_ORDER: ColId[] = ["global", "local"];
 
   const pendingToggles = new Map<string, "adding" | "removing">();
@@ -184,54 +227,89 @@ export function createTui(renderer: CliRenderer, deps: TuiDeps) {
     width: "100%",
   });
 
+  type HeaderRef = { spacer: BoxRenderable | null; row: BoxRenderable; text: TextRenderable };
+  const headerRefs = new Map<number, HeaderRef>();
+
   type RowRefs = {
     row: BoxRenderable;
     nameText: TextRenderable;
     globalText: TextRenderable;
     localText: TextRenderable;
   };
-  const rows: RowRefs[] = [];
+  const rows: RowRefs[] = new Array(allSkills.length);
 
   scrollBox.add(searchRow);
 
-  for (let i = 0; i < allSkills.length; i++) {
-    const skill = allSkills[i]!;
-
-    const row = new BoxRenderable(renderer, {
-      id: `row-${i}`,
-      flexDirection: "row",
-      height: 1,
-      width: "100%",
-      paddingLeft: 1,
-      backgroundColor: i % 2 === 0 ? C.rowBg : C.rowAltBg,
-    });
-
-    const nameText = new TextRenderable(renderer, {
-      id: `name-${i}`,
-      content: `  ${ellipsize(skill, NAME_W - 3)}`,
-      fg: C.fg,
-      width: NAME_W,
-    });
-
-    const globalText = new TextRenderable(renderer, {
-      id: `global-${i}`,
-      content: checkboxStr("global", skill),
-      fg: checkboxColor("global", skill, false),
-      width: COL_W,
-    });
-
-    const localText = new TextRenderable(renderer, {
-      id: `local-${i}`,
-      content: checkboxStr("local", skill),
-      fg: checkboxColor("local", skill, false),
-      width: COL_W,
-    });
-
-    row.add(nameText);
-    row.add(globalText);
-    row.add(localText);
-    scrollBox.add(row);
-    rows.push({ row, nameText, globalText, localText });
+  for (let di = 0; di < displayItems.length; di++) {
+    const item = displayItems[di]!;
+    if (item.type === "header") {
+      let spacer: BoxRenderable | null = null;
+      if (di > 0) {
+        spacer = new BoxRenderable(renderer, {
+          id: `spacer-${di}`,
+          height: 1,
+          width: "100%",
+          backgroundColor: C.rowBg,
+        });
+        scrollBox.add(spacer);
+      }
+      const hRow = new BoxRenderable(renderer, {
+        id: `header-${di}`,
+        flexDirection: "row",
+        height: 1,
+        width: "100%",
+        paddingLeft: 1,
+        backgroundColor: C.rowBg,
+      });
+      const hText = new TextRenderable(renderer, {
+        id: `header-text-${di}`,
+        content: `  ${item.repo}`,
+        fg: C.fgDim,
+        width: NAME_W + COL_W * 2,
+      });
+      hRow.add(hText);
+      scrollBox.add(hRow);
+      headerRefs.set(di, { spacer, row: hRow, text: hText });
+    } else {
+      const i = item.skillIndex;
+      const skill = allSkills[i]!;
+
+      const row = new BoxRenderable(renderer, {
+        id: `row-${i}`,
+        flexDirection: "row",
+        height: 1,
+        width: "100%",
+        paddingLeft: 1,
+        backgroundColor: C.rowBg,
+      });
+
+      const nameText = new TextRenderable(renderer, {
+        id: `name-${i}`,
+        content: `  ${ellipsize(skill, NAME_W - 3)}`,
+        fg: C.fg,
+        width: NAME_W,
+      });
+
+      const globalText = new TextRenderable(renderer, {
+        id: `global-${i}`,
+        content: checkboxStr("global", skill),
+        fg: checkboxColor("global", skill, false),
+        width: COL_W,
+      });
+
+      const localText = new TextRenderable(renderer, {
+        id: `local-${i}`,
+        content: checkboxStr("local", skill),
+        fg: checkboxColor("local", skill, false),
+        width: COL_W,
+      });
+
+      row.add(nameText);
+      row.add(globalText);
+      row.add(localText);
+      scrollBox.add(row);
+      rows[i] = { row, nameText, globalText, localText };
+    }
   }
 
   const footerSep = new TextRenderable(renderer, {
@@ -268,20 +346,40 @@ export function createTui(renderer: CliRenderer, deps: TuiDeps) {
 
   function applyFilter() {
     const term = searchQuery.toLowerCase();
-    filteredIndices = [];
+    filteredDisplayIndices = [];
+
+    const matchingSkills = new Set<number>();
     for (let i = 0; i < allSkills.length; i++) {
-      if (deletedSkills.has(i)) {
-        rows[i]!.row.visible = false;
-        continue;
+      if (deletedSkills.has(i)) continue;
+      if (!term || allSkills[i]!.toLowerCase().includes(term)) {
+        matchingSkills.add(i);
       }
-      const match = !term || allSkills[i]!.toLowerCase().includes(term);
-      rows[i]!.row.visible = match;
-      if (match) filteredIndices.push(i);
     }
-    if (filteredIndices.length === 0) {
+
+    const visibleRepos = new Set<string>();
+    for (const si of matchingSkills) {
+      const repo = deps.skillRepos.get(allSkills[si]!) ?? null;
+      if (repo !== null) visibleRepos.add(repo);
+    }
+
+    for (let di = 0; di < displayItems.length; di++) {
+      const item = displayItems[di]!;
+      if (item.type === "header") {
+        const visible = visibleRepos.has(item.repo);
+        const ref = headerRefs.get(di)!;
+        ref.row.visible = visible;
+        if (ref.spacer) ref.spacer.visible = visible;
+      } else {
+        const visible = matchingSkills.has(item.skillIndex);
+        rows[item.skillIndex]!.row.visible = visible;
+        if (visible) filteredDisplayIndices.push(di);
+      }
+    }
+
+    if (filteredDisplayIndices.length === 0) {
       cursor = 0;
-    } else if (cursor >= filteredIndices.length) {
-      cursor = filteredIndices.length - 1;
+    } else if (cursor >= filteredDisplayIndices.length) {
+      cursor = filteredDisplayIndices.length - 1;
     }
   }
 
@@ -300,7 +398,11 @@ export function createTui(renderer: CliRenderer, deps: TuiDeps) {
   // ── Update display ──────────────────────────────────────────────────
 
   function currentSkillIndex(): number | null {
-    return filteredIndices.length > 0 ? (filteredIndices[cursor] ?? null) : null;
+    if (filteredDisplayIndices.length === 0) return null;
+    const di = filteredDisplayIndices[cursor];
+    if (di === undefined) return null;
+    const item = displayItems[di]!;
+    return item.type === "skill" ? item.skillIndex : null;
   }
 
   function updateRow(i: number) {
@@ -309,7 +411,8 @@ export function createTui(renderer: CliRenderer, deps: TuiDeps) {
     const ci = currentSkillIndex();
     const isCursor = ci === i && focusArea === "grid";
 
-    const visPos = filteredIndices.indexOf(i);
+    const di = skillIndexToDisplayIndex.get(i)!;
+    const visPos = filteredDisplayIndices.indexOf(di);
     const baseBg = visPos % 2 === 0 ? C.rowBg : C.rowAltBg;
     r.row.backgroundColor = isCursor ? C.cursorBg : baseBg;
 
@@ -351,10 +454,16 @@ export function createTui(renderer: CliRenderer, deps: TuiDeps) {
       r.globalText.width = COL_W;
       r.localText.width = COL_W;
     }
+    for (const [, ref] of headerRefs) {
+      ref.text.width = NAME_W + COL_W * 2;
+    }
   }
 
   function refreshAll() {
-    for (const i of filteredIndices) updateRow(i);
+    for (const di of filteredDisplayIndices) {
+      const item = displayItems[di]!;
+      if (item.type === "skill") updateRow(item.skillIndex);
+    }
     updateSearchBar();
   }
 
@@ -366,7 +475,22 @@ export function createTui(renderer: CliRenderer, deps: TuiDeps) {
     if (focusArea === "search") {
       scrollBox.scrollTo(0);
     } else {
-      scrollBox.scrollTo(Math.max(0, cursor + 1 - 2));
+      const targetDi = filteredDisplayIndices[cursor];
+      if (targetDi === undefined) return;
+      let visibleBefore = 0;
+      for (let di = 0; di < targetDi; di++) {
+        const item = displayItems[di]!;
+        if (item.type === "header") {
+          const ref = headerRefs.get(di)!;
+          if (ref.row.visible) {
+            visibleBefore++;
+            if (ref.spacer?.visible) visibleBefore++;
+          }
+        } else {
+          if (rows[item.skillIndex]!.row.visible) visibleBefore++;
+        }
+      }
+      scrollBox.scrollTo(Math.max(0, visibleBefore + 1 - 2));
     }
   }
 
@@ -381,8 +505,8 @@ export function createTui(renderer: CliRenderer, deps: TuiDeps) {
     refreshAll();
 
     try {
-      const ok = await deps.onToggle(col, name, !enabled);
-      if (ok) {
+      const result = await deps.onToggle(col, name, !enabled);
+      if (result === true) {
         const set = col === "global" ? globalInstalled : localInstalled;
         if (enabled) {
           set.delete(name);
@@ -392,7 +516,8 @@ export function createTui(renderer: CliRenderer, deps: TuiDeps) {
           setStatus(`Added ${name}`, C.statusOk);
         }
       } else {
-        setStatus(`Failed to ${enabled ? "remove" : "add"} ${name}`, C.statusErr);
+        const detail = typeof result === "string" ? `: ${result}` : "";
+        setStatus(`Failed to ${enabled ? "remove" : "add"} ${name}${detail}`, C.statusErr);
       }
     } finally {
       pendingToggles.delete(key);
@@ -541,7 +666,7 @@ export function createTui(renderer: CliRenderer, deps: TuiDeps) {
     // ── Navigation & actions ──
     switch (key.name) {
       case "down":
-        if (cursor < filteredIndices.length - 1) cursor++;
+        if (cursor < filteredDisplayIndices.length - 1) cursor++;
         break;
       case "up":
         if (cursor > 0) {
@@ -562,7 +687,7 @@ export function createTui(renderer: CliRenderer, deps: TuiDeps) {
         cursorCol = colNext(cursorCol);
         break;
       case "pagedown":
-        cursor = Math.min(filteredIndices.length - 1, cursor + 10);
+        cursor = Math.min(filteredDisplayIndices.length - 1, cursor + 10);
         break;
       case "pageup":
         cursor = Math.max(0, cursor - 10);
@@ -571,7 +696,7 @@ export function createTui(renderer: CliRenderer, deps: TuiDeps) {
         cursor = 0;
         break;
       case "end":
-        cursor = Math.max(0, filteredIndices.length - 1);
+        cursor = Math.max(0, filteredDisplayIndices.length - 1);
         break;
       case "space":
       case "return": {
@@ -602,7 +727,12 @@ export function createTui(renderer: CliRenderer, deps: TuiDeps) {
         cursorCol,
         focusArea,
         searchQuery,
-        filteredIndices,
+        get filteredIndices() {
+          return filteredDisplayIndices.map(
+            (di) => (displayItems[di] as Extract<DisplayItem, { type: "skill" }>).skillIndex
+          );
+        },
+        displayItems,
         pendingDelete,
         pendingToggles,
         currentSkillIndex,

package/update-check.ts

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const CACHE_PATH = join(homedir(), ".skl", "update-check.json");
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 1 day
+const PKG_NAME = "@dealdeploy/skl";
+
+type Cache = { latest: string; checkedAt: number };
+
+function readCache(): Cache | null {
+  try {
+    return JSON.parse(readFileSync(CACHE_PATH, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(cache: Cache): void {
+  mkdirSync(join(homedir(), ".skl"), { recursive: true });
+  writeFileSync(CACHE_PATH, JSON.stringify(cache));
+}
+
+/**
+ * Check npm for the latest version. Non-blocking — fire and forget.
+ * Returns a message string if an update is available, or null.
+ */
+export async function checkForUpdate(currentVersion: string): Promise<string | null> {
+  const cache = readCache();
+  const now = Date.now();
+
+  // Use cache if fresh
+  if (cache && now - cache.checkedAt < CHECK_INTERVAL_MS) {
+    return compareVersions(currentVersion, cache.latest);
+  }
+
+  // Fetch from registry
+  try {
+    const resp = await fetch(`https://registry.npmjs.org/${PKG_NAME}/latest`, {
+      signal: AbortSignal.timeout(3000),
+    });
+    if (!resp.ok) return null;
+    const data = (await resp.json()) as { version: string };
+    writeCache({ latest: data.version, checkedAt: now });
+    return compareVersions(currentVersion, data.version);
+  } catch {
+    return null;
+  }
+}
+
+function compareVersions(current: string, latest: string): string | null {
+  if (current === latest) return null;
+  const [cMaj, cMin, cPat] = current.split(".").map(Number);
+  const [lMaj, lMin, lPat] = latest.split(".").map(Number);
+  if (lMaj > cMaj || lMin > cMin || lPat > cPat) {
+    return `Update available: ${current} → ${latest}  (run: bun install -g ${PKG_NAME})`;
+  }
+  return null;
+}