paperlint 2.0.0

package/src/link-skills.harness.mjs

@@ -0,0 +1,273 @@
+/**
+ * Both halves for `link-skills.ts` — the symlinks that make the shipped skills visible to Claude
+ * Code at `.claude/skills/<name>`.
+ *
+ * 🔴 WHY THE PACKAGE IS BUILT ON DISK HERE, NOT FAKED. What is under test is a property of a tree:
+ * whether Node resolves the package from the project, which spelling of it the link uses, and
+ * whether `SKILL.md` is reachable THROUGH the link. A stubbed locator would test the stub. So each
+ * case lays out a real `node_modules` — the npm shape and the pnpm shape, where
+ * `node_modules/<package>` is itself a symlink into a version-stamped store
+ * directory — and asks the filesystem.
+ *
+ * The fixture package keeps its skills where the real one does, under `SHIPPED_SKILLS_DIR` from
+ * consumer.mjs — the same constant the linker and the install e2e read.
+ *
+ * Run:    node src/link-skills.harness.mjs
+ * Killed by: src/link-skills.mutations.mjs
+ */
+import assert from "node:assert/strict";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const { linkSkills, locatePackage, shippedSkills } = await import(
+  join(HERE, "link-skills.ts")
+);
+const {
+  SHIPPED_SKILLS_DIR: SHIPS,
+  PACKAGE_NAME: PKG,
+  LEGACY_PACKAGE_NAME,
+} = await import(
+  join(HERE, "..", "skills", "paper-pipeline", "scripts", "consumer.mjs")
+);
+
+let n = 0;
+const check = (label, cond) => {
+  n++;
+  assert.ok(cond, label);
+};
+
+const SKILLS = ["alpha", "beta", "gamma"];
+const work = realpathSync(mkdtempSync(join(tmpdir(), "rpp-link-skills-")));
+
+/** A package as a manager would unpack it: manifest, skills, one non-skill. */
+function writePackage(dir) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify({ name: PKG, version: "1.0.0" }),
+  );
+  for (const s of SKILLS) {
+    mkdirSync(join(dir, SHIPS, s, "scripts"), { recursive: true });
+    writeFileSync(join(dir, SHIPS, s, "SKILL.md"), `---\nname: ${s}\n---\n`);
+    writeFileSync(join(dir, SHIPS, s, "scripts", "run.mjs"), "");
+  }
+  // A directory without SKILL.md and a loose file: neither is a skill.
+  mkdirSync(join(dir, SHIPS, "shared"), { recursive: true });
+  writeFileSync(join(dir, SHIPS, "README.md"), "# skills\n");
+}
+
+/** A consumer project with the package installed the npm way or the pnpm way. */
+function consumer(name, manager = "npm") {
+  const dir = join(work, name);
+  mkdirSync(join(dir, "node_modules"), { recursive: true });
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify({ name: "c", version: "1.0.0" }),
+  );
+  if (manager === "npm") writePackage(join(dir, "node_modules", PKG));
+  else if (manager === "pnpm") {
+    const store = join(
+      "node_modules",
+      ".pnpm",
+      `${PKG}@1.0.0`,
+      "node_modules",
+      PKG,
+    );
+    writePackage(join(dir, store));
+    symlinkSync(
+      join(".pnpm", `${PKG}@1.0.0`, "node_modules", PKG),
+      join(dir, "node_modules", PKG),
+      "dir",
+    );
+  }
+  return dir;
+}
+
+const home = (dir) => join(dir, ".claude", "skills");
+const status = (report, name) => report.links.find((l) => l.name === name);
+
+try {
+  // ── I. A FRESH npm CONSUMER: EVERY DECLARED SKILL IS LINKED, AND ONLY SKILLS ───────────
+  {
+    const dir = consumer("npm");
+    const r = linkSkills(dir);
+    check(
+      "🔴 it links every skill the package ships",
+      r.ok === true && SKILLS.every((s) => status(r, s)?.status === "created"),
+    );
+    check(
+      "and nothing that is not a skill — a directory without SKILL.md is not one",
+      r.links.length === SKILLS.length &&
+        !existsSync(join(home(dir), "shared")),
+    );
+    check(
+      "🔴 SKILL.md is reachable THROUGH the link, where Claude Code looks",
+      SKILLS.every((s) => existsSync(join(home(dir), s, "SKILL.md"))),
+    );
+    check(
+      "and a project-root-relative script path resolves from the project root",
+      existsSync(join(dir, ".claude", "skills", "beta", "scripts", "run.mjs")),
+    );
+    const target = readlinkSync(join(home(dir), "alpha"));
+    check(
+      "🔴 the link is RELATIVE — an absolute one breaks the moment the checkout moves",
+      !isAbsolute(target) &&
+        target === join("..", "..", "node_modules", PKG, SHIPS, "alpha"),
+    );
+  }
+
+  // ── II. A SECOND RUN CHANGES NOTHING ──────────────────────────────────────────────────
+  {
+    const dir = join(work, "npm");
+    const before = SKILLS.map((s) => readlinkSync(join(home(dir), s)));
+    const r = linkSkills(dir);
+    check(
+      "🔴 a second run reports every link as ALREADY present, not as a clash",
+      r.ok && SKILLS.every((s) => status(r, s)?.status === "present"),
+    );
+    check(
+      "and leaves the links byte for byte as they were",
+      SKILLS.every((s, i) => readlinkSync(join(home(dir), s)) === before[i]),
+    );
+  }
+
+  // ── III. A NAME THAT IS ALREADY TAKEN IS SOMEONE ELSE'S ───────────────────────────────
+  {
+    const dir = consumer("foreign");
+    mkdirSync(join(home(dir), "alpha"), { recursive: true });
+    writeFileSync(join(home(dir), "alpha", "SKILL.md"), "mine\n");
+    mkdirSync(join(dir, "elsewhere"), { recursive: true });
+    symlinkSync(join("..", "..", "elsewhere"), join(home(dir), "beta"), "dir");
+    symlinkSync(join("..", "..", "gone"), join(home(dir), "gamma"), "dir");
+    const r = linkSkills(dir);
+    check(
+      "🔴 a foreign DIRECTORY is left untouched, content and all",
+      readFileSync(join(home(dir), "alpha", "SKILL.md"), "utf8") === "mine\n",
+    );
+    check(
+      "a link that points ELSEWHERE is left pointing there",
+      readlinkSync(join(home(dir), "beta")) === join("..", "..", "elsewhere"),
+    );
+    check(
+      "a DANGLING link is not silently replaced either — it may be the consumer's",
+      readlinkSync(join(home(dir), "gamma")) === join("..", "..", "gone"),
+    );
+    check(
+      "and each one is reported by name, with WHAT is there",
+      status(r, "alpha")?.status === "foreign" &&
+        status(r, "alpha")?.reason === "a directory" &&
+        /^a link to /.test(status(r, "beta")?.reason ?? "") &&
+        /^a dangling link to /.test(status(r, "gamma")?.reason ?? ""),
+    );
+  }
+
+  // ── IV. pnpm: THE LINK GOES THROUGH THE PROJECT'S OWN SPELLING ─────────────────────────
+  {
+    const dir = consumer("pnpm", "pnpm");
+    const located = locatePackage(dir);
+    check(
+      "Node resolves the package to the version-stamped store directory",
+      !("error" in located) &&
+        located.dir.includes(join(".pnpm", `${PKG}@1.0.0`)),
+    );
+    const r = linkSkills(dir);
+    check(
+      "🔴 under pnpm the link goes through node_modules/<package>, not the .pnpm store — that one dangles on the next upgrade",
+      r.ok &&
+        readlinkSync(join(home(dir), "alpha")) ===
+          join("..", "..", "node_modules", PKG, SHIPS, "alpha"),
+    );
+    check(
+      "and SKILL.md is reachable through both hops",
+      SKILLS.every((s) => existsSync(join(home(dir), s, "SKILL.md"))),
+    );
+  }
+
+  // ── V. NOT INSTALLED IN THIS PROJECT — NOTHING IS LINKED, AND IT SAYS WHY ──────────────
+  {
+    const dir = consumer("bare", "none");
+    const r = linkSkills(dir);
+    check(
+      "a project that does not have the package gets an error, not links into somebody's cache",
+      r.ok === false && /does not resolve from/.test(r.error),
+    );
+    check("and nothing is created", !existsSync(join(dir, ".claude")));
+  }
+
+  // ── VI. doctor's READ WRITES NOTHING ───────────────────────────────────────────────────
+  {
+    const dir = consumer("readonly");
+    const r = linkSkills(dir, { write: false });
+    check(
+      "🔴 write:false reports every skill as missing and creates nothing — doctor only looks",
+      r.ok &&
+        SKILLS.every((s) => status(r, s)?.status === "missing") &&
+        !existsSync(home(dir)),
+    );
+  }
+
+  // ── VI-bis. LINKS LEFT BY AN INSTALL UNDER THE OLD NAME ARE REPLACED, NOT SKIPPED ─────
+  // After `npm rm research-paper-pipeline && npm i -D paperlint` every old link dangles. They are
+  // ours, spelled the way an older `init` wrote them, so the next `init` replaces them.
+  {
+    const dir = consumer("renamed");
+    mkdirSync(home(dir), { recursive: true });
+    const old = join(
+      "..",
+      "..",
+      "node_modules",
+      LEGACY_PACKAGE_NAME,
+      SHIPS,
+      "alpha",
+    );
+    symlinkSync(old, join(home(dir), "alpha"), "dir");
+    const seen = linkSkills(dir, { write: false });
+    check(
+      "doctor's read names a link into the old package name, with the command that fixes it",
+      status(seen, "alpha")?.status === "foreign" &&
+        /old name — `npx paperlint init` replaces it/.test(
+          status(seen, "alpha")?.reason ?? "",
+        ),
+    );
+    const r = linkSkills(dir);
+    check(
+      "🔴 init REPLACES it: status `replaced`, and SKILL.md is reachable through the new link",
+      status(r, "alpha")?.status === "replaced" &&
+        existsSync(join(home(dir), "alpha", "SKILL.md")) &&
+        readlinkSync(join(home(dir), "alpha")).includes(
+          join("node_modules", PKG),
+        ),
+    );
+  }
+
+  // ── VII. A PACKAGE WITHOUT ITS SKILLS DIRECTORY IS AN ERROR, NOT ZERO SKILLS ─────────
+  {
+    const pkg = join(work, "no-skills");
+    writePackage(pkg);
+    rmSync(join(pkg, SHIPS), { recursive: true, force: true });
+    const s = shippedSkills(pkg);
+    check(
+      "no skills directory — an error that names it, not an empty list",
+      "error" in s && s.error.includes(join(pkg, SHIPS)),
+    );
+  }
+} finally {
+  rmSync(work, { recursive: true, force: true });
+}
+
+console.log(
+  `✓ ${n} assertions passed — link-skills: the skills are where Claude Code looks`,
+);

package/src/link-skills.mutations.mjs

@@ -0,0 +1,136 @@
+/**
+ * Battery for `link-skills.ts`.
+ *
+ * Every case below reintroduces a way the skills stop being where Claude Code looks — or, worse,
+ * a way the linker destroys something the consumer made. Both fail silently in real life: a
+ * missing skill is simply absent from the listing, and a replaced directory is simply gone.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { runMutations } from "../lib/mutation-driver.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, "..");
+const SRC = join(HERE, "link-skills.ts");
+const HARNESS = join(HERE, "link-skills.harness.mjs");
+const CONSUMER = join(
+  ROOT,
+  "skills",
+  "paper-pipeline",
+  "scripts",
+  "consumer.mjs",
+);
+
+process.exit(
+  runMutations({
+    root: ROOT,
+    runner: "node",
+    cases: [
+      {
+        // The definition lives in the port since rpp#62 (`installedSkills` in consumer.mjs), so
+        // the defect is planted THERE and must still die in THIS harness — the evidence that the
+        // linker reads it through the shared function rather than through a copy of its own.
+        name: "any directory counts as a skill",
+        harness: HARNESS,
+        expect: "a directory without SKILL.md is not one",
+        disables:
+          "the definition of a skill. A helper directory beside the skills gets a link, and Claude " +
+          "Code lists an entry with no SKILL.md behind it",
+        edits: [
+          [
+            CONSUMER,
+            '    if (st.isDirectory() && existsSync(join(entry, "SKILL.md")))\n      names.push(name);',
+            "    if (st.isDirectory())\n      names.push(name);",
+          ],
+        ],
+      },
+      {
+        name: "the link is written absolute",
+        harness: HARNESS,
+        expect: "the link is RELATIVE",
+        disables:
+          "portability of the checkout. An absolute link works on the machine that ran init and " +
+          "dangles in every other clone, container and CI runner",
+        edits: [
+          [
+            SRC,
+            '    symlinkSync(target, entry, "dir");',
+            '    symlinkSync(resolve(dirname(entry), target), entry, "dir");',
+          ],
+        ],
+      },
+      {
+        name: "an existing correct link is not recognised",
+        harness: HARNESS,
+        expect: "a second run reports every link as ALREADY present",
+        disables:
+          "idempotency. Every re-run of init would report its own links as someone else's " +
+          "and tell the consumer to move them",
+        edits: [
+          [
+            SRC,
+            '    if (realpathSync(entry) === want) return { status: "present" };',
+            '    if (realpathSync(entry) === "") return { status: "present" };',
+          ],
+        ],
+      },
+      {
+        name: "a foreign entry is replaced instead of reported",
+        harness: HARNESS,
+        expect: "a foreign DIRECTORY is left untouched",
+        disables:
+          "the one promise that makes init safe to run on a real project: a consumer's own skill " +
+          "of the same name, or a link they aimed elsewhere, is deleted without a word",
+        edits: [
+          [
+            SRC,
+            '  unlinkSync,\n} from "node:fs";',
+            '  unlinkSync,\n  rmSync,\n} from "node:fs";',
+          ],
+          [
+            SRC,
+            "  if (!write || !fixable) {",
+            '  if (!write || seen.status === "present") {',
+          ],
+          [
+            SRC,
+            '    symlinkSync(target, entry, "dir");',
+            '    rmSync(entry, { recursive: true, force: true });\n    symlinkSync(target, entry, "dir");',
+          ],
+        ],
+      },
+      {
+        name: "the resolved store path is linked instead of the project's own spelling",
+        harness: HARNESS,
+        expect: "under pnpm the link goes through node_modules/<package>",
+        disables:
+          "the link surviving an upgrade under pnpm. The store directory carries the version in " +
+          "its name; the next install removes it and every skill link dangles until init is re-run",
+        edits: [
+          [
+            SRC,
+            "      if (realpathSync(candidate) === dir) return { dir, spelled: candidate };",
+            '      if (realpathSync(candidate) === "") return { dir, spelled: candidate };',
+          ],
+        ],
+      },
+      {
+        name: "doctor's read-only call writes links",
+        harness: HARNESS,
+        expect:
+          "write:false reports every skill as missing and creates nothing",
+        disables:
+          "the difference between looking and changing. `paperlint doctor` would quietly repair the " +
+          "state it is supposed to report, so the report can never show the gap",
+        edits: [
+          [SRC, "  if (!write || !fixable) {", "  if (!fixable) {"],
+          [
+            SRC,
+            "  if (write && shipped.names.length > 0) {",
+            "  if (shipped.names.length > 0) {",
+          ],
+        ],
+      },
+    ],
+  }),
+);

package/src/link-skills.ts

@@ -0,0 +1,258 @@
+/**
+ * Makes the shipped skills visible to Claude Code: one RELATIVE symlink per skill,
+ * `<project>/.claude/skills/<name> -> <the installed package>/skills/<name>`.
+ *
+ * 🔴 WHY THIS EXISTS. The README used to say the skills "sit in `node_modules/…/skills/` and Claude
+ * Code reads them from there". It does not: Claude Code discovers project skills in
+ * `.claude/skills/<name>/SKILL.md` (plus user and plugin skills), never inside `node_modules`. So a
+ * consumer who followed the install to the letter had no `/paper-pipeline` at all (Codex review on
+ * #45). A plugin could not carry them either — it gets no `node_modules`, and 23 of 24 skills run
+ * scripts (`docs/install.md`, "Why it is shaped this way"). The one consumer where the skills
+ * DID work had made these links by hand; this module makes the same links, so the layout is the
+ * proven one rather than a new one.
+ *
+ * The links are what make the project-root-relative script paths inside the skills
+ * (`.claude/skills/paper-pipeline/scripts/x.mjs`) resolve in a consumer at all.
+ *
+ * ── THE THREE RULES ─────────────────────────────────────────────────────────
+ *   what to link      every subdirectory holding a SKILL.md under the package's
+ *                     `SHIPPED_SKILLS_DIR` (consumer.mjs). No list, no count.
+ *   where it points   the package as it RESOLVES BY NAME from the project, spelled through the
+ *                     project's own `node_modules/paperlint` when that path leads to
+ *                     the same place. Under pnpm the resolved path is the version-stamped
+ *                     `.pnpm/…` store directory; a link spelled that way dangles after the next
+ *                     upgrade, a link through `node_modules/paperlint` does not.
+ *   what it touches   only what is missing. An entry that already leads to the shipped skill is
+ *                     left alone; ANY other entry of the same name — a directory, a file, a link
+ *                     elsewhere, a dangling link — is someone else's, and is reported, not replaced.
+ */
+/* eslint-disable boundaries/dependencies -- legacy I/O, moves behind a port in #76 */
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readlinkSync,
+  realpathSync,
+  symlinkSync,
+  unlinkSync,
+} from "node:fs";
+/* eslint-enable boundaries/dependencies */
+import { createRequire } from "node:module";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  installedSkills,
+  LEGACY_PACKAGE_NAME,
+  PACKAGE_NAME,
+  SHIPPED_SKILLS_DIR,
+} from "../skills/paper-pipeline/scripts/consumer.mjs";
+
+export { PACKAGE_NAME };
+/** Where Claude Code looks for project skills, relative to the project root. */
+export const SKILLS_HOME = join(".claude", "skills");
+
+export type Located =
+  | { readonly dir: string; readonly spelled: string }
+  | { readonly error: string };
+
+/**
+ * The installed package, asked of Node from the PROJECT, not from wherever this code runs. A copy
+ * run out of the npx cache is not the project's install, and a link into a cache is a link that
+ * disappears with it — so "does not resolve from here" is an answer, not something to paper over.
+ *
+ * @returns `dir` — the real directory; `spelled` — the same directory as the project names it.
+ */
+export function locatePackage(project: string): Located {
+  let manifest: string;
+  try {
+    const req = createRequire(
+      pathToFileURL(join(project, "__rpp_locate__.js")).href,
+    );
+    manifest = req.resolve(`${PACKAGE_NAME}/package.json`);
+  } catch (e) {
+    return {
+      error: `${(e as NodeJS.ErrnoException).code ?? "error"}: ${(e as Error).message.split("\n")[0]}`,
+    };
+  }
+  const dir = realpathSync(dirname(manifest));
+  // Node's own walk, without its realpath step: the first `node_modules/<name>` up the tree that
+  // leads to the package that resolved.
+  for (let d = realpathSync(project); ; d = dirname(d)) {
+    const candidate = join(d, "node_modules", PACKAGE_NAME);
+    try {
+      if (realpathSync(candidate) === dir) return { dir, spelled: candidate };
+    } catch {
+      // not here — keep walking
+    }
+    if (dirname(d) === d) break;
+  }
+  return { dir, spelled: dir };
+}
+
+/** The skills the package ships: every skill under its `SHIPPED_SKILLS_DIR`. */
+export function shippedSkills(
+  pkgDir: string,
+):
+  | { readonly skillsDir: string; readonly names: readonly string[] }
+  | { readonly error: string } {
+  const skillsDir = join(pkgDir, SHIPPED_SKILLS_DIR);
+  // A missing directory is an error, never an empty list: zero skills linked must not read as a
+  // clean run.
+  if (!existsSync(skillsDir))
+    return { error: `the package's skills directory is missing: ${skillsDir}` };
+  // The same function every reader of an installed skills directory calls (rpp#62): the writer
+  // and the readers of this fact share one definition of "a skill is here", links included.
+  try {
+    return { skillsDir, names: installedSkills(skillsDir) };
+  } catch (e) {
+    return { error: (e as Error).message };
+  }
+}
+
+export type LinkStatus =
+  "created" | "replaced" | "present" | "missing" | "foreign";
+
+export interface SkillLink {
+  readonly name: string;
+  readonly status: LinkStatus;
+  /** For `foreign`: what is there instead, in words. */
+  readonly reason?: string;
+}
+
+export type LinkReport =
+  | {
+      readonly ok: true;
+      readonly home: string;
+      /** The link target of the first skill, e.g. `../../node_modules/paperlint/skills/x`. */
+      readonly example: string | null;
+      readonly links: readonly SkillLink[];
+    }
+  | { readonly ok: false; readonly error: string };
+
+/**
+ * What occupies `entry`, judged against the directory it should lead to. A link spelled exactly as
+ * an install under the package's old name wrote it (`legacyTarget`) is `stale`: ours, from before
+ * the rename, and replaced on the next `init`.
+ */
+function inspect(
+  entry: string,
+  want: string,
+  legacyTarget: string,
+): { status: "present" | "missing" | "foreign" | "stale"; reason?: string } {
+  let st;
+  try {
+    st = lstatSync(entry);
+  } catch {
+    return { status: "missing" };
+  }
+  if (st.isSymbolicLink() && readlinkSync(entry) === legacyTarget)
+    return {
+      status: "stale",
+      reason: `a link into ${LEGACY_PACKAGE_NAME}, the package's old name — \`npx ${PACKAGE_NAME} init\` replaces it`,
+    };
+  try {
+    if (realpathSync(entry) === want) return { status: "present" };
+  } catch {
+    return st.isSymbolicLink()
+      ? {
+          status: "foreign",
+          reason: `a dangling link to ${readlinkSync(entry)}`,
+        }
+      : { status: "foreign", reason: "an entry that cannot be resolved" };
+  }
+  if (st.isSymbolicLink())
+    return { status: "foreign", reason: `a link to ${readlinkSync(entry)}` };
+  return {
+    status: "foreign",
+    reason: st.isDirectory() ? "a directory" : "a file",
+  };
+}
+
+/**
+ * One skill: inspect its entry and, when writing, create the link — or replace one an install
+ * under the package's old name made.
+ */
+function linkOne(
+  name: string,
+  {
+    entry,
+    target,
+    want,
+    write,
+  }: { entry: string; target: string; want: string; write: boolean },
+): SkillLink {
+  const legacyTarget = target.replace(
+    `node_modules${sep}${PACKAGE_NAME}${sep}`,
+    `node_modules${sep}${LEGACY_PACKAGE_NAME}${sep}`,
+  );
+  const seen = inspect(entry, want, legacyTarget);
+  const fixable = seen.status === "missing" || seen.status === "stale";
+  if (!write || !fixable) {
+    const status = seen.status === "stale" ? "foreign" : seen.status;
+    return seen.reason
+      ? { name, status, reason: seen.reason }
+      : { name, status };
+  }
+  try {
+    if (seen.status === "stale") unlinkSync(entry);
+    symlinkSync(target, entry, "dir");
+    return { name, status: seen.status === "stale" ? "replaced" : "created" };
+  } catch (e) {
+    return {
+      name,
+      status: "foreign",
+      reason: `could not create the link: ${(e as Error).message}`,
+    };
+  }
+}
+
+/**
+ * Link every shipped skill into `<project>/.claude/skills/`, or — with `write: false` — only
+ * report which ones are missing (that is what `paperlint doctor` asks).
+ */
+export function linkSkills(
+  project: string,
+  {
+    write = true,
+    locate = locatePackage,
+  }: { write?: boolean; locate?: (p: string) => Located } = {},
+): LinkReport {
+  const pkg = locate(project);
+  if ("error" in pkg)
+    return {
+      ok: false,
+      error: `${PACKAGE_NAME} does not resolve from ${project} (${pkg.error})`,
+    };
+  const shipped = shippedSkills(pkg.dir);
+  if ("error" in shipped) return { ok: false, error: shipped.error };
+  // The same directory, as the project spells it: the real skills dir re-rooted on `spelled`.
+  const spelledSkills = join(pkg.spelled, relative(pkg.dir, shipped.skillsDir));
+
+  const home = join(project, SKILLS_HOME);
+  if (write && shipped.names.length > 0) {
+    try {
+      mkdirSync(home, { recursive: true });
+    } catch (e) {
+      return {
+        ok: false,
+        error: `cannot create ${home}: ${(e as Error).message}`,
+      };
+    }
+  }
+  // A relative target resolves against the directory that PHYSICALLY holds the link, so it is
+  // computed from the real one — `.claude` may itself be a symlink.
+  const physicalHome = existsSync(home) ? realpathSync(home) : resolve(home);
+
+  let example: string | null = null;
+  const links = shipped.names.map((name): SkillLink => {
+    const target = relative(physicalHome, join(spelledSkills, name));
+    example ??= target;
+    return linkOne(name, {
+      entry: join(home, name),
+      target,
+      want: realpathSync(join(shipped.skillsDir, name)),
+      write,
+    });
+  });
+  return { ok: true, home, example, links };
+}