skillshelf 0.3.0 → 0.4.1

package/README.md

@@ -7,22 +7,42 @@
 [![CI](https://img.shields.io/github/actions/workflow/status/Wang-Cankun/skillshelf/ci.yml?branch=main)](https://github.com/Wang-Cankun/skillshelf/actions)
 [![npm](https://img.shields.io/npm/v/skillshelf.svg)](https://www.npmjs.com/package/skillshelf)
 
-Your skills are scattered across **every agent you use** — some in `~/.claude/skills`, some in
-`~/.codex/skills` or `~/.cursor/skills`, some buried in Obsidian or notes vaults, more copied into
-a dozen per-project `.claude` / `.codex` directories. Each tool scatters its own copies and
-symlinks; you forget which ones exist, rewrite ones you already have, and copies drift out of sync.
-The naive fix — dump everything into one agent's dir — makes every session pay the token cost of
-loading hundreds of skill descriptions at once.
-
-skillshelf is **agent-agnostic** (Claude Code, Codex, Cursor, and compatible agents): the library
-is a neutral source, and `skl where` maps where every skill is actually deployed across all of
-them — surfacing untracked copies, drift, and dead links. It's the curation layer *over* your
-agent dirs, complementary to installers like [`vercel-labs/skills`](https://github.com/vercel-labs/skills).
-
-skillshelf is the middle path: a single git-backed **library** that is a *passive shelf*
-(nothing auto-loads), plus a CLI to **search, tag, bundle, and load** exactly the skills a
-project needs, exactly when it needs them. Find anything in one place; pay only for what you
-actually use.
+Your skills are scattered across **every agent you use** — `~/.claude/skills`, `~/.codex/skills`,
+`~/.cursor/skills`, Obsidian vaults, and a dozen per-project `.claude` dirs. Copies drift, you
+rewrite skills you already have, and you forget which exist. The naive fix — dump everything into
+one agent's dir — makes every session pay to load hundreds of skill descriptions at once.
+
+skillshelf is the middle path: one git-backed **library** that is a *passive shelf* (nothing
+auto-loads), plus a CLI to **search, tag, bundle, and load** exactly the skills a project needs,
+when it needs them. It's **agent-agnostic** (Claude Code, Codex, Cursor, …) — `skl where` maps
+where every skill is actually deployed across all of them, surfacing untracked copies, drift, and
+dead links. Find anything in one place; pay only for what you use. (Complementary to installers
+like [`vercel-labs/skills`](https://github.com/vercel-labs/skills).)
+
+## Desktop app
+
+A cross-platform desktop UI (React + Tauri) sits on top of the same engine — a **Library-first**
+workbench for managing where every skill is deployed across your agents. It reads the **real**
+`skl` library (no separate data store) and every toggle writes the same symlinks the CLI does.
+
+![skillshelf — Library view](docs/images/main.png)
+
+- **Library-first, skill-centric list** — scan all skills, flip them on/off per agent inline; a
+  top **scope switcher** (Global · each project · + Add project) and a per-scope count bar.
+- **Project scopes** — manage a project's loadout without leaving the app; globally-deployed
+  skills show an *"active via Global"* inherited state so you always know what's effectively live.
+- **Two-tier toggles** — a clean on/off for the happy path, but drift / copy / dead / aliased
+  surface a resolve flow instead of silently doing the wrong thing (state is derived from the
+  filesystem, never stored — so the UI can't lie about what's deployed).
+
+![skillshelf — skill detail drawer](docs/images/detail.png)
+
+The detail drawer shows a skill's body, tags, provenance, and an `agent × scope` deployment
+matrix (Global + the projects where it's pinned), plus lifecycle actions.
+
+> Browser/dev mode (`cd app && bun run dev`) renders synthetic fixtures with no backend; the
+> packaged desktop app talks to your real `skl` engine. See [`docs/adr/0010-*`](docs/adr/) for the
+> design.
 
 ## Install
 
@@ -85,7 +105,7 @@ skl scan                       # report every candidate + duplicate/drift group
 # 2. Adopt the ones you want, one at a time. Each import moves the skill into the
 #    library and leaves a symlink behind so old paths keep resolving.
 skl import rnaseq-qc --from ~/.claude/skills/rnaseq-qc
-skl import xhs-title --from ~/notes/.agents/skills/xhs-title
+skl import headline-picker --from ~/notes/.agents/skills/headline-picker
 
 #    For a skill living inside a project repo, copy instead of move (no symlink left behind):
 skl import deploy-check --from ~/projects/web/.claude/skills/deploy-check --copy
@@ -95,7 +115,7 @@ skl import rnaseq-qc --from ~/projects/lab/.claude/skills/rnaseq-qc --force
 
 #    For a skill you actively develop in its own git repo, shelve a LINK instead of a copy —
 #    the repo stays canonical and edits show up live, no drift, no re-sync (ADR-0004):
-skl link --from ~/Documents/GitHub/cairn/skill/cairn
+skl link --from ~/Documents/GitHub/claim-log/skill/claim-log
 
 # 3. Tag the now-populated library in one pass. Domain is tags, not folders, so this
 #    runs AFTER import with no reorg — no skill ever has to move because a tag changed.
@@ -123,27 +143,32 @@ skillshelf separates *owning* a skill from *loading* it.
 - **On-demand `show`** — prints only the SKILL.md instruction body and lists the paths of
   any bundled reference files (without reading them). Progressive disclosure: cheap by
   default, deep when you ask. Works mid-task with no reload.
-- **Owned vs linked entries** ([ADR-0004](./docs/adr/0004-owned-vs-linked-entries.md)) — the
-  library is a *bookshelf*: an entry either **owns** its bytes (a real copy; the library is
-  canonical — for downloads and stabilized skills) or is **linked** (a symlink to an external dev
-  repo that stays canonical — for skills you actively develop in their own git, e.g. `cairn`).
-  `skl link --from <dev-repo>` registers a linked entry; `skl where` shows it as a clean
-  `✓ source`; `skl update` / `outdated` skip linked entries so they never pull upstream into your
-  dev repo. The mode is derived from the filesystem (a symlink resolving outside the library),
-  never stored, so it can't go stale.
+- **Owned vs linked entries** ([ADR-0004](./docs/adr/0004-owned-vs-linked-entries.md)) — an entry
+  either **owns** its bytes (a real copy — for downloads and stabilized skills) or is **linked**
+  (`skl link --from <dev-repo>` — a symlink to an external repo that stays canonical, for skills you
+  develop in their own git). `update` / `outdated` skip linked entries so they never push upstream
+  into your dev repo. The mode is derived from the filesystem, never stored, so it can't go stale.
 - **Updates never clobber your tags** — domain tags live in the central `taxonomy.json`
   ([ADR-0002](./docs/adr/0002-central-taxonomy-not-sidecars.md)), separate from the skill body, so
   `skl update` can swap an owned skill's upstream `SKILL.md` cleanly while your taxonomy survives.
 
-```
-                       skl search / ls / show          skl use <bundle>
-                                │                              │
-   ┌──────────────────────┐    │   ┌──────────────────────┐   │   ┌─────────────────────┐
-   │   canonical library  │────┴──▶│   bundles = tag query │───┴──▶│  project .claude/   │
-   │  (passive git shelf) │        │  bioinfo · coding · … │       │  skills/ (symlinks) │
-   └──────────┬───────────┘        └──────────────────────┘       └─────────────────────┘
-              │
-              └──── thin global core ──▶ ~/.claude/skills  (always-on, bounded)
+```mermaid
+flowchart LR
+    L["📚 Canonical library<br/><i>passive git shelf</i>"]
+    B["🏷️ Bundles<br/><i>tag query — bioinfo · coding · …</i>"]
+    P["📁 Project .claude/skills/<br/><i>symlinks, on demand</i>"]
+    G["⚡ ~/.claude/skills<br/><i>thin global core, always-on</i>"]
+
+    L -- "skl use bundle" --> B
+    B -- symlink --> P
+    L -- "thin global core" --> G
+
+    search(["skl search · ls · show"]) -. reads .-> L
+
+    classDef shelf fill:#1f2937,stroke:#4b5563,color:#e5e7eb;
+    classDef live fill:#064e3b,stroke:#10b981,color:#d1fae5;
+    class L,B shelf;
+    class P,G live;
 ```
 
 See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for the full design.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillshelf",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Agent-first skill registry + manager for Claude Code and compatible agents.",
   "type": "module",
   "license": "MIT",

package/src/cli.ts

@@ -29,8 +29,12 @@ import * as infer from "./commands/infer.ts";
 import * as newCmd from "./commands/new.ts";
 import * as scan from "./commands/scan.ts";
 import * as roots from "./commands/roots.ts";
+import * as projects from "./commands/projects.ts";
 import * as importCmd from "./commands/import.ts";
 import * as link from "./commands/link.ts";
+import * as track from "./commands/track.ts";
+import * as untrack from "./commands/untrack.ts";
+import * as migrate from "./commands/migrate.ts";
 import * as where from "./commands/where.ts";
 import * as agents from "./commands/agents.ts";
 import * as tag from "./commands/tag.ts";
@@ -56,8 +60,12 @@ const MODULES: CommandModule[] = [
   add,
   scan,
   roots,
+  projects,
   importCmd,
   link,
+  track,
+  untrack,
+  migrate,
   tag,
   untag,
   retag,

package/src/commands/add.test.ts

@@ -0,0 +1,118 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run } from "./add.ts";
+import type { Ctx } from "../types.ts";
+
+interface Captured {
+  ctx: Ctx;
+  logs: string[];
+  errors: string[];
+  json: unknown[];
+}
+
+/** Minimal Ctx mock — add.run reads config.libraryPath + log/error/json. */
+function makeCtx(libraryPath: string): Captured {
+  const logs: string[] = [];
+  const errors: string[] = [];
+  const json: unknown[] = [];
+  const ctx = {
+    config: { libraryPath },
+    libraryPath,
+    log: (...a: unknown[]) => logs.push(a.join(" ")),
+    error: (...a: unknown[]) => errors.push(a.join(" ")),
+    json: (v: unknown) => json.push(v),
+  } as unknown as Ctx;
+  return { ctx, logs, errors, json };
+}
+
+function skillBody(name: string): string {
+  return `---\nname: ${name}\ndescription: a ${name} skill for testing\n---\n\n# ${name}\n\nbody for ${name}\n`;
+}
+
+/** Build a real local git repo holding the given skills, for offline `git:` add. */
+async function makeGitRepo(parent: string, skills: string[]): Promise<string> {
+  const repo = join(parent, "src-repo");
+  await mkdir(repo, { recursive: true });
+  for (const s of skills) {
+    await mkdir(join(repo, s), { recursive: true });
+    await writeFile(join(repo, s, "SKILL.md"), skillBody(s));
+  }
+  const run = (cmd: string[]) =>
+    Bun.spawn(cmd, { cwd: repo, stdout: "ignore", stderr: "ignore" }).exited;
+  await run(["git", "init", "-q"]);
+  await run(["git", "config", "user.email", "test@example.com"]);
+  await run(["git", "config", "user.name", "test"]);
+  await run(["git", "add", "-A"]);
+  await run(["git", "commit", "-q", "-m", "init"]);
+  return repo;
+}
+
+describe("skl add — retired-aware collision", () => {
+  let tmp: string;
+  let library: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-add-")));
+    library = join(tmp, "library");
+    await mkdir(library, { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("--all over a repo where one name is retired: skips it (no duplicate), installs the rest", async () => {
+    const repo = await makeGitRepo(tmp, ["caveman", "tdd"]);
+    // Retire "caveman": a tombstone under _retired/, NO active copy.
+    await mkdir(join(library, "_retired", "caveman"), { recursive: true });
+    await writeFile(join(library, "_retired", "caveman", "SKILL.md"), skillBody("caveman"));
+
+    const { ctx, json } = makeCtx(library);
+    const code = await run([`git:${repo}`, "--all", "--no-infer", "--json"], ctx);
+    expect(code).toBe(0);
+
+    const out = json[0] as {
+      results: Array<{ name: string; status: string; verdict: string; reason: string }>;
+    };
+    const caveman = out.results.find((r) => r.name === "caveman")!;
+    const tdd = out.results.find((r) => r.name === "tdd")!;
+
+    expect(caveman.status).toBe("skipped");
+    expect(caveman.verdict).toBe("retired");
+    expect(caveman.reason).toContain("skl unretire caveman");
+
+    // No active duplicate beside the tombstone.
+    expect(existsSync(join(library, "caveman"))).toBe(false);
+    expect(existsSync(join(library, "_retired", "caveman"))).toBe(true);
+
+    // The non-colliding name still installs.
+    expect(tdd.status).toBe("installed");
+    expect(existsSync(join(library, "tdd", "SKILL.md"))).toBe(true);
+  });
+
+  test("single add of a retired name refuses (exit 1, no duplicate)", async () => {
+    const repo = await makeGitRepo(tmp, ["caveman"]);
+    await mkdir(join(library, "_retired", "caveman"), { recursive: true });
+    await writeFile(join(library, "_retired", "caveman", "SKILL.md"), skillBody("caveman"));
+
+    const { ctx, errors } = makeCtx(library);
+    const code = await run([`git:${repo}`, "--no-infer"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("skl unretire caveman");
+    expect(existsSync(join(library, "caveman"))).toBe(false);
+  });
+
+  test("active-collision still refuses without --force (no regression)", async () => {
+    const repo = await makeGitRepo(tmp, ["tdd"]);
+    // An ACTIVE copy already exists.
+    await mkdir(join(library, "tdd"), { recursive: true });
+    await writeFile(join(library, "tdd", "SKILL.md"), skillBody("tdd") + "local edit\n");
+
+    const { ctx, errors } = makeCtx(library);
+    const code = await run([`git:${repo}`, "--no-infer"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("already exists");
+  });
+});

package/src/commands/add.ts

@@ -38,7 +38,7 @@ import { hashContent } from "../core/crawl.ts";
 import { recordEntry } from "../core/provenance.ts";
 import { setDomainsForName } from "../core/taxonomy.ts";
 import { assertSafeName } from "../core/lifecycle.ts";
-import { loadLibrary, findByName } from "../core/library.ts";
+import { loadLibrary, findByName, entryStatus } from "../core/library.ts";
 import { ensureDir, isSymlink, realpathOrSelf } from "../lib/fs.ts";
 
 export const meta = {
@@ -217,7 +217,7 @@ interface InstallOptions {
 interface InstallOutcome {
   name: string;
   subpath: string;
-  verdict: Verdict | "duplicate";
+  verdict: Verdict | "duplicate" | "retired";
   status: "installed" | "skipped" | "error";
   reason: string;
   path: string;
@@ -268,6 +268,21 @@ async function installOne(
     return { ...base, reason: err instanceof Error ? err.message : String(err) };
   }
 
+  // Retired-aware collision guard: if this name exists ONLY as a retired tombstone
+  // (<library>/_retired/<name>), do NOT install a fresh active copy beside it — that
+  // strands a duplicate and breaks `skl unretire`. The user must unretire first. This
+  // fires regardless of --force (force overwrites an ACTIVE copy, not a retired one).
+  // Checked against the flat library root (retirement is never under a domain folder).
+  const status = entryStatus(opts.libraryPath, rawName);
+  if (status.retired && !status.active) {
+    return {
+      ...base,
+      verdict: "retired",
+      status: "skipped",
+      reason: `a retired '${rawName}' exists — run \`skl unretire ${rawName}\` first`,
+    };
+  }
+
   const destDir = destDirFor(opts.libraryPath, opts.domainFolder, rawName);
   const verdict = await driftVerdict(skill, destDir);
   base.verdict = verdict;
@@ -608,6 +623,12 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         ctx.error("add:", o.reason);
         return 1;
       }
+      // A retired-name collision is a refusal in single mode (no duplicate written):
+      // surface it as an error + non-zero exit, pointing the user at `skl unretire`.
+      if (o.status === "skipped") {
+        ctx.error("add:", o.reason);
+        return 1;
+      }
       // Legacy single-skill summary shape (unchanged for existing consumers).
       const summary = {
         ok: true,

package/src/commands/adopted.test.ts

@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, readFile, rm, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run as outdatedRun } from "./outdated.ts";
+import { run as updateRun } from "./update.ts";
+import { readLockfile, recordEntry } from "../core/provenance.ts";
+import type { Ctx, LockEntry } from "../types.ts";
+
+function makeCtx(libraryPath: string) {
+  const logs: string[] = [];
+  const errors: string[] = [];
+  const json: unknown[] = [];
+  const ctx = {
+    config: { libraryPath },
+    libraryPath,
+    log: (...a: unknown[]) => logs.push(a.join(" ")),
+    error: (...a: unknown[]) => errors.push(a.join(" ")),
+    json: (v: unknown) => json.push(v),
+  } as unknown as Ctx;
+  return { ctx, logs, errors, json };
+}
+
+/** Build a tiny on-disk git repo to act as a `git:` upstream for one skill. */
+async function makeGitUpstream(dir: string, name: string, body: string): Promise<void> {
+  await mkdir(join(dir, name), { recursive: true });
+  await writeFile(join(dir, name, "SKILL.md"), `---\nname: ${name}\ndescription: d\n---\n\n${body}\n`);
+  const git = (args: string[]) => Bun.spawnSync(["git", "-C", dir, ...args], { stdout: "ignore", stderr: "ignore" });
+  git(["init", "-q"]);
+  git(["config", "user.email", "t@t.t"]);
+  git(["config", "user.name", "t"]);
+  git(["add", "-A"]);
+  git(["commit", "-q", "-m", "init"]);
+}
+
+describe("adopted entries — outdated reports 'adopted', not stale", () => {
+  let tmp: string;
+  let library: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-adopted-outdated-")));
+    library = join(tmp, "library");
+    await mkdir(join(library, "foo"), { recursive: true });
+    await writeFile(join(library, "foo", "SKILL.md"), "---\nname: foo\ndescription: d\n---\n\nbody\n");
+    const entry: LockEntry = {
+      name: "foo",
+      source: "github:owner/repo",
+      ref: "",
+      channel: "github",
+      installedAt: "2024-01-01T00:00:00.000Z",
+      localEdits: false,
+      installedHash: "abc",
+      adopted: true,
+    };
+    await recordEntry(library, entry);
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("status is 'adopted' and never counted stale (no upstream probe)", async () => {
+    const { ctx, json } = makeCtx(library);
+    const code = await outdatedRun(["--json"], ctx);
+    expect(code).toBe(0); // not stale -> exit 0, no network probe of the empty ref
+    const report = json[0] as { stale: number; rows: Array<{ name: string; status: string; note: string }> };
+    expect(report.stale).toBe(0);
+    const row = report.rows.find((r) => r.name === "foo")!;
+    expect(row.status).toBe("adopted");
+    expect(row.note).toContain("baseline unverified");
+  });
+});
+
+describe("adopted entries — update is conservative and graduates", () => {
+  let tmp: string;
+  let library: string;
+  let upstream: string;
+
+  async function seedAdopted(libBody: string, upstreamBody: string): Promise<void> {
+    await mkdir(join(library, "foo"), { recursive: true });
+    await writeFile(join(library, "foo", "SKILL.md"), `---\nname: foo\ndescription: d\n---\n\n${libBody}\n`);
+    upstream = join(tmp, "upstream");
+    await makeGitUpstream(upstream, "foo", upstreamBody);
+    const entry: LockEntry = {
+      name: "foo",
+      source: `git:${upstream}#foo`,
+      ref: "",
+      channel: "git",
+      installedAt: "2024-01-01T00:00:00.000Z",
+      localEdits: false,
+      installedHash: "unverified-baseline-hash",
+      adopted: true,
+    };
+    await recordEntry(library, entry);
+  }
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-adopted-update-")));
+    library = join(tmp, "library");
+    await mkdir(library, { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("differing body: requires --force, shows diff, does not clobber", async () => {
+    await seedAdopted("LOCAL BODY", "UPSTREAM BODY");
+    const { ctx, json } = makeCtx(library);
+    const code = await updateRun(["foo", "--json"], ctx);
+    // diverged -> exit 2
+    expect(code).toBe(2);
+    const report = json[0] as { results: Array<{ name: string; outcome: string }> };
+    expect(report.results.find((r) => r.name === "foo")!.outcome).toBe("diverged");
+    // local body untouched
+    const body = await readFile(join(library, "foo", "SKILL.md"), "utf8");
+    expect(body).toContain("LOCAL BODY");
+    // still adopted (not graduated)
+    expect((await readLockfile(library)).entries.foo!.adopted).toBe(true);
+  });
+
+  test("differing body with --force: overwrites and graduates (adopted cleared)", async () => {
+    await seedAdopted("LOCAL BODY", "UPSTREAM BODY");
+    const { ctx } = makeCtx(library);
+    const code = await updateRun(["foo", "--force"], ctx);
+    expect(code).toBe(0);
+    const body = await readFile(join(library, "foo", "SKILL.md"), "utf8");
+    expect(body).toContain("UPSTREAM BODY");
+    const e = (await readLockfile(library)).entries.foo!;
+    expect(e.adopted).toBe(false); // graduated
+    expect(e.ref).not.toBe(""); // real commit pinned
+    expect(e.localEdits).toBe(false);
+  });
+
+  test("identical body: graduates without --force (lossless)", async () => {
+    await seedAdopted("SAME BODY", "SAME BODY");
+    const { ctx } = makeCtx(library);
+    const code = await updateRun(["foo"], ctx);
+    expect(code).toBe(0);
+    const e = (await readLockfile(library)).entries.foo!;
+    expect(e.adopted).toBe(false); // graduated
+    expect(e.ref).not.toBe("");
+    // installedHash now reflects the verified upstream body.
+    expect(e.installedHash).not.toBe("unverified-baseline-hash");
+  });
+});

package/src/commands/agents-config.test.ts

@@ -0,0 +1,126 @@
+// `skl agents add|rm` write verbs (ADR-0010 delta 4). Drives the real ctx through
+// an isolated SKILLSHELF_CONFIG so the GUI round-trip is pinned: a registered
+// custom agent persists, reads back tagged `custom:true` in `agents --json` (the
+// flag loadConfig() filters on), and `rm` removes it. This is the round-trip the
+// review flagged as a non-persisting stub.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadContext } from "../config.ts";
+import { run as agentsRun } from "./agents.ts";
+import type { AgentsReport } from "../core/agents.ts";
+import type { Ctx } from "../types.ts";
+
+describe("skl agents add|rm write verbs (ADR-0010 delta 4)", () => {
+  let tmp: string;
+  let cfg: string;
+  let library: string;
+
+  async function makeCtx(): Promise<{ ctx: Ctx; json: unknown[] }> {
+    const json: unknown[] = [];
+    const ctx = await loadContext({
+      env: {
+        SKILLSHELF_CONFIG: cfg,
+        SKILLSHELF_LIBRARY: library,
+        SKILLSHELF_GLOBAL_CORE: join(tmp, ".no-global-core"),
+      } as NodeJS.ProcessEnv,
+    });
+    ctx.json = (v: unknown) => json.push(v);
+    ctx.log = () => {};
+    ctx.error = () => {};
+    return { ctx, json };
+  }
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), "skl-agents-config-"));
+    cfg = join(tmp, "config.json");
+    library = join(tmp, "library");
+    await mkdir(library, { recursive: true });
+    await writeFile(
+      join(library, "config.json"),
+      "", // placeholder so library dir is non-empty; real skills not needed here
+    );
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("add persists a custom agent and reports the updated list", async () => {
+    const { ctx, json } = await makeCtx();
+    const code = await agentsRun(
+      [
+        "add",
+        "cursor",
+        "--name",
+        "Cursor",
+        "--global",
+        "~/.cursor/skills",
+        "--proj-convention",
+        ".cursor/skills",
+        "--icon",
+        "cursor",
+        "--json",
+      ],
+      ctx,
+    );
+    expect(code).toBe(0);
+    const out = json[0] as { agents: Array<{ id: string; icon?: string }>; added: boolean };
+    expect(out.added).toBe(true);
+    expect(out.agents.map((a) => a.id)).toContain("cursor");
+    expect(out.agents.find((a) => a.id === "cursor")?.icon).toBe("cursor");
+  });
+
+  test("a persisted custom agent reads back tagged custom:true in agents --json", async () => {
+    const { ctx } = await makeCtx();
+    await agentsRun(
+      ["add", "cursor", "--name", "Cursor", "--global", "~/.cursor/skills", "--proj-convention", ".cursor/skills"],
+      ctx,
+    );
+
+    // fresh ctx reads config from disk
+    const { ctx: ctx2, json } = await makeCtx();
+    await agentsRun(["--json"], ctx2);
+    const report = json[0] as AgentsReport;
+    const cursor = report.agents.find((a) => a.id === "cursor");
+    expect(cursor).toBeDefined();
+    expect(cursor!.custom).toBe(true);
+    // built-in seeds are NOT tagged custom (loadConfig must not pick them up).
+    const claude = report.agents.find((a) => a.id === "claude");
+    expect(claude?.custom).toBeUndefined();
+  });
+
+  test("rm removes a persisted custom agent", async () => {
+    const { ctx } = await makeCtx();
+    await agentsRun(
+      ["add", "cursor", "--name", "Cursor", "--global", "~/.cursor/skills", "--proj-convention", ".cursor/skills"],
+      ctx,
+    );
+
+    const { ctx: ctx2, json } = await makeCtx();
+    const code = await agentsRun(["rm", "cursor", "--json"], ctx2);
+    expect(code).toBe(0);
+    const out = json[0] as { agents: unknown[]; removed: boolean };
+    expect(out.removed).toBe(true);
+    expect(out.agents).toEqual([]);
+  });
+
+  test("rm on a non-registered id reports removed:false", async () => {
+    const { ctx, json } = await makeCtx();
+    const code = await agentsRun(["rm", "nope", "--json"], ctx);
+    expect(code).toBe(0);
+    expect(json[0]).toEqual({ agents: [], removed: false });
+  });
+
+  test("add without required path flags errors", async () => {
+    const { ctx } = await makeCtx();
+    expect(await agentsRun(["add", "cursor", "--name", "Cursor"], ctx)).toBe(1);
+  });
+
+  test("add/rm without an id errors", async () => {
+    const { ctx } = await makeCtx();
+    expect(await agentsRun(["add"], ctx)).toBe(1);
+    expect(await agentsRun(["rm"], ctx)).toBe(1);
+  });
+});