skillshelf 0.6.1 → 0.7.0

package/README.md

@@ -115,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/claim-log/skill/claim-log
+skl link --from ~/dev/headline-picker/skill/headline-picker
 
 # 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.
@@ -183,29 +183,35 @@ See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for the full design.
 | `skl import <name> --from <path>` | Adopt your own skill into the library as an OWNED copy (move + symlink-back, or `--copy`) | `--copy`, `--as <slug>`, `--force` |
 | `skl link [<name>] --from <dev-repo>` | Shelve a dev-repo skill as a LINKED entry (library symlinks to it; the repo stays canonical). `--at <path>` instead collapses a stray copy into the library | `--from`, `--at`, `--force` |
 | `skl new <name>` | Scaffold a new skill dir + SKILL.md into the library | `--domain <d>`, `--desc "..."`, `--force` |
-| `skl ls [bundle]` | One-line listing of the library, or one bundle (`--json` carries `mode`/`linkTarget`) | `--all` |
+| `skl ls [bundle]` | One-line listing of the library, or one bundle (`--json` carries `mode`/`linkTarget`) | `--all`, `--sort modified\|name\|domain\|deploys\|source` |
 | `skl search <kw...>` | Fuzzy match over name + description + domains across the library | — |
 | `skl show <name>` | Print a skill's SKILL.md body; list reference-file paths (not contents) | — |
 | `skl tag <name> <domain>…` | Add domain tag(s) to a skill in the central taxonomy (deterministic, no LLM) | — |
 | `skl untag <name> <domain>` | Remove a domain tag from a skill | — |
 | `skl retag <old> <new>` | Rename a domain across the whole library taxonomy (deterministic) | — |
 | `skl rename <old> <new>` | Rename a skill slug atomically (dir + frontmatter + taxonomy + lock). Alias `skl mv` | — |
-| `skl retire <name>` | Soft-delete a skill into `_retired/` (reversible; excluded from deploys) | — |
-| `skl unretire <name>` | Restore a retired skill back to the active library | — |
-| `skl rm <name>` | Delete a skill (dir/symlink + taxonomy + lock), re-index. Refuses a live OWNED skill without `--force`; a LINKED entry `rm`s freely (safe unlink) | `--force`, `--dry-run` |
-| `skl status` | Show which library skills are linked into `./.claude/skills`; flags unmanaged real copies (drift-prone) | — |
+| `skl retire <name…>` | Soft-delete skill(s) into `_retired/` (reversible; excluded from deploys) | — |
+| `skl unretire <name…>` | Restore retired skill(s) back to the active library | — |
+| `skl rm <name…>` | Delete skill(s) (dir/symlink + taxonomy + lock), re-index. Refuses a live OWNED skill without `--force`; a LINKED entry `rm`s freely (safe unlink) | `--force`, `--dry-run` |
+| `skl status` | Show which library skills are linked into an agent's project skills dir (default `./.claude/skills`); flags unmanaged real copies (drift-prone) | `--agent <id>`, `--project <dir>` |
 | `skl where [name]` | Map where each skill is deployed across all agents (Claude, Codex, Cursor…); flags copies, drift, 2nd-sources, dead links — a dev repo a library entry links to shows as a clean `✓ source` | `--problems`, `--prune`, `--fix`, `--dry-run` |
-| `skl use <bundle\|skill>` | Symlink a bundle (or a single skill) into `./.claude/skills/` (hot-loads) | — |
-| `skl drop <bundle\|skill>` | Remove a bundle's (or single skill's) symlinks from `./.claude/skills/` | — |
+| `skl agents [name]` | Per-agent × per-scope deployment matrix (one skill's row, or the whole library) | `--agent <id>`, `--project <dir>` |
+| `skl use <bundle\|skill>…` | Symlink bundle(s)/skill(s) into an agent's skills dir (default `./.claude/skills/`, hot-loads). `--force` replaces a real-file conflict with the library symlink | `--agent <id>`, `--global \| --project <name>`, `--force` |
+| `skl drop <bundle\|skill>…` | Remove bundle/skill symlinks from an agent's skills dir | `--agent <id>`, `--global \| --project <name>` |
+| `skl realign <deployed-name>` | Rename an aliased deployment symlink (wrong name) to match its library skill | `--agent <id>`, `--global \| --project <name>` |
+| `skl diff <name>` | Unified diff of a deployed copy's `SKILL.md` against the library skill (read-only) | `--agent <id>`, `--global \| --project <name>` |
 | `skl refresh` | Re-sync this project's `./.claude/skills` symlinks to current library reality (repoint stale, prune vanished) | `--dry-run` |
+| `skl projects` | Manage the persisted nav projects shown as scopes in the desktop app (`ls`/`add`/`rm`) | — |
 | `skl add <src>` | Install third-party skill(s) into the library (librarian only — no agent-dir writes). One repo = **one clone**: a bare repo with several skills needs `--all`/`--skill`/`--list`; single-skill `add <repo>/<path>` is unchanged. `--all` installs the **published set** (the `.claude-plugin`/`marketplace.json` manifest allowlist when present, else every discovered skill; minus `metadata.internal`); an unpublished skill installs only via `--skill <name>`. A published set over **15** skills refuses without `--yes` (a count gate on blast radius; `--skill` is never gated). `--list` discovers + prints (marks `published`/`unpublished`); `--dry-run` previews drift (new/identical/differs); a `differs` skill is skipped without `--force` ([ADR-0012](./docs/adr/0012-published-set-and-all-count-gate.md)) | `--all`, `--skill <a,b>`, `--list`, `--yes`, `--dry-run`, `--domain <d>`, `--name <slug>`, `--no-infer`, `--force` |
+| `skl track <name> --source <src>` | Adopt provenance for a library skill you already have (offline; no re-download). `skl untrack` drops the lock entry (idempotent inverse) | `--ref <r>`, `--resolve`, `--force` |
+| `skl migrate` | Bulk-adopt provenance from a vendor skill-lock for skills already in your library | `--from <path>`, `--dry-run`, `--resolve`, `--force` |
 | `skl outdated [name]` | Check upstream ref per tracked skill and mark stale ones (LINKED dev-repo entries are reported, never probed); `--check-local` diffs the local body against its baseline offline | `--check-local` |
 | `skl update [name]` | Re-pull upstream body, preserve domain tags, diff if local body diverged (LINKED entries are skipped — their own git owns versioning) | `--force`, `--dry-run` |
 | `skl index` | Regenerate `INDEX.md` (catalog grouped by domain) | — |
 | `skl infer` | Re-run AI domain taxonomy over the library (emit/apply/provider modes) | see below |
 
 Every command also accepts `--json`. Destructive/edit verbs (`rm`, `retire`/`unretire`,
-`rename`, `tag`/`untag`/`retag`, `scan --remove-root`, `where --prune`/`--fix`,
+`rename`, `realign`, `tag`/`untag`/`retag`, `scan --remove-root`, `where --prune`/`--fix`,
 `refresh`) are the inverse + fine-grained-edit family from
 [ADR-0005](./docs/adr/0005-inverse-and-edit-verbs.md): reversible by default, transactional
 across the skill dir + `taxonomy.json` + `shelf.lock.json` + `INDEX.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillshelf",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Agent-first skill registry + manager for Claude Code and compatible agents.",
   "type": "module",
   "license": "MIT",
@@ -25,7 +25,7 @@
     "skl": "./src/cli.ts"
   },
   "scripts": {
-    "preinstall": "bun --version >/dev/null 2>&1 || { echo '\\nskillshelf requires the Bun runtime (https://bun.sh) — its bin is a TypeScript entrypoint, not a compiled Node script.\\nInstall Bun, then:  bun add -g skillshelf   (or run without installing:  bunx skillshelf <command>)\\n' >&2; exit 1; }",
+    "preinstall": "bun --version >/dev/null 2>&1 || { echo '\\nskillshelf requires the Bun runtime (https://bun.sh) \u2014 its bin is a TypeScript entrypoint, not a compiled Node script.\\nInstall Bun, then:  bun add -g skillshelf   (or run without installing:  bunx skillshelf <command>)\\n' >&2; exit 1; }",
     "skl": "bun run src/cli.ts",
     "test": "bun test"
   },

package/src/cli.ts

@@ -21,6 +21,8 @@ import * as show from "./commands/show.ts";
 import * as index from "./commands/index.ts";
 import * as use from "./commands/use.ts";
 import * as drop from "./commands/drop.ts";
+import * as realign from "./commands/realign.ts";
+import * as diffCmd from "./commands/diff.ts";
 import * as init from "./commands/init.ts";
 import * as add from "./commands/add.ts";
 import * as outdated from "./commands/outdated.ts";
@@ -56,6 +58,8 @@ const MODULES: CommandModule[] = [
   show,
   use,
   drop,
+  realign,
+  diffCmd,
   refresh,
   add,
   scan,

package/src/commands/add.ts

@@ -174,7 +174,6 @@ async function reportDryRun(
   parsed: ParsedSource,
   ref: string,
   discovered: DiscoveredSkill[],
-  domainFolder: string | null,
 ): Promise<number> {
   interface Row {
     name: string;
@@ -189,7 +188,7 @@ async function reportDryRun(
       rows.push({ name: d.name, subpath: d.subpath, verdict: "invalid", willInstall: false, needsForce: false });
       continue;
     }
-    const destDir = destDirFor(ctx.config.libraryPath, domainFolder, d.name);
+    const destDir = destDirFor(ctx.config.libraryPath, d.name);
     if (writesThroughSymlink(ctx.config.libraryPath, destDir)) {
       rows.push({ name: d.name, subpath: d.subpath, verdict: "linked", willInstall: false, needsForce: false });
       continue;
@@ -240,10 +239,11 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     return 1;
   }
 
-  // --domain validated once up front (applies to every install path).
-  const domainFolder = flags.domain && flags.domain.trim() !== "" ? flags.domain.trim() : null;
-  if (domainFolder !== null && !SLUG_RE.test(domainFolder)) {
-    ctx.error(`add: invalid --domain "${domainFolder}" — use lowercase letters, digits, and hyphens`);
+  // --domain validated once up front (applies to every install path). It is a taxonomy
+  // tag, never a folder — installs always land flat at library/<name> (ADR-0001).
+  const domain = flags.domain && flags.domain.trim() !== "" ? flags.domain.trim() : null;
+  if (domain !== null && !SLUG_RE.test(domain)) {
+    ctx.error(`add: invalid --domain "${domain}" — use lowercase letters, digits, and hyphens`);
     return 1;
   }
 
@@ -340,7 +340,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         : flags.skill !== null
           ? discovered.filter((d) => flags.skill!.includes(d.name))
           : discovered;
-      return await reportDryRun(ctx, flags, parsed, ref, preview, domainFolder);
+      return await reportDryRun(ctx, flags, parsed, ref, preview);
     }
 
     // ---- selection ----
@@ -395,7 +395,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         selected[0]!,
         {
           libraryPath: ctx.config.libraryPath,
-          domainFolder,
+          domain,
           nameOverride: flags.name,
           sourceStr: sourceOf(selected[0]!),
           ref,
@@ -474,7 +474,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
           s,
           {
             libraryPath: ctx.config.libraryPath,
-            domainFolder,
+            domain,
             nameOverride: null,
             sourceStr: sourceOf(s),
             ref,

package/src/commands/diff.ts

@@ -0,0 +1,78 @@
+// `skl diff <name>` — unified diff between a DEPLOYED site's SKILL.md and the
+// library skill's SKILL.md, for one agent surface. Read-only (an L2 fact per
+// ADR-0007: two runs can't disagree). The engine verb behind the UI's drift
+// "View diff" action. A clean symlink deployment trivially reports identical —
+// its realpath IS the library copy.
+
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import type { Ctx } from "../types.ts";
+import { parseDeployTarget } from "../core/agents.ts";
+import { findByName } from "../core/library.ts";
+import { readSkillBody, unifiedDiff } from "../core/fetch.ts";
+import { isSymlink, realpathOrSelfAsync } from "../lib/fs.ts";
+import { render, type CommandResult } from "../core/report.ts";
+
+export const meta = {
+  name: "diff",
+  summary: "Unified diff of a deployed copy's SKILL.md against the library skill",
+  usage: "skl diff <name> [--agent <id>] [--global | --project <name>] [--json]",
+} as const;
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  try {
+    const json = argv.includes("--json");
+    const parsed = parseDeployTarget(argv);
+    if ("error" in parsed) {
+      ctx.error(`skl diff: ${parsed.error}`);
+      ctx.error("usage: " + meta.usage);
+      return 1;
+    }
+    const { positionals, target } = parsed;
+    const name = positionals[0];
+    if (!name || positionals.length > 1) {
+      ctx.error("usage: " + meta.usage);
+      return 1;
+    }
+
+    const skills = await ctx.loadLibrary();
+    const skill = findByName(
+      skills.filter((s) => !s.retired),
+      name,
+    );
+    if (!skill) {
+      ctx.error(`skl diff: no library skill named "${name}"`);
+      return 1;
+    }
+
+    const site = join(target.dir, name);
+    if (!existsSync(site) && !isSymlink(site)) {
+      ctx.error(`skl diff: ${name} is not deployed at ${target.dir}`);
+      return 1;
+    }
+
+    // A symlink resolving to the library skill can't drift — same bytes.
+    const siteReal = await realpathOrSelfAsync(site);
+    const libReal = await realpathOrSelfAsync(skill.path);
+    const deployedBody = siteReal === libReal ? null : await readSkillBody(site);
+    const libraryBody = await readSkillBody(skill.path);
+    const text =
+      deployedBody === null
+        ? ""
+        : await unifiedDiff(libraryBody, deployedBody, `library/${name}/SKILL.md`, `${site}/SKILL.md`);
+
+    const identical = text.trim() === "";
+    const result: CommandResult = {
+      json: { name, site, library: skill.path, identical, diff: text },
+      human: (emit) => {
+        if (identical) emit(`${name}: deployed copy matches the library (no drift)`);
+        else emit(text.trimEnd());
+      },
+    };
+    render(ctx, json, result);
+    return 0;
+  } catch (err) {
+    ctx.error(`skl diff failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/realign.ts

@@ -0,0 +1,89 @@
+// `skl realign <deployed-name>` — fix an ALIASED deployment: a symlink in an
+// agent's skills dir that resolves to a library skill but carries the WRONG
+// name (e.g. `nuwa` -> <library>/huashu-nuwa). Renames the link to the library
+// skill's name so name-keyed views (status/agents) see it again. The engine
+// verb behind the UI's "Realign name" remediation. Only ever renames a symlink
+// in place — never touches the library or the link target.
+
+import { join } from "node:path";
+import { rename } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import type { Ctx } from "../types.ts";
+import { parseDeployTarget } from "../core/agents.ts";
+import { isSymlink, realpathOrSelf, realpathOrSelfAsync } from "../lib/fs.ts";
+import { render, type CommandResult } from "../core/report.ts";
+
+export const meta = {
+  name: "realign",
+  summary: "Rename an aliased deployment symlink to match its library skill",
+  usage: "skl realign <deployed-name> [--agent <id>] [--global | --project <name>] [--json]",
+} as const;
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  try {
+    const json = argv.includes("--json");
+    const parsed = parseDeployTarget(argv);
+    if ("error" in parsed) {
+      ctx.error(`skl realign: ${parsed.error}`);
+      ctx.error("usage: " + meta.usage);
+      return 1;
+    }
+    const { positionals, target } = parsed;
+    const deployedName = positionals[0];
+    if (!deployedName || positionals.length > 1) {
+      ctx.error("usage: " + meta.usage);
+      return 1;
+    }
+
+    const link = join(target.dir, deployedName);
+    if (!isSymlink(link)) {
+      ctx.error(
+        `skl realign: ${link} is not a symlink — realign only renames aliased links (a real copy is a different anomaly; see \`skl where\`)`,
+      );
+      return 1;
+    }
+
+    // Resolve which library skill the link points at, by realpath — this also
+    // matches a LINKED library entry, whose canonical realpath is its external
+    // dev repo, exactly like the `where` classifier does.
+    const real = await realpathOrSelfAsync(link);
+    const skills = await ctx.loadLibrary();
+    const owner = skills.find((s) => !s.retired && realpathOrSelf(s.path) === real);
+    if (!owner) {
+      ctx.error(
+        `skl realign: ${link} does not resolve to any library skill (target: ${real}) — nothing to align to`,
+      );
+      return 1;
+    }
+
+    if (owner.name === deployedName) {
+      const result: CommandResult = {
+        json: { from: deployedName, to: owner.name, link, status: "already" },
+        human: (emit) => emit(`${deployedName} already matches its library skill — nothing to do`),
+      };
+      render(ctx, json, result);
+      return 0;
+    }
+
+    const dest = join(target.dir, owner.name);
+    if (existsSync(dest) || isSymlink(dest)) {
+      ctx.error(
+        `skl realign: ${dest} already exists — remove one of the two deployments first (\`skl drop ${deployedName}\` keeps the aligned one)`,
+      );
+      return 1;
+    }
+
+    // Atomic same-dir rename of the LINK itself (rename never dereferences).
+    await rename(link, dest);
+
+    const result: CommandResult = {
+      json: { from: deployedName, to: owner.name, link: dest, status: "realigned" },
+      human: (emit) => emit(`realigned ${deployedName} -> ${owner.name} in ${target.dir}`),
+    };
+    render(ctx, json, result);
+    return 0;
+  } catch (err) {
+    ctx.error(`skl realign failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/rm.test.ts

@@ -166,6 +166,30 @@ describe("skl rm/retire/unretire — removal lifecycle (friction #1)", () => {
     expect(errors.join("\n")).toContain("not in the library");
   });
 
+  test("rm removes MULTIPLE names in one call (regression: batch must not drop names)", async () => {
+    await writeSkill(library, "beta");
+    await writeSkill(library, "gamma");
+    const { ctx } = makeCtx(library);
+    // Live OWNED skills need --force; the WHOLE batch must purge, not just the first
+    // (the old single-name rm silently ignored names 2..N).
+    const code = await rmRun(["alpha", "beta", "gamma", "--force"], ctx);
+    expect(code).toBe(0);
+    for (const n of ["alpha", "beta", "gamma"]) {
+      expect(existsSync(join(library, n))).toBe(false);
+    }
+  });
+
+  test("rm batch is ATOMIC on validation — one missing name deletes nothing", async () => {
+    await writeSkill(library, "beta");
+    const { ctx, errors } = makeCtx(library);
+    const code = await rmRun(["alpha", "ghost", "beta", "--force"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("not in the library");
+    // No partial purge — both valid names survive because one name was invalid.
+    expect(existsSync(join(library, "alpha"))).toBe(true);
+    expect(existsSync(join(library, "beta"))).toBe(true);
+  });
+
   test("rm refuses a path-traversal name (no escape outside the library)", async () => {
     // a sibling dir outside the library that must NOT be deletable via `../`
     const victim = join(tmp, "victim");

package/src/commands/rm.ts

@@ -1,10 +1,14 @@
-// `skl rm <name>` — delete a skill from the library entirely: remove its dir (or, for
-// a LINKED entry, just the symlink — the dev repo it points at is never touched, so
-// this doubles as `unlink`) AND drop its taxonomy + lockfile entries, then re-index.
+// `skl rm <name>...` — delete skill(s) from the library entirely: remove each dir (or,
+// for a LINKED entry, just the symlink — the dev repo it points at is never touched, so
+// this doubles as `unlink`) AND drop its taxonomy + lockfile entries, then re-index ONCE.
 // Before this, the ONLY delete path was an unguarded `rm -rf` against the library —
 // no safety rail for the most destructive lifecycle step.
 //
-//   skl rm <name> [--force] [--dry-run] [--json]
+//   skl rm <name>... [--force] [--dry-run] [--json]
+//
+// Batch: multiple names delete in one call (reindex collapses to one, mirroring
+// `retire`). Validation is ATOMIC — if any name is missing or a live OWNED skill without
+// --force, the whole batch refuses and nothing is deleted (never a partial purge).
 //
 // Safety (mirrors `link --at` refuse-by-default + named escape hatch): a LIVE (active,
 // non-retired) skill is refused without --force — retire it first (reversible) or pass
@@ -12,15 +16,15 @@
 // it purges without --force. --dry-run previews exactly what would be removed.
 
 import type { Ctx } from "../types.ts";
-import { locateEntry, removeSkill, reindexLibrary } from "../core/lifecycle.ts";
+import { locateEntry, removeSkill, reindexLibrary, type RemoveResult } from "../core/lifecycle.ts";
 import { readTaxonomy } from "../core/taxonomy.ts";
 import { readLockfile } from "../core/provenance.ts";
 import { render, type CommandResult } from "../core/report.ts";
 
 export const meta = {
   name: "rm",
-  summary: "Delete a skill from the library (dir/symlink + taxonomy + lock), re-index",
-  usage: "skl rm <name> [--force] [--dry-run] [--json]",
+  summary: "Delete skill(s) from the library (dir/symlink + taxonomy + lock), re-index",
+  usage: "skl rm <name>... [--force] [--dry-run] [--json]",
 } as const;
 
 export async function run(argv: string[], ctx: Ctx): Promise<number> {
@@ -35,64 +39,71 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     ctx.error(`usage: ${meta.usage}`);
     return 1;
   }
-  const name = argv.find((a) => !a.startsWith("--"));
-  if (!name) {
+  const names = argv.filter((a) => !a.startsWith("--"));
+  if (names.length === 0) {
     ctx.error("skl rm: a <name> is required");
     ctx.error(`usage: ${meta.usage}`);
     return 1;
   }
 
   try {
-    const loc = locateEntry(ctx.libraryPath, name);
-    if (!loc.path) {
-      ctx.error(`skl rm: '${name}' is not in the library`);
+    // Locate + guard EVERY name up front. The batch is ATOMIC on validation: if any
+    // name is missing, or is a live OWNED skill without --force (destroys real bytes),
+    // refuse the WHOLE batch and delete nothing — never a partial purge.
+    const located = names.map((name) => ({ name, loc: locateEntry(ctx.libraryPath, name) }));
+
+    const notFound = located.filter((x) => !x.loc.path).map((x) => x.name);
+    if (notFound.length) {
+      // Not-found stays a plain error (no --json body), matching the prior single-name path.
+      for (const n of notFound) ctx.error(`skl rm: '${n}' is not in the library`);
       return 1;
     }
-    // Refuse only a live OWNED skill unless forced — that destroys real bytes. A
-    // LINKED entry is just a symlink: removing it loses nothing (the dev repo stays
-    // canonical), so `skl rm <linked>` is the safe `unlink` and needs no --force. A
-    // purely-retired skill is already in the reversible holding area, so it purges
-    // freely. NOTE: gate on `loc.active` itself (the resolved path IS the active copy
-    // when active), NOT on the absence of a retired twin — a skill present in BOTH
-    // active and _retired still resolves `path` to the active copy, so a `!loc.retired`
-    // term would wrongly drop the guard and delete the live copy without --force.
-    if (loc.active && !loc.isLink && !force) {
-      // Refusal is an ERROR path: the human side prints via ctx.error (not ctx.log),
-      // so it stays in run(); only the --json payload routes through render().
+
+    // Refuse only a live OWNED skill unless forced — that destroys real bytes. A LINKED
+    // entry is just a symlink (removing it loses nothing); a purely-retired skill is
+    // already in the reversible holding area — both purge freely. Gate on `loc.active`
+    // itself (NOT `!loc.retired`) so a skill present in BOTH active and _retired keeps
+    // the guard on its live copy.
+    const refused = located.filter((x) => x.loc.active && !x.loc.isLink && !force).map((x) => x.name);
+    if (refused.length) {
       if (json) {
-        const result: CommandResult = {
-          json: { ok: false, name, refused: true, reason: "live-owned-needs-force" },
-          human: () => {},
-        };
-        render(ctx, json, result);
+        // Preserve the single-name payload shape; use a list form for a batch.
+        const body =
+          names.length === 1
+            ? { ok: false, name: names[0], refused: true, reason: "live-owned-needs-force" }
+            : { ok: false, refused, reason: "live-owned-needs-force" };
+        render(ctx, json, { json: body, human: () => {} });
       } else {
-        ctx.error(`skl rm: '${name}' is a live skill — this destroys real bytes.`);
-        ctx.error("Retire it first (reversible):  skl retire " + name);
-        ctx.error("Or hard-purge now:             skl rm " + name + " --force");
+        for (const n of refused) {
+          ctx.error(`skl rm: '${n}' is a live skill — this destroys real bytes.`);
+          ctx.error("Retire it first (reversible):  skl retire " + n);
+          ctx.error("Or hard-purge now:             skl rm " + n + " --force");
+        }
       }
       return 1;
     }
 
     // Preview what would be dropped (for --dry-run and richer reporting).
-    const tax = await readTaxonomy(ctx.libraryPath);
-    const lock = await readLockfile(ctx.libraryPath);
-    const plan = {
-      name,
-      path: loc.path,
-      mode: loc.isLink ? ("linked" as const) : ("owned" as const),
-      wasRetired: loc.retired && !loc.active,
-      taxonomyEntry: name in tax.skills,
-      lockEntry: name in lock.entries,
-    };
-
     if (dryRun) {
+      const tax = await readTaxonomy(ctx.libraryPath);
+      const lock = await readLockfile(ctx.libraryPath);
+      const plans = located.map(({ name, loc }) => ({
+        name,
+        path: loc.path,
+        mode: loc.isLink ? ("linked" as const) : ("owned" as const),
+        wasRetired: loc.retired && !loc.active,
+        taxonomyEntry: name in tax.skills,
+        lockEntry: name in lock.entries,
+      }));
       const result: CommandResult = {
-        json: { ok: true, dryRun: true, plan },
+        json: names.length === 1 ? { ok: true, dryRun: true, plan: plans[0] } : { ok: true, dryRun: true, plans },
         human: (emit) => {
-          emit(`DRY RUN — would remove '${name}':`);
-          emit(`  path:     ${plan.path}${plan.mode === "linked" ? " (symlink only — dev repo untouched)" : ""}`);
-          emit(`  taxonomy: ${plan.taxonomyEntry ? "drop entry" : "none"}`);
-          emit(`  lockfile: ${plan.lockEntry ? "drop entry" : "none"}`);
+          for (const plan of plans) {
+            emit(`DRY RUN — would remove '${plan.name}':`);
+            emit(`  path:     ${plan.path}${plan.mode === "linked" ? " (symlink only — dev repo untouched)" : ""}`);
+            emit(`  taxonomy: ${plan.taxonomyEntry ? "drop entry" : "none"}`);
+            emit(`  lockfile: ${plan.lockEntry ? "drop entry" : "none"}`);
+          }
           emit("Re-run without --dry-run to apply.");
         },
       };
@@ -100,14 +111,22 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
       return 0;
     }
 
-    const removed = await removeSkill(ctx.libraryPath, name);
+    // Apply: remove each, then re-index ONCE at the end (a per-name reindex is the cost
+    // a bulk rm avoids — collapse it to one, mirroring bulkLifecycle).
+    const removed: RemoveResult[] = [];
+    for (const { name } of located) {
+      removed.push(await removeSkill(ctx.libraryPath, name));
+    }
     await reindexLibrary(ctx.libraryPath);
+
     const result: CommandResult = {
-      json: { ok: true, ...removed },
+      json: names.length === 1 ? { ok: true, ...removed[0] } : { ok: true, removed },
       human: (emit) => {
-        emit(`removed ${name}${removed.wasLink ? " (symlink only — dev repo untouched)" : ""}`);
-        if (removed.taxonomyDropped) emit("  dropped taxonomy entry");
-        if (removed.lockDropped) emit("  dropped lockfile entry");
+        for (const r of removed) {
+          emit(`removed ${r.name}${r.wasLink ? " (symlink only — dev repo untouched)" : ""}`);
+          if (r.taxonomyDropped) emit("  dropped taxonomy entry");
+          if (r.lockDropped) emit("  dropped lockfile entry");
+        }
       },
     };
     render(ctx, json, result);

package/src/commands/use.ts

@@ -5,7 +5,7 @@
 // library crawl, one symlink pass); the single-name shape is byte-identical to before.
 
 import { join } from "node:path";
-import { mkdir } from "node:fs/promises";
+import { mkdir, rm } from "node:fs/promises";
 import type { Ctx, Skill } from "../types.ts";
 import { resolveBundle } from "../core/bundle.ts";
 import { activeSkills, findByName } from "../core/library.ts";
@@ -16,20 +16,25 @@ import { render, type CommandResult } from "../core/report.ts";
 export const meta = {
   name: "use",
   summary: "Symlink bundle(s)/skill(s) into an agent's skills dir (default: ./.claude/skills/)",
-  usage: "skl use <bundle|skill>... [--agent <id>] [--global | --project <name>] [--json]",
+  usage: "skl use <bundle|skill>... [--agent <id>] [--global | --project <name>] [--force] [--json]",
 } as const;
 
 interface LinkResult {
   name: string;
   target: string;
   link: string;
-  status: "linked" | "already" | "conflict";
+  status: "linked" | "already" | "conflict" | "overwritten";
 }
 
 export async function run(argv: string[], ctx: Ctx): Promise<number> {
   try {
     const json = argv.includes("--json");
-    const parsed = parseDeployTarget(argv);
+    // --force: a real (non-symlink) file/dir occupying a slot is REPLACED by the
+    // library symlink instead of reported as a conflict — the UI's "Overwrite
+    // from library" drift remediation. Consumed here; parseDeployTarget rejects
+    // unknown flags.
+    const force = argv.includes("--force");
+    const parsed = parseDeployTarget(argv.filter((a) => a !== "--force"));
     if ("error" in parsed) {
       ctx.error(`skl use: ${parsed.error}`);
       ctx.error("usage: " + meta.usage);
@@ -118,9 +123,16 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         const want = await realpathOrSelfAsync(skillPath);
         if (cur === want) status = "already";
       } else if (await pathTakenNonLink(link)) {
-        // A real (non-symlink) file/dir occupies the slot — don't clobber it.
-        results.push({ name: s.name, target: skillPath, link, status: "conflict" });
-        continue;
+        if (!force) {
+          // A real (non-symlink) file/dir occupies the slot — don't clobber it.
+          results.push({ name: s.name, target: skillPath, link, status: "conflict" });
+          continue;
+        }
+        // --force: replace the real entry with the library symlink. `link` is
+        // always join(skillsDir, <library skill name>), so the removal cannot
+        // reach outside the agent's skills dir.
+        await rm(link, { recursive: true, force: true });
+        status = "overwritten";
       }
 
       await safeSymlink(skillPath, link);
@@ -139,7 +151,13 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         emit(`${label} -> ${skillsDir}`);
         for (const r of results) {
           const tag =
-            r.status === "linked" ? "linked" : r.status === "already" ? "ok" : "SKIP (real file present)";
+            r.status === "linked"
+              ? "linked"
+              : r.status === "already"
+                ? "ok"
+                : r.status === "overwritten"
+                  ? "overwritten (real file replaced)"
+                  : "SKIP (real file present)";
           emit(`  ${r.name}  [${tag}]`);
         }
         for (const u of unresolved) {

package/src/core/agent-matrix.test.ts

@@ -14,7 +14,7 @@ import {
 } from "./agent-matrix.ts";
 
 const HOME = "/home/u";
-const IDS = ["claude", "codex", "cursor", "opencode", "gemini", "omp"] as const;
+const IDS = ["claude", "codex", "cursor", "opencode", "gemini", "pi"] as const;
 
 function site(p: Partial<DeploymentSite> & { name: string; surface: string }): DeploymentSite {
   return {
@@ -31,9 +31,9 @@ function site(p: Partial<DeploymentSite> & { name: string; surface: string }): D
 describe("agentIdForSurface honors `ids` ordering", () => {
   test("returns the FIRST matching id in the given order (custom precedence)", () => {
     // A surface that could match two ids: the caller's order decides the winner.
-    const s = "/work/proj/.pi/skills";
-    expect(agentIdForSurface(s, ["pi", "claude"])).toBe("pi");
-    // pi not in the id set → no match (the engine never widened to it).
+    const s = "/work/proj/.walrus/skills";
+    expect(agentIdForSurface(s, ["walrus", "claude"])).toBe("walrus");
+    // walrus not in the id set → no match (the engine never widened to it).
     expect(agentIdForSurface(s, ["claude", "codex"])).toBeNull();
   });
   test("matches segment, trailing dotdir, and trailing /skills", () => {
@@ -146,8 +146,8 @@ describe("foldAgentMatrix", () => {
   });
 
   test("custom-agent surface detected via a widened id set", () => {
-    const sites = [site({ name: "x", surface: "/work/proj/.pi/skills", kind: "linked" })];
-    const m = foldAgentMatrix(sites, { home: HOME, agentIds: [...IDS, "pi"] });
-    expect(m.deployments.x!.pi!.p!.proj).toBe("clean");
+    const sites = [site({ name: "x", surface: "/work/proj/.walrus/skills", kind: "linked" })];
+    const m = foldAgentMatrix(sites, { home: HOME, agentIds: [...IDS, "walrus"] });
+    expect(m.deployments.x!.walrus!.p!.proj).toBe("clean");
   });
 });

package/src/core/agents.test.ts

@@ -113,7 +113,7 @@ describe("computeAgentsReport", () => {
   const r = computeAgentsReport(report, HOME);
 
   test("registers the 6 known agents (installed=false under a fake HOME)", () => {
-    expect(r.agents.map((a) => a.id)).toEqual(["claude", "codex", "cursor", "opencode", "gemini", "omp"]);
+    expect(r.agents.map((a) => a.id)).toEqual(["claude", "codex", "cursor", "opencode", "gemini", "pi"]);
     expect(r.agents.every((a) => a.installed === false)).toBe(true);
     expect(r.agents[0]!.global).toBe("~/.claude/skills");
   });
@@ -138,9 +138,9 @@ describe("computeAgentsReport — opts (ADR-0010)", () => {
     problems: [],
   };
 
-  test("opts.agents appends a custom agent (pi) after the seeds", () => {
+  test("opts.agents appends a custom agent (walrus) after the seeds", () => {
     const r = computeAgentsReport(baseReport, HOME, {
-      agents: [{ id: "pi", name: "PI Agent", short: "PI", icon: "anthropic" }],
+      agents: [{ id: "walrus", name: "Walrus Agent", short: "Walrus", icon: "anthropic" }],
     });
     expect(r.agents.map((a) => a.id)).toEqual([
       "claude",
@@ -148,8 +148,8 @@ describe("computeAgentsReport — opts (ADR-0010)", () => {
       "cursor",
       "opencode",
       "gemini",
-      "omp",
       "pi",
+      "walrus",
     ]);
   });
 
@@ -177,17 +177,17 @@ describe("computeAgentsReport — opts (ADR-0010)", () => {
     const r = computeAgentsReport(
       {
         surfaces: [],
-        sites: [site({ name: "x", surface: "/work/proj/.pi/skills", kind: "linked" })],
+        sites: [site({ name: "x", surface: "/work/proj/.walrus/skills", kind: "linked" })],
         problems: [],
       },
       HOME,
-      { agents: [{ id: "pi", name: "PI", short: "PI" }] },
+      { agents: [{ id: "walrus", name: "Walrus", short: "Walrus" }] },
     );
-    expect(r.deployments.x!.pi!.p!.proj).toBe("clean");
+    expect(r.deployments.x!.walrus!.p!.proj).toBe("clean");
   });
   test("no opts is backward-compatible (seed-only, default extraScopes)", () => {
     const r = computeAgentsReport(baseReport, HOME);
-    expect(r.agents.map((a) => a.id)).toEqual(["claude", "codex", "cursor", "opencode", "gemini", "omp"]);
+    expect(r.agents.map((a) => a.id)).toEqual(["claude", "codex", "cursor", "opencode", "gemini", "pi"]);
   });
 
   test("inheritsGlobal: all seeds default true; report carries the flag", () => {
@@ -199,11 +199,11 @@ describe("computeAgentsReport — opts (ADR-0010)", () => {
   test("inheritsGlobal: a custom agent defaults true unless inheritsGlobal:false", () => {
     const r = computeAgentsReport(baseReport, HOME, {
       agents: [
-        { id: "pi", name: "PI", short: "PI" }, // no flag → inherits (true)
+        { id: "walrus", name: "Walrus", short: "Walrus" }, // no flag → inherits (true)
         { id: "static", name: "Static", short: "Static", inheritsGlobal: false },
       ],
     });
-    expect(r.agents.find((a) => a.id === "pi")!.inheritsGlobal).toBe(true);
+    expect(r.agents.find((a) => a.id === "walrus")!.inheritsGlobal).toBe(true);
     expect(r.agents.find((a) => a.id === "static")!.inheritsGlobal).toBe(false);
   });
 

package/src/core/agents.ts

@@ -72,22 +72,22 @@ interface AgentSeed {
   short: string;
 }
 // ENGINE seed list — the full set of agents `skl` can DETECT on disk (claude,
-// codex, cursor, opencode, gemini, omp; no `pi` — `pi` is a user-facing alias for
-// `omp` in the app). This INTENTIONALLY diverges from the app-side seed list in
-// `app/src/lib/agents.ts` (claude, codex, pi, omp), which shows only the agents a
-// given user actually deploys to and reconstructs the report in the browser dev
-// fallback. The two lists are NOT meant to match: the engine errs toward broad
-// detection, the app toward the user's real surfaces, and custom/overridden agents
-// flow through config (delta 4) on both sides. If you add/remove an id here, decide
-// deliberately whether the app list should follow — see the matching comment over
-// AGENT_SEEDS in app/src/lib/agents.ts.
+// codex, cursor, opencode, gemini, pi). `pi` is now a first-class engine-seeded
+// agent, matching the app-side seed list in `app/src/lib/agents.ts` (claude,
+// codex, pi), which shows only the agents a given user actually deploys to and
+// reconstructs the report in the browser dev fallback. The two lists are NOT
+// meant to match exactly: the engine errs toward broad detection (cursor,
+// opencode, gemini included), the app toward the user's real surfaces, and
+// custom/overridden agents flow through config (delta 4) on both sides. If you
+// add/remove an id here, decide deliberately whether the app list should follow
+// — see the matching comment over AGENT_SEEDS in app/src/lib/agents.ts.
 const AGENT_SEEDS: AgentSeed[] = [
   { id: "claude", name: "Claude Code", short: "Claude" },
   { id: "codex", name: "Codex", short: "Codex" },
   { id: "cursor", name: "Cursor", short: "Cursor" },
   { id: "opencode", name: "OpenCode", short: "OpenCode" },
   { id: "gemini", name: "Gemini", short: "Gemini" },
-  { id: "omp", name: "Oh My Pi", short: "OMP" },
+  { id: "pi", name: "Pi", short: "Pi" },
 ];
 
 const AGENT_IDS = AGENT_SEEDS.map((a) => a.id);
@@ -105,9 +105,9 @@ export function agentIdForSurface(
   return agentIdForSurfaceCore(surface, ids);
 }
 
-/** Relative subdirectory under .<id>/ where skills live (agent/skills for omp, skills otherwise). */
+/** Relative subdirectory under .<id>/ where skills live (agent/skills for pi, skills otherwise). */
 function skillsSuffix(id: string): string {
-  return id === "omp" ? join("agent", "skills") : "skills";
+  return id === "pi" ? join("agent", "skills") : "skills";
 }
 
 /** Absolute path to an agent's global skills dir. */

package/src/core/surfaces.ts

@@ -37,7 +37,7 @@ export function knownAgentSurfaces(home: string = homedir()): AgentSurface[] {
     // matrix advertises must have its global surface scanned, or `installed`
     // can disagree with the (empty) matrix. See agents.test.ts coverage check.
     { agent: "gemini", path: join(home, ".gemini", "skills") },
-    { agent: "omp", path: join(home, ".omp", "agent", "skills") },
+    { agent: "pi", path: join(home, ".pi", "agent", "skills") },
   ];
 }
 

package/src/core/vendor.test.ts

@@ -49,7 +49,7 @@ async function makeStagedSkill(parent: string, name: string, body?: string): Pro
 function installOpts(libraryPath: string, over: Partial<InstallOptions> = {}): InstallOptions {
   return {
     libraryPath,
-    domainFolder: null,
+    domain: null,
     nameOverride: null,
     sourceStr: "github:owner/repo",
     ref: "abc123",
@@ -146,13 +146,14 @@ describe("vendor.installSkill — copy + provenance + verdict", () => {
     expect(o.reason).toContain("not overwriting");
   });
 
-  test("a domain folder lands the skill under it and tags the taxonomy", async () => {
+  test("--domain tags the taxonomy but the skill lands FLAT (ADR-0001: tags, not folders)", async () => {
     const skill = await makeStagedSkill(tmp, "foo");
-    const o = await installSkill(skill, installOpts(library, { domainFolder: "data" }));
+    const o = await installSkill(skill, installOpts(library, { domain: "data" }));
     expect(o.status).toBe("installed");
-    expect(o.path).toBe(join(library, "data", "foo"));
+    expect(o.path).toBe(join(library, "foo"));
     expect(o.domains).toEqual(["data"]);
-    expect(existsSync(join(library, "data", "foo", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(library, "foo", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(library, "data"))).toBe(false);
   });
 
   test("nameOverride renames the install slug", async () => {
@@ -214,16 +215,18 @@ describe("vendor.installSkill — guard suite", () => {
     expect(devBody).toContain("DEV REPO");
   });
 
-  test("multi mode skips a write through a symlinked DOMAIN folder (ancestor escape)", async () => {
-    // <library>/ext -> /external; installing under --domain ext must not write through it.
+  test("--domain never routes the write through a same-named symlinked dir (regression: flat layout)", async () => {
+    // <library>/ext -> /external. Pre-ADR-0001 leftovers made --domain ext write into
+    // library/ext/foo (through the symlink); flat layout must land at library/foo.
     const external = join(tmp, "external");
     await mkdir(external, { recursive: true });
     await symlink(external, join(library, "ext"));
 
     const skill = await makeStagedSkill(tmp, "foo");
-    const o = await installSkill(skill, installOpts(library, { domainFolder: "ext", multi: true }));
-    expect(o.status).toBe("skipped");
-    expect(o.reason).toContain("symlink");
+    const o = await installSkill(skill, installOpts(library, { domain: "ext", multi: true }));
+    expect(o.status).toBe("installed");
+    expect(o.path).toBe(join(library, "foo"));
+    expect(o.domains).toEqual(["ext"]);
     expect(existsSync(join(external, "foo"))).toBe(false);
   });
 });
@@ -241,9 +244,8 @@ describe("vendor guard primitives (pure-ish, fs-anchored)", () => {
     await rm(tmp, { recursive: true, force: true });
   });
 
-  test("destDirFor honors the optional domain folder", () => {
-    expect(destDirFor("/lib", null, "foo")).toBe(join("/lib", "foo"));
-    expect(destDirFor("/lib", "data", "foo")).toBe(join("/lib", "data", "foo"));
+  test("destDirFor is always flat under the library root", () => {
+    expect(destDirFor("/lib", "foo")).toBe(join("/lib", "foo"));
   });
 
   test("nearestExisting climbs to the closest on-disk ancestor", () => {

package/src/core/vendor.ts

@@ -59,9 +59,9 @@ export function bodyOf(text: string): string {
 // GUARD SUITE — the checks every library-write path funnels through, ONCE.
 // ---------------------------------------------------------------------------
 
-/** The library destination dir for a slug (under its domain folder, if any). */
-export function destDirFor(libraryPath: string, domainFolder: string | null, name: string): string {
-  return domainFolder ? join(libraryPath, domainFolder, name) : join(libraryPath, name);
+/** The library destination dir for a slug — always flat `library/<name>` (ADR-0001). */
+export function destDirFor(libraryPath: string, name: string): string {
+  return join(libraryPath, name);
 }
 
 /** The nearest ancestor of `p` (incl. `p`) that exists on disk; falls back to `p`. */
@@ -78,7 +78,7 @@ export function nearestExisting(p: string): string {
 /**
  * True if writing to `destDir` would resolve OUTSIDE the library — i.e. the nearest
  * existing component on the way to destDir is (or is reached through) a symlink whose
- * realpath escapes the library. Catches a symlinked DOMAIN folder (`library/<d> ->
+ * realpath escapes the library. Catches a symlinked ancestor dir (`library/<d> ->
  * /external`) that the leaf-only `isSymlink(destDir)` check misses, so `--force` can't
  * clobber an external tree through a symlinked parent (ADR-0004). Both sides anchor to
  * their nearest existing ancestor, so a fresh (not-yet-created) library is not a false
@@ -93,8 +93,8 @@ export function destEscapesLibrary(libraryPath: string, destDir: string): boolea
 /**
  * The symlink-escape guard: would writing `destDir` go THROUGH a symlink into something
  * the library doesn't own — a LINKED leaf entry, OR a destination reached through a
- * symlinked ANCESTOR (e.g. a symlinked --domain folder) whose realpath escapes the
- * library? Writing through either clobbers an external dev repo, even with --force
+ * symlinked ANCESTOR whose realpath escapes the library? Writing through either
+ * clobbers an external dev repo, even with --force
  * (ADR-0004). The two add/dry-run sites that combined `isSymlink(destDir) ||
  * destEscapesLibrary(...)` inline now share this one predicate.
  */
@@ -108,8 +108,8 @@ export function writesThroughSymlink(libraryPath: string, destDir: string): bool
  * beside a tombstone would strand a duplicate and break `skl unretire`, so add/import/
  * link all refuse it regardless of --force (force overwrites an ACTIVE copy, not a
  * retired one). Each command keeps its own bespoke error wording + exit handling; this
- * is the shared PREDICATE they all branch on. Checked against the flat library root
- * (retirement is never under a domain folder); name-validated via entryStatus.
+ * is the shared PREDICATE they all branch on. Checked against the flat library root;
+ * name-validated via entryStatus.
  */
 export function isRetiredOnly(libraryPath: string, name: string): boolean {
   const status = entryStatus(libraryPath, name);
@@ -179,7 +179,8 @@ async function maybeInferTags(
 
 export interface InstallOptions {
   libraryPath: string;
-  domainFolder: string | null;
+  /** taxonomy tag to apply after install — never a folder (ADR-0001) */
+  domain: string | null;
   /** single-skill --name override; ignored in multi mode */
   nameOverride: string | null;
   /** per-skill lockfile `source` string (already carries the @subpath / #subpath) */
@@ -258,7 +259,7 @@ export async function installSkill(
   // (<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).
+  // Checked against the flat library root.
   if (isRetiredOnly(opts.libraryPath, rawName)) {
     return {
       ...base,
@@ -268,14 +269,14 @@ export async function installSkill(
     };
   }
 
-  const destDir = destDirFor(opts.libraryPath, opts.domainFolder, rawName);
+  const destDir = destDirFor(opts.libraryPath, rawName);
   const verdict = await driftVerdict(skill, destDir);
   base.verdict = verdict;
 
   // Never copy THROUGH a symlink into something the library doesn't own: a LINKED leaf
-  // entry, OR a destination reached through a symlinked ANCESTOR (e.g. a symlinked
-  // --domain folder) whose realpath escapes the library. Writing through either would
-  // clobber an external dev repo, even with --force (ADR-0004).
+  // entry, OR a destination reached through a symlinked ANCESTOR whose realpath escapes
+  // the library. Writing through either would clobber an external dev repo, even with
+  // --force (ADR-0004).
   const throughSymlink = writesThroughSymlink(opts.libraryPath, destDir);
 
   if (opts.multi) {
@@ -308,7 +309,7 @@ export async function installSkill(
   }
 
   // ---- write into the library ----
-  await ensureDir(opts.domainFolder ? join(opts.libraryPath, opts.domainFolder) : opts.libraryPath);
+  await ensureDir(opts.libraryPath);
   await copySkillDir(skill.dir, destDir);
 
   const installedBody = bodyOf(await readSkillBody(skill.dir));
@@ -327,8 +328,8 @@ export async function installSkill(
   const installed: Skill = {
     name: rawName,
     description: skill.description,
-    primaryDomain: opts.domainFolder,
-    domains: opts.domainFolder ? [opts.domainFolder] : [],
+    primaryDomain: opts.domain,
+    domains: opts.domain ? [opts.domain] : [],
     path: destDir,
     bodyPath: join(destDir, "SKILL.md"),
     refFiles: [],
@@ -337,14 +338,14 @@ export async function installSkill(
     mirrorOf: null,
     contentHash: "",
   };
-  if (opts.domainFolder) await setDomainsForName(opts.libraryPath, rawName, [opts.domainFolder]);
+  if (opts.domain) await setDomainsForName(opts.libraryPath, rawName, [opts.domain]);
 
   let inferred: string[] | null = null;
   if (opts.infer) {
     inferred = await maybeInferTags(installed, warn);
     if (inferred && inferred.length > 0) await setDomainsForName(opts.libraryPath, rawName, inferred);
   }
-  const domains = inferred && inferred.length > 0 ? inferred : opts.domainFolder ? [opts.domainFolder] : [];
+  const domains = inferred && inferred.length > 0 ? inferred : opts.domain ? [opts.domain] : [];
 
   return {
     ...base,