skillshelf 0.2.0 → 0.4.0

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

@@ -0,0 +1,243 @@
+// `skl agents [name]` — the multi-agent deployment matrix: for each known agent
+// (claude, codex, …) and scope (Global / a project), what is each skill's
+// deployment state? Built on the same reality `skl where` inventories. ADR-0008 §7.3.
+//
+//   skl agents              human summary of installed agents + per-agent counts
+//   skl agents --json        full AgentsReport { agents, scopes, deployments }
+//   skl agents <name>        one skill's row across agents × scopes
+
+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,
+  knownAgentIds,
+  resolveReadTarget,
+  type DeployState,
+} from "../core/agents.ts";
+
+export const meta = {
+  name: "agents",
+  summary: "Show each skill's deployment state across known agents (claude, codex, …) and scopes",
+  usage: "skl agents [name] [--agent <id>] [--project <dir>] [--json]",
+} as const;
+
+const GLYPH: Record<DeployState, string> = {
+  clean: "✓",
+  source: "⊙",
+  drift: "⚠",
+  copy: "□",
+  dead: "✗",
+  absent: "·",
+};
+
+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) {
+      ctx.error(`skl agents: ${rt.error}`);
+      ctx.error("usage: " + meta.usage);
+      return 1;
+    }
+    const json = rt.rest.includes("--json");
+    const name = rt.rest.find((a) => !a.startsWith("--")) ?? null;
+
+    const lib = await ctx.loadLibrary();
+    // 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);
+    // 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).
+    if (rt.agentId) {
+      const id = rt.agentId;
+      const deployments: typeof agentsReport.deployments = {};
+      for (const [skill, byAgent] of Object.entries(agentsReport.deployments)) {
+        if (byAgent[id]) deployments[skill] = { [id]: byAgent[id] };
+      }
+      agentsReport = {
+        agents: agentsReport.agents.filter((a) => a.id === id),
+        scopes: agentsReport.scopes,
+        deployments,
+      };
+    }
+
+    if (json) {
+      if (name !== null) {
+        ctx.json({
+          name,
+          agents: agentsReport.agents,
+          scopes: agentsReport.scopes,
+          deployment: agentsReport.deployments[name] ?? {},
+        });
+        return 0;
+      }
+      ctx.json(agentsReport);
+      return 0;
+    }
+
+    // --- human view ------------------------------------------------------
+    const { agents, scopes, deployments } = agentsReport;
+    if (name !== null) {
+      const byAgent = deployments[name] ?? {};
+      ctx.log(`${name} — deployment across agents:`);
+      for (const a of agents) {
+        const dep = byAgent[a.id];
+        const g = dep?.g ?? "absent";
+        const projects = dep?.p
+          ? Object.entries(dep.p).map(([s, st]) => `${s} ${GLYPH[st]}`).join("  ")
+          : "";
+        const installed = a.installed ? "" : " (not installed)";
+        ctx.log(`  ${a.short.padEnd(10)} ${GLYPH[g]} global·${g}${installed}${projects ? `   ${projects}` : ""}`);
+      }
+      ctx.log("");
+      ctx.log(LEGEND);
+      return 0;
+    }
+
+    ctx.log(`Agents (${agents.filter((a) => a.installed).length} installed) · scopes: ${scopes.join(", ")}`);
+    for (const a of agents) {
+      let clean = 0;
+      let problems = 0;
+      for (const byAgent of Object.values(deployments)) {
+        const dep = byAgent[a.id];
+        if (!dep) continue;
+        const states: DeployState[] = [dep.g ?? "absent", ...Object.values(dep.p ?? {})];
+        for (const st of states) {
+          if (st === "clean" || st === "source") clean++;
+          else if (st !== "absent") problems++;
+        }
+      }
+      const tag = a.installed ? "" : "  (not installed)";
+      ctx.log(`  ${a.short.padEnd(10)} ${a.global}${tag}  —  ${clean} clean, ${problems} need attention`);
+    }
+    ctx.log("");
+    ctx.log(LEGEND);
+    return 0;
+  } catch (err) {
+    ctx.error(`skl agents failed: ${err instanceof Error ? err.message : String(err)}`);
+    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;
+}

package/src/commands/drop.ts

@@ -5,12 +5,14 @@
 import { join } from "node:path";
 import type { Ctx } from "../types.ts";
 import { resolveBundle } from "../core/bundle.ts";
+import { findByName } from "../core/library.ts";
+import { parseDeployTarget } from "../core/agents.ts";
 import { isSymlink, realpathOrSelf, realpathOrSelfAsync, removeSymlink } from "../lib/fs.ts";
 
 export const meta = {
   name: "drop",
-  summary: "Remove a bundle's symlinks from ./.claude/skills/",
-  usage: "skl drop <bundle> [--json]",
+  summary: "Remove a bundle's (or skill's) symlinks from an agent's skills dir (default: ./.claude/skills/)",
+  usage: "skl drop <bundle|skill> [--agent <id>] [--global | --project <name>] [--json]",
 } as const;
 
 interface DropResult {
@@ -19,14 +21,17 @@ interface DropResult {
   status: "removed" | "absent" | "skipped";
 }
 
-function projectSkillsDir(): string {
-  return join(process.cwd(), ".claude", "skills");
-}
-
 export async function run(argv: string[], ctx: Ctx): Promise<number> {
   try {
     const json = argv.includes("--json");
-    const bundleName = argv.find((a) => !a.startsWith("-"));
+    const parsed = parseDeployTarget(argv);
+    if ("error" in parsed) {
+      ctx.error(`skl drop: ${parsed.error}`);
+      ctx.error("usage: " + meta.usage);
+      return 1;
+    }
+    const { positionals, target } = parsed;
+    const bundleName = positionals[0];
 
     if (!bundleName) {
       ctx.error("usage: " + meta.usage);
@@ -36,12 +41,15 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     // Include retired so a bundle that was `use`d (which excludes retired) and a
     // later drop stay symmetric on the active set — we match on the same active set.
     const skills = await ctx.loadLibrary();
-    const bundle = await resolveBundle(
-      skills.filter((s) => !s.retired),
-      bundleName,
-    );
+    const active = skills.filter((s) => !s.retired);
+    // Mirror `use`: resolve a single skill name first, else a bundle, so
+    // `skl drop <skill>` undoes `skl use <skill>` symmetrically.
+    const single = findByName(active, bundleName);
+    const bundle = single
+      ? { name: single.name, skills: [single] }
+      : await resolveBundle(active, bundleName);
 
-    const skillsDir = projectSkillsDir();
+    const skillsDir = target.dir;
     const results: DropResult[] = [];
 
     for (const s of bundle.skills) {
@@ -68,7 +76,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     const removedCount = results.filter((r) => r.status === "removed").length;
 
     if (json) {
-      ctx.json({ bundle: bundle.name, skillsDir, results, removed: removedCount });
+      ctx.json({ bundle: bundle.name, skillsDir, agent: target.agentId, scope: target.scope, results, removed: removedCount });
     } else {
       if (bundle.skills.length === 0) {
         ctx.log(`Bundle '${bundleName}' has no skills; nothing to drop.`);