skillshelf 0.2.0 → 0.4.0

package/src/commands/import.ts

@@ -19,26 +19,26 @@
 //   --force         overwrite an existing same-named library skill
 //
 // Provenance: these are the user's OWN skills, not third-party — source is null and
-// NO lockfile entry is written (that is `add`'s job). We still create an EMPTY
-// overlay (<name>.shelf.json) so taxonomy can be applied later without clobbering
-// the upstream SKILL.md.
+// NO lockfile entry is written (that is `add`'s job). Import is purely mechanical
+// (move + symlink-back, or --copy); domain tags are applied later by `skl infer`
+// into the central <library>/taxonomy.json, which never touches the SKILL.md body.
 
 import { join, basename, resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { rename, cp, rm } from "node:fs/promises";
-import type { Ctx, Skill } from "../types.ts";
-import { writeOverlay } from "../core/overlay.ts";
+import type { Ctx } from "../types.ts";
 import {
   ensureDir,
   safeSymlink,
   isDirectory,
+  isSymlink,
   realpathOrSelfAsync,
 } from "../lib/fs.ts";
 
 export const meta = {
   name: "import",
   summary: "Adopt your own skill into the library (move + symlink-back, or --copy)",
-  usage: "skl import <name> --from <path> [--copy | --no-link-back] [--as <slug>] [--force] [--json]",
+  usage: "skl import <name> --from <path> [--copy | --no-link-back] [--follow] [--as <slug>] [--force] [--json]",
 } as const;
 
 interface Flags {
@@ -47,6 +47,7 @@ interface Flags {
   as: string | null;
   copy: boolean;
   noLinkBack: boolean;
+  follow: boolean;
   force: boolean;
   json: boolean;
 }
@@ -60,6 +61,7 @@ function parseFlags(argv: string[]): { flags: Flags } | { error: string } {
     as: null,
     copy: false,
     noLinkBack: false,
+    follow: false,
     force: false,
     json: false,
   };
@@ -81,6 +83,8 @@ function parseFlags(argv: string[]): { flags: Flags } | { error: string } {
       flags.copy = true;
     } else if (a === "--no-link-back" || a === "--no-link") {
       flags.noLinkBack = true;
+    } else if (a === "--follow" || a === "--deref") {
+      flags.follow = true;
     } else if (a === "--force") {
       flags.force = true;
     } else if (a === "--json") {
@@ -141,6 +145,12 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     );
     return 1;
   }
+  if (flags.follow && flags.noLinkBack) {
+    ctx.error(
+      "skl import: --follow copies the dereferenced target; it cannot be combined with --no-link-back (a move option)",
+    );
+    return 1;
+  }
 
   // The library name is --as if given, else <name>.
   const targetName = (flags.as ?? flags.name).trim();
@@ -171,6 +181,23 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
       return 1;
     }
 
+    // Symlink safety (option b): a symlinked source dir is refused unless --follow.
+    // Without it, a move would `rename` the LINK (the library would point back at the
+    // target and own no real copy) and a copy would copy the link itself. With
+    // --follow we dereference to the real target and COPY its contents (below).
+    const linkSource = isSymlink(fromPath);
+    if (linkSource && !flags.follow) {
+      const tgt = await realpathOrSelfAsync(fromPath);
+      ctx.error(`skl import: --from is a symlink (${fromPath} -> ${tgt}).`);
+      ctx.error(
+        "Refusing to import a symlink source: a move would relocate the link, not the content.",
+      );
+      ctx.error(
+        "Re-run with --follow (alias --deref) to dereference and copy the target's real contents into the library.",
+      );
+      return 1;
+    }
+
     const libraryPath = ctx.config.libraryPath;
     // Flat, non-semantic layout (ADR-0001): always <library>/<name>/.
     const destDir = join(libraryPath, targetName);
@@ -202,12 +229,15 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
       await rm(destDir, { recursive: true, force: true });
     }
 
-    const mode: "move" | "copy" = flags.copy ? "copy" : "move";
+    // A symlinked source with --follow: copy the dereferenced TARGET's contents
+    // (never move — that would relocate the canonical store the link points at).
+    const srcDir = linkSource ? await realpathOrSelfAsync(fromPath) : fromPath;
+    const mode: "move" | "copy" = linkSource ? "copy" : flags.copy ? "copy" : "move";
     let linkedBack = false;
 
     if (mode === "copy") {
       // Copy into the library; leave the original untouched (no symlink-back).
-      await cp(fromPath, destDir, {
+      await cp(srcDir, destDir, {
         recursive: true,
         force: true,
         filter: (s: string) => basename(s) !== ".git",
@@ -233,26 +263,10 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
       }
     }
 
-    // Empty overlay so taxonomy (domains/bundles) can be applied later via
-    // `skl infer` without touching the upstream SKILL.md. These are the user's own
-    // skills: source/provenance is null and NO lockfile entry is written.
-    const imported: Skill = {
-      name: targetName,
-      description: "",
-      primaryDomain: null,
-      domains: [],
-      path: destDir,
-      bodyPath: join(destDir, "SKILL.md"),
-      refFiles: [],
-      source: null,
-      retired: false,
-      mirrorOf: null,
-      contentHash: "",
-    };
-    const overlayPathStr = join(destDir, `${targetName}.shelf.json`);
-    if (!existsSync(overlayPathStr)) {
-      await writeOverlay(imported, {});
-    }
+    // Import is mechanical: no domain is decided here. Domain tags are applied
+    // later via `skl infer` into the central <library>/taxonomy.json — never into
+    // the upstream SKILL.md. These are the user's own skills: source/provenance is
+    // null and NO lockfile entry is written.
 
     const summary = {
       ok: true,
@@ -261,6 +275,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
       to: destDir,
       mode,
       linkedBack,
+      followed: linkSource,
     };
 
     if (flags.json) {
@@ -268,6 +283,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     } else {
       ctx.log(`imported ${targetName}`);
       ctx.log(`  from:  ${fromPath}`);
+      if (linkSource) ctx.log(`  follow: ${fromPath} -> ${srcDir} (copied target contents)`);
       ctx.log(`  to:    ${destDir}`);
       ctx.log(`  mode:  ${mode}`);
       if (linkedBack) ctx.log(`  link:  ${fromPath} -> ${destDir} (old path still resolves)`);

package/src/commands/infer.ts

@@ -3,8 +3,8 @@
 // Dual-mode, LLM-FREE core:
 //   skl infer --emit                 print {instruction, schema, corpus} for a
 //                                    host agent to reason over (no LLM call here).
-//   skl infer --apply <file.json>    write the agent's proposal into each skill's
-//                                    <name>.shelf.json overlay (never upstream).
+//   skl infer --apply <file.json>    write the agent's proposal into the central
+//                                    taxonomy.json (never upstream SKILL.md).
 //   skl infer --provider openai      API mode: POST the corpus to an
 //                                    OpenAI-compatible endpoint and apply the
 //                                    strict-JSON result automatically.
@@ -164,7 +164,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         ctx.error("skl infer: proposal contained no assignments");
         return 1;
       }
-      const result = await applyProposal(skills, proposal);
+      const result = await applyProposal(ctx.libraryPath, skills, proposal);
       return reportApply(result, args.json, ctx);
     }
 
@@ -193,7 +193,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         ctx.error("skl infer: gateway returned no assignments");
         return 1;
       }
-      const result = await applyProposal(skills, inferred.proposal);
+      const result = await applyProposal(ctx.libraryPath, skills, inferred.proposal);
       return reportApply(result, args.json, ctx, prov.config.name, prov.config.model);
     }
 
@@ -227,7 +227,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     ctx.error(
       "skl infer: no inference mode available. Provide one of:\n" +
         "  --emit                 print corpus for a host agent to reason over\n" +
-        "  --apply <file.json>    apply an agent proposal into overlays\n" +
+        "  --apply <file.json>    apply an agent proposal into taxonomy.json\n" +
         `  --provider <name>      call an OpenAI-compatible endpoint (${knownProviders().join(", ")})\n` +
         "  --base-url <url>       call a custom OpenAI-compatible endpoint\n" +
         "(auto-emit only activates inside a Claude Code agent context.)",
@@ -268,7 +268,7 @@ function reportApply(
     ctx.log(`  ${a.name}: ${a.domains.join(", ")}${addedNote}`);
   }
   ctx.log(
-    `Applied ${result.applied.length} overlay update${
+    `Applied ${result.applied.length} taxonomy update${
       result.applied.length === 1 ? "" : "s"
     }.`,
   );

package/src/commands/link.test.ts

@@ -0,0 +1,160 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, readFile, rm, lstat, readlink, realpath } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run } from "./link.ts";
+import type { Ctx } from "../types.ts";
+
+const BODY = "---\nname: claim-log\ndescription: a test skill\n---\n\nbody\n";
+
+async function makeSkillDir(parent: string, name: string, body = BODY): Promise<string> {
+  const dir = join(parent, name);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, "SKILL.md"), body);
+  return dir;
+}
+
+interface Captured {
+  ctx: Ctx;
+  logs: string[];
+  errors: string[];
+  json: unknown[];
+}
+
+/** Minimal Ctx mock — link.run only reads config.libraryPath + log/error/json. */
+function makeCtx(libraryPath: string): Captured {
+  const logs: string[] = [];
+  const errors: string[] = [];
+  const json: unknown[] = [];
+  const ctx = {
+    config: { libraryPath },
+    libraryPath,
+    log: (...a: unknown[]) => logs.push(a.join(" ")),
+    error: (...a: unknown[]) => errors.push(a.join(" ")),
+    json: (v: unknown) => json.push(v),
+  } as unknown as Ctx;
+  return { ctx, logs, errors, json };
+}
+
+describe("skl link --from (LINKED mode)", () => {
+  let tmp: string;
+  let library: string;
+  let devRepo: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-link-")));
+    library = join(tmp, "library");
+    devRepo = join(tmp, "dev");
+    await mkdir(library, { recursive: true });
+    await mkdir(devRepo, { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("registers a dev-repo skill as a library symlink", async () => {
+    const src = await makeSkillDir(devRepo, "claim-log");
+    const { ctx, json } = makeCtx(library);
+    const code = await run(["claim-log", "--from", src, "--json"], ctx);
+
+    expect(code).toBe(0);
+    const libEntry = join(library, "claim-log");
+    const st = await lstat(libEntry);
+    expect(st.isSymbolicLink()).toBe(true);
+    expect(await realpath(libEntry)).toBe(await realpath(src));
+    expect(json[0]).toMatchObject({ ok: true, name: "claim-log", mode: "linked", discarded: false });
+  });
+
+  test("derives the name from the dev-repo dir basename when omitted", async () => {
+    const src = await makeSkillDir(devRepo, "claim-log");
+    const { ctx } = makeCtx(library);
+    const code = await run(["--from", src], ctx);
+
+    expect(code).toBe(0);
+    const libEntry = join(library, "claim-log");
+    expect((await lstat(libEntry)).isSymbolicLink()).toBe(true);
+    expect(await realpath(libEntry)).toBe(await realpath(src));
+  });
+
+  test("is idempotent — re-running reports 'already'", async () => {
+    const src = await makeSkillDir(devRepo, "claim-log");
+    const { ctx } = makeCtx(library);
+    await run(["claim-log", "--from", src], ctx);
+
+    const { ctx: ctx2, json } = makeCtx(library);
+    const code = await run(["claim-log", "--from", src, "--json"], ctx2);
+    expect(code).toBe(0);
+    expect(json[0]).toMatchObject({ status: "already", mode: "linked" });
+  });
+
+  test("refuses to clobber an existing owned library copy without --force", async () => {
+    await makeSkillDir(library, "claim-log"); // a real OWNED copy already in the library
+    const src = await makeSkillDir(devRepo, "claim-log");
+    const { ctx, errors } = makeCtx(library);
+
+    const code = await run(["claim-log", "--from", src], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("already exists in the library");
+    // unchanged: still a real dir, not a symlink
+    expect((await lstat(join(library, "claim-log"))).isSymbolicLink()).toBe(false);
+  });
+
+  test("--force replaces an owned copy with the symlink and reports discarded", async () => {
+    await makeSkillDir(library, "claim-log");
+    const src = await makeSkillDir(devRepo, "claim-log");
+    const { ctx, json } = makeCtx(library);
+
+    const code = await run(["claim-log", "--from", src, "--force", "--json"], ctx);
+    expect(code).toBe(0);
+    expect((await lstat(join(library, "claim-log"))).isSymbolicLink()).toBe(true);
+    expect(json[0]).toMatchObject({ discarded: true, mode: "linked" });
+  });
+
+  test("drops a stale lockfile entry so update/outdated skip the now-LINKED skill", async () => {
+    // An owned import existed (real copy + a github lock entry); now convert to LINKED.
+    await makeSkillDir(library, "claim-log");
+    await writeFile(
+      join(library, "shelf.lock.json"),
+      JSON.stringify({
+        version: 1,
+        entries: {
+          "claim-log": { name: "claim-log", source: "github:owner/repo", ref: "abc", channel: "github", installedAt: "2020-01-01T00:00:00.000Z", localEdits: false },
+        },
+      }),
+    );
+    const src = await makeSkillDir(devRepo, "claim-log");
+    const { ctx } = makeCtx(library);
+
+    const code = await run(["claim-log", "--from", src, "--force"], ctx);
+    expect(code).toBe(0);
+    const lock = JSON.parse(await readFile(join(library, "shelf.lock.json"), "utf8"));
+    expect(lock.entries["claim-log"]).toBeUndefined();
+  });
+
+  test("rejects --at and --from together", async () => {
+    const src = await makeSkillDir(devRepo, "claim-log");
+    const { ctx, errors } = makeCtx(library);
+    const code = await run(["claim-log", "--from", src, "--at", "/tmp/x"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("mutually exclusive");
+  });
+
+  test("refuses a --from source inside the library", async () => {
+    const inside = await makeSkillDir(library, "claim-log");
+    const { ctx, errors } = makeCtx(library);
+    const code = await run(["other", "--from", inside], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("inside the library");
+  });
+
+  test("refuses a --from dir with no SKILL.md", async () => {
+    const bare = join(devRepo, "bare");
+    await mkdir(bare, { recursive: true });
+    const { ctx, errors } = makeCtx(library);
+    const code = await run(["bare", "--from", bare], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("no SKILL.md");
+    expect(existsSync(join(library, "bare"))).toBe(false);
+  });
+});

package/src/commands/link.ts

@@ -0,0 +1,317 @@
+// `skl link` — manage the symlink relationship between the library and on-disk copies.
+//
+// Two modes (the bookshelf model, ADR-0004):
+//
+//   skl link <name> --at <path>          OWNED side. The library already owns <name>; replace
+//                                        some other on-disk copy at <path> with a symlink INTO
+//                                        the library — fulfilling the one-canonical-copy rule for
+//                                        locations that were never consolidated (e.g. an old
+//                                        `.claude/skills/<name>` duplicate).
+//
+//   skl link [<name>] --from <dev-repo>  LINKED side. Register an external dev-repo skill as a
+//                                        library entry: make <library>/<name> a symlink pointing
+//                                        AT the dev repo, which stays canonical. The inverse of
+//                                        --at — the library shelves a reference instead of owning
+//                                        the bytes (for skills you actively develop in their own
+//                                        git repo). Name defaults to the dev-repo dir's basename.
+//
+//   --force   --at:   replace even if <path>'s body differs from the library copy (the divergent
+//                     copy is DISCARDED). Without it, a content mismatch is refused — pick a
+//                     winner: keep library (this, with --force) or make <path> canonical
+//                     (`skl import <name> --from <path> --force`).
+//             --from: replace an existing library entry (its current contents are DISCARDED).
+//   --json    machine-readable summary.
+//
+// Safety: --at never touches the library copy and refuses paths inside the library; --from
+// refuses a source inside the library; both verify the resulting symlink resolves as intended and
+// are idempotent when the link already points where intended.
+
+import { join, resolve, basename } from "node:path";
+import { existsSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import type { Ctx } from "../types.ts";
+import { parseFrontmatter } from "../lib/frontmatter.ts";
+import { removeEntry } from "../core/provenance.ts";
+import {
+  isDirectory,
+  isSymlink,
+  safeSymlink,
+  realpathOrSelfAsync,
+} from "../lib/fs.ts";
+
+export const meta = {
+  name: "link",
+  summary: "Link a skill to the library: collapse a copy (--at) or shelve a dev repo (--from)",
+  usage: "skl link <name> --at <path>  |  skl link [<name>] --from <dev-repo>  [--force] [--json]",
+} as const;
+
+interface Flags {
+  name: string | null;
+  at: string | null;
+  from: string | null;
+  force: boolean;
+  json: boolean;
+}
+
+function parseFlags(argv: string[]): { flags: Flags } | { error: string } {
+  const flags: Flags = { name: null, at: null, from: null, force: false, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--at") {
+      const v = argv[++i];
+      if (v === undefined) return { error: "--at requires a <path>" };
+      flags.at = v;
+    } else if (a.startsWith("--at=")) {
+      flags.at = a.slice("--at=".length);
+    } else if (a === "--from") {
+      const v = argv[++i];
+      if (v === undefined) return { error: "--from requires a <dev-repo path>" };
+      flags.from = v;
+    } else if (a.startsWith("--from=")) {
+      flags.from = a.slice("--from=".length);
+    } else if (a === "--force") {
+      flags.force = true;
+    } else if (a === "--json") {
+      flags.json = true;
+    } else if (a.startsWith("--")) {
+      return { error: `unknown argument: ${a}` };
+    } else if (flags.name === null) {
+      flags.name = a;
+    } else {
+      return { error: `unexpected argument: ${a}` };
+    }
+  }
+  return { flags };
+}
+
+/** sha-256 of a SKILL.md body (frontmatter stripped) — matches crawl/dedupe hashing. */
+async function bodyHash(skillMdPath: string): Promise<string | null> {
+  if (!existsSync(skillMdPath)) return null;
+  try {
+    const raw = await Bun.file(skillMdPath).text();
+    const { body } = parseFrontmatter(raw);
+    return createHash("sha256").update(body, "utf8").digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const parsed = parseFlags(argv);
+  if ("error" in parsed) {
+    ctx.error(`skl link: ${parsed.error}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const flags = parsed.flags;
+
+  if (flags.at && flags.from) {
+    ctx.error("skl link: --at and --from are mutually exclusive (collapse a copy vs. shelve a dev repo)");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  if (!flags.at && !flags.from) {
+    ctx.error("skl link: one of --at <path> or --from <dev-repo> is required");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+
+  return flags.from
+    ? await runFrom(flags, ctx)
+    : await runAt(flags, ctx);
+}
+
+/**
+ * LINKED mode: register an external dev-repo skill as a library symlink. The library entry
+ * <library>/<name> becomes a symlink pointing AT the dev repo (which stays canonical).
+ */
+async function runFrom(flags: Flags, ctx: Ctx): Promise<number> {
+  const fromPath = resolve(flags.from!.trim());
+  const name = (flags.name?.trim()) || basename(fromPath);
+  if (!name || name === "." || name === "/") {
+    ctx.error("skl link: could not determine a <name> — pass one explicitly");
+    return 1;
+  }
+  const libraryPath = ctx.config.libraryPath;
+  const libDir = join(libraryPath, name);
+
+  try {
+    // The source must be a real skill dir (has a SKILL.md).
+    if (!existsSync(fromPath) || !(await isDirectory(fromPath))) {
+      ctx.error(`skl link: --from must be an existing directory: ${fromPath}`);
+      return 1;
+    }
+    if (!existsSync(join(fromPath, "SKILL.md"))) {
+      ctx.error(`skl link: ${fromPath} has no SKILL.md (not a skill dir).`);
+      return 1;
+    }
+
+    // Refuse a source inside the library — that would link the library to itself.
+    const fromReal = await realpathOrSelfAsync(fromPath);
+    const libRoot = await realpathOrSelfAsync(libraryPath);
+    if (fromReal === libRoot || fromReal.startsWith(libRoot + "/")) {
+      ctx.error(`skl link: --from is inside the library (${fromPath}) — nothing to register`);
+      return 1;
+    }
+
+    // Idempotent: library entry is already a symlink resolving to this source.
+    if (isSymlink(libDir)) {
+      const cur = await realpathOrSelfAsync(libDir);
+      if (cur === fromReal) {
+        const summary = { ok: true, name, from: fromPath, to: libDir, status: "already" as const, mode: "linked" as const, discarded: false };
+        if (flags.json) ctx.json(summary);
+        else ctx.log(`link: library/${name} already points at ${fromPath}`);
+        return 0;
+      }
+    }
+
+    // An existing library entry won't be clobbered silently.
+    const exists = existsSync(libDir) || isSymlink(libDir);
+    if (exists && !flags.force) {
+      ctx.error(`skl link: '${name}' already exists in the library (${libDir}).`);
+      ctx.error("Pass --force to replace it with a symlink to the dev repo (its current contents are discarded).");
+      return 1;
+    }
+    const discarded = exists && !isSymlink(libDir); // a real OWNED copy is being dropped
+    if (exists) await rm(libDir, { recursive: true, force: true });
+    await safeSymlink(fromPath, libDir, { force: true });
+
+    // Verify the library entry resolves to the dev repo.
+    const linkReal = await realpathOrSelfAsync(libDir);
+    if (linkReal !== fromReal) {
+      ctx.error(`skl link: verification failed — library/${name} resolves to ${linkReal}, expected ${fromReal}`);
+      return 1;
+    }
+
+    // A LINKED entry is not a tracked github import — drop any stale lock entry so
+    // `skl update`/`outdated` never try to pull upstream into the dev repo (ADR-0004).
+    await removeEntry(libraryPath, name);
+
+    const summary = { ok: true, name, from: fromPath, to: libDir, status: "linked" as const, mode: "linked" as const, discarded };
+    if (flags.json) {
+      ctx.json(summary);
+    } else {
+      ctx.log(`shelved ${name} -> ${fromPath} (LINKED)`);
+      if (discarded) ctx.log("  (discarded the previous owned library copy; library now points at the dev repo)");
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`skl link: failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}
+
+/**
+ * OWNED mode: replace a redundant on-disk copy at <path> with a symlink INTO the library copy
+ * the library already owns.
+ */
+async function runAt(flags: Flags, ctx: Ctx): Promise<number> {
+  if (!flags.name || flags.name.trim() === "") {
+    ctx.error("skl link: a <name> is required with --at");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+
+  const name = flags.name.trim();
+  const atPath = resolve(flags.at!.trim());
+  const libraryPath = ctx.config.libraryPath;
+  const libDir = join(libraryPath, name);
+
+  try {
+    // The library must already own this skill — link points AT the canonical copy.
+    if (!existsSync(libDir) || !existsSync(join(libDir, "SKILL.md"))) {
+      ctx.error(
+        `skl link: '${name}' is not in the library (${libDir}). Import it first with \`skl import\`.`,
+      );
+      return 1;
+    }
+
+    const libReal = await realpathOrSelfAsync(libDir);
+
+    // Idempotent: already a symlink resolving to the library copy.
+    if (isSymlink(atPath)) {
+      const cur = await realpathOrSelfAsync(atPath);
+      if (cur === libReal) {
+        const summary = { ok: true, name, at: atPath, to: libDir, status: "already" as const, discarded: false };
+        if (flags.json) ctx.json(summary);
+        else ctx.log(`link: ${atPath} already points at the library copy of ${name}`);
+        return 0;
+      }
+    }
+
+    // Safety: never operate on the library copy itself or anything inside the library.
+    const atReal = await realpathOrSelfAsync(atPath);
+    if (atReal === libReal) {
+      ctx.error(`skl link: --at is the library copy itself (${atPath}) — nothing to do`);
+      return 1;
+    }
+    const libRoot = await realpathOrSelfAsync(libraryPath);
+    if (atReal === libRoot || atReal.startsWith(libRoot + "/")) {
+      ctx.error(`skl link: refusing to operate on a path inside the library (${atPath})`);
+      return 1;
+    }
+
+    // If the target exists as a real dir, require it to look like a skill and compare
+    // content. A body mismatch means a real decision the tool won't make silently.
+    if (existsSync(atPath) && !isSymlink(atPath)) {
+      if (!(await isDirectory(atPath))) {
+        ctx.error(`skl link: --at must be a directory (the redundant copy): ${atPath}`);
+        return 1;
+      }
+      const atSkillMd = join(atPath, "SKILL.md");
+      if (!existsSync(atSkillMd) && !flags.force) {
+        ctx.error(
+          `skl link: ${atPath} has no SKILL.md (not a skill dir). Pass --force to replace it anyway.`,
+        );
+        return 1;
+      }
+      if (existsSync(atSkillMd) && !flags.force) {
+        const [a, b] = await Promise.all([
+          bodyHash(atSkillMd),
+          bodyHash(join(libDir, "SKILL.md")),
+        ]);
+        if (a !== b) {
+          ctx.error(
+            `skl link: ${atPath} differs from the library copy of '${name}'.`,
+          );
+          ctx.error(
+            "Pass --force to discard the divergent copy and replace it with a symlink,",
+          );
+          ctx.error(
+            `or make this copy canonical instead: \`skl import ${name} --from ${atPath} --force\`.`,
+          );
+          return 1;
+        }
+      }
+    }
+
+    // Replace the redundant copy with a symlink into the library.
+    const discarded = existsSync(atPath) && !isSymlink(atPath);
+    if (existsSync(atPath) || isSymlink(atPath)) {
+      await rm(atPath, { recursive: true, force: true });
+    }
+    await safeSymlink(libDir, atPath, { force: true });
+
+    // Verify the link resolves to the library copy.
+    const linkReal = await realpathOrSelfAsync(atPath);
+    if (linkReal !== libReal) {
+      ctx.error(
+        `skl link: verification failed — ${atPath} resolves to ${linkReal}, expected ${libReal}`,
+      );
+      return 1;
+    }
+
+    const summary = { ok: true, name, at: atPath, to: libDir, status: "linked" as const, discarded };
+    if (flags.json) {
+      ctx.json(summary);
+    } else {
+      ctx.log(`linked ${basename(atPath)} -> ${libDir}`);
+      if (discarded) ctx.log("  (discarded the redundant copy; old path now resolves to the library)");
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`skl link: failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}