skillshelf 0.3.0 → 0.4.0

package/README.md

@@ -24,6 +24,31 @@ skillshelf is the middle path: a single git-backed **library** that is a *passiv
 project needs, exactly when it needs them. Find anything in one place; pay only for what you
 actually use.
 
+## 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
 
 skillshelf runs on [Bun](https://bun.sh) (>= 1.0). No other runtime dependencies.
@@ -85,7 +110,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 +120,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.
@@ -126,7 +151,7 @@ skillshelf separates *owning* a skill from *loading* it.
 - **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`).
+  repo that stays canonical — for skills you actively develop in their own git, e.g. `claim-log`).
   `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),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillshelf",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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/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);
+  });
+});

package/src/commands/agents.test.ts

@@ -0,0 +1,96 @@
+// `skl agents --json` end-to-end with ADR-0010 config: a persisted-but-empty
+// project must surface as a scope (no phantom deployments), a custom agent must
+// appear in the matrix, and a real deploy into a config-project must be inventoried.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run as agentsRun } from "./agents.ts";
+import { run as useRun } from "./use.ts";
+import { loadLibrary } from "../core/library.ts";
+import type { AgentsReport } from "../core/agents.ts";
+import type { Config, Ctx } from "../types.ts";
+
+async function writeSkill(library: string, name: string) {
+  const dir = join(library, name);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, "SKILL.md"), `---\nname: ${name}\ndescription: ${name}\ndomains: [bio]\n---\n\nbody\n`);
+}
+
+describe("skl agents --json — config projects + agents (ADR-0010)", () => {
+  let tmp: string;
+  let library: string;
+
+  function makeCtx(config: Partial<Config>): { ctx: Ctx; json: unknown[] } {
+    const json: unknown[] = [];
+    const full: Config = {
+      libraryPath: library,
+      globalCoreTarget: join(tmp, ".no-global-core"),
+      roots: [],
+      agents: [],
+      projects: [],
+      configFile: null,
+      configFilePath: join(tmp, "config.json"),
+      source: "default",
+      ...config,
+    };
+    const ctx = {
+      config: full,
+      libraryPath: library,
+      roots: full.roots,
+      loadLibrary: () => loadLibrary(library),
+      log: () => {},
+      error: () => {},
+      json: (v: unknown) => json.push(v),
+    } as unknown as Ctx;
+    return { ctx, json };
+  }
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-agents-cmd-")));
+    library = join(tmp, "library");
+    await writeSkill(library, "alpha");
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("an empty config-project appears as a scope with no phantom deployments", async () => {
+    const empty = join(tmp, "scratch");
+    await mkdir(empty, { recursive: true });
+    const { ctx, json } = makeCtx({ projects: [empty] });
+    const code = await agentsRun(["--json"], ctx);
+    expect(code).toBe(0);
+    const report = json[0] as AgentsReport;
+    expect(report.scopes).toContain("scratch");
+    // empty project = NO fabricated cell. (The matrix may contain real machine
+    // global deployments; the invariant is that nothing is keyed to `scratch`.)
+    for (const byAgent of Object.values(report.deployments)) {
+      for (const dep of Object.values(byAgent)) {
+        expect(dep.p?.scratch).toBeUndefined();
+      }
+    }
+  });
+
+  test("a custom config-agent appears in the agents list", async () => {
+    const { ctx, json } = makeCtx({ agents: [{ id: "pi", name: "PI Agent", short: "PI" }] });
+    await agentsRun(["--json"], ctx);
+    const report = json[0] as AgentsReport;
+    expect(report.agents.map((a) => a.id)).toContain("pi");
+  });
+
+  test("a real deploy into a config-project is inventoried in the matrix", async () => {
+    const proj = join(tmp, "webapp");
+    await mkdir(proj, { recursive: true });
+    // deploy alpha into the config project for claude
+    const { ctx: useCtx } = makeCtx({ projects: [proj] });
+    await useRun(["alpha", "--agent", "claude", "--project", proj, "--json"], useCtx);
+
+    const { ctx, json } = makeCtx({ projects: [proj] });
+    await agentsRun(["--json"], ctx);
+    const report = json[0] as AgentsReport;
+    expect(report.scopes).toContain("webapp");
+    expect(report.deployments.alpha!.claude!.p!.webapp).toBe("clean");
+  });
+});

package/src/commands/agents.ts

@@ -6,10 +6,16 @@
 //   skl agents --json        full AgentsReport { agents, scopes, deployments }
 //   skl agents <name>        one skill's row across agents × scopes
 
-import type { Ctx } from "../types.ts";
+import { basename, join, sep } from "node:path";
+import type { AgentConfigEntry, Ctx } from "../types.ts";
 import { inventoryDeployments } from "../core/deployments.ts";
 import { knownAgentSurfacePaths } from "../core/surfaces.ts";
-import { computeAgentsReport, resolveReadTarget, type DeployState } from "../core/agents.ts";
+import {
+  computeAgentsReport,
+  knownAgentIds,
+  resolveReadTarget,
+  type DeployState,
+} from "../core/agents.ts";
 
 export const meta = {
   name: "agents",
@@ -28,7 +34,24 @@ const GLYPH: Record<DeployState, string> = {
 
 const LEGEND = "legend: ✓ clean · ⊙ source · ⚠ drift · □ copy · ✗ dead · · absent";
 
+/**
+ * Scope name for a persisted project dir = its basename — matching the engine's
+ * scope derivation (parseDeployTarget / scopeForSurface use the last path segment),
+ * so a config project reconciles with the FS-derived scopes in the matrix.
+ */
+function projectScopeName(projectPath: string): string {
+  return projectPath.split(sep).filter(Boolean).pop() || basename(projectPath) || projectPath;
+}
+
 export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  // ── Config write subverbs (ADR-0010 delta 4): `skl agents add|rm` mutate the
+  //    custom-agent registry in config.json. These are registry metadata only —
+  //    they never deploy; the matrix stays FS-derived. Checked BEFORE the read
+  //    path so `add`/`rm` are never mistaken for a skill name. (`add`/`rm` are
+  //    reserved subverbs; a skill literally named "add"/"rm" is not a concern.)
+  if (argv[0] === "add" || argv[0] === "rm") {
+    return runConfigSubverb(argv, ctx);
+  }
   try {
     const rt = resolveReadTarget(argv);
     if ("error" in rt) {
@@ -40,11 +63,35 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     const name = rt.rest.find((a) => !a.startsWith("--")) ?? null;
 
     const lib = await ctx.loadLibrary();
-    // Same surface union as `skl where` (+ any --project surfaces for this call) so
-    // the agent matrix sees the same reality and can verify an ad-hoc project deploy.
-    const surfaces = [...ctx.roots, ctx.config.globalCoreTarget, ...knownAgentSurfacePaths(), ...rt.extraSurfaces];
+    // Effective agent ids = built-in seeds + custom config agents (so a custom
+    // agent's project/global skills dirs are scanned for inventory).
+    const agentIds = new Set<string>(knownAgentIds());
+    for (const a of ctx.config.agents) {
+      if (a && typeof a.id === "string" && a.id.trim() !== "") agentIds.add(a.id);
+    }
+    // Config-project surfaces (ADR-0010 §5a): scan each persisted project dir for
+    // every effective agent so a deployed config-project is inventoried.
+    const projectSurfaces: string[] = [];
+    for (const proj of ctx.config.projects) {
+      for (const id of agentIds) projectSurfaces.push(join(proj, `.${id}`, "skills"));
+    }
+    // Same surface union as `skl where` (+ any --project surfaces for this call,
+    // + persisted config-project surfaces) so the agent matrix sees the same
+    // reality and can verify an ad-hoc OR persisted project deploy.
+    const surfaces = [
+      ...ctx.roots,
+      ctx.config.globalCoreTarget,
+      ...knownAgentSurfacePaths(),
+      ...projectSurfaces,
+      ...rt.extraSurfaces,
+    ];
     const report = await inventoryDeployments(surfaces, ctx.libraryPath, lib);
-    let agentsReport = computeAgentsReport(report);
+    // Empty persisted projects still appear as scope rows (basename = scope name);
+    // custom agents merge into the matrix. Deployments stay FS-derived.
+    let agentsReport = computeAgentsReport(report, undefined, {
+      agents: ctx.config.agents,
+      extraScopes: ctx.config.projects.map((p) => projectScopeName(p)),
+    });
 
     // --agent <id> focuses the whole report on that agent: prune the agents list
     // and the deployments map to just that agent (skills not deployed to it drop).
@@ -118,3 +165,79 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     return 1;
   }
 }
+
+/** Read a `--flag value` option out of argv (returns undefined if absent). */
+function flag(argv: string[], name: string): string | undefined {
+  const i = argv.indexOf(name);
+  if (i < 0) return undefined;
+  const v = argv[i + 1];
+  return v && !v.startsWith("--") ? v : undefined;
+}
+
+/**
+ * `skl agents add <id> --name <n> --global <dir> --proj-convention <c> [--icon k]
+ *  [--color #rgb]` and `skl agents rm <id>` — persist the custom-agent registry
+ * (ADR-0010 delta 4). With `--json` emits `{ agents }` / `{ agents, removed }`
+ * (the full custom-agent list) so the GUI can round-trip without a separate read.
+ */
+async function runConfigSubverb(argv: string[], ctx: Ctx): Promise<number> {
+  const verb = argv[0];
+  const json = argv.includes("--json");
+  const id = argv[1] && !argv[1].startsWith("--") ? argv[1].trim() : "";
+
+  if (!id) {
+    ctx.error(`skl agents ${verb}: requires an agent id`);
+    ctx.error("usage: skl agents add <id> --name <name> --global <dir> --proj-convention <conv> [--icon <key>] [--color <hex>]");
+    return 1;
+  }
+
+  if (verb === "rm") {
+    const { agents, removed } = await ctx.removeAgent(id);
+    if (json) {
+      ctx.json({ agents, removed });
+      return 0;
+    }
+    ctx.log(removed ? `Removed custom agent "${id}".` : `No custom agent "${id}" (nothing removed).`);
+    return 0;
+  }
+
+  // add
+  const name = flag(argv, "--name") ?? id;
+  const global = flag(argv, "--global");
+  const projConvention = flag(argv, "--proj-convention");
+  const icon = flag(argv, "--icon");
+  const color = flag(argv, "--color");
+  // `--hidden` persists a hide override (ADR-0010 delta 4 / RISK 8): mergeAgents
+  // drops `hidden:true` so the agent leaves the matrix everywhere. A hide entry
+  // for a SEED carries no paths, so --global/--proj-convention are only required
+  // for a real (visible) registration.
+  const hidden = argv.includes("--hidden");
+  // Global→project inheritance (ADR-0010): default TRUE (the ~/.x/skills
+  // convention). `--no-inherits-global` opts out (persists inheritsGlobal:false);
+  // `--inherits-global` is accepted for symmetry but is the default, so we only
+  // persist the flag when it diverges from the default to keep config minimal.
+  const inheritsGlobal = !argv.includes("--no-inherits-global");
+  if (!hidden && (!global || !projConvention)) {
+    ctx.error("skl agents add: --global and --proj-convention are required");
+    return 1;
+  }
+  const entry: AgentConfigEntry = {
+    id,
+    name,
+    short: name,
+    ...(global ? { global } : {}),
+    ...(projConvention ? { projConvention } : {}),
+    ...(icon ? { icon } : {}),
+    ...(color ? { color } : {}),
+    ...(hidden ? { hidden: true } : {}),
+    ...(inheritsGlobal ? {} : { inheritsGlobal: false }),
+  };
+  const agents = await ctx.addAgent(entry);
+  if (json) {
+    ctx.json({ agents, added: true });
+    return 0;
+  }
+  ctx.log(`Registered custom agent "${name}" (${id}). Custom agents (${agents.length}):`);
+  for (const a of agents) ctx.log(`  ${a.id}  ${a.global}`);
+  return 0;
+}