skillshelf 0.4.0 → 0.4.1

package/README.md

@@ -7,22 +7,17 @@
 [![CI](https://img.shields.io/github/actions/workflow/status/Wang-Cankun/skillshelf/ci.yml?branch=main)](https://github.com/Wang-Cankun/skillshelf/actions)
 [![npm](https://img.shields.io/npm/v/skillshelf.svg)](https://www.npmjs.com/package/skillshelf)
 
-Your skills are scattered across **every agent you use** — some in `~/.claude/skills`, some in
-`~/.codex/skills` or `~/.cursor/skills`, some buried in Obsidian or notes vaults, more copied into
-a dozen per-project `.claude` / `.codex` directories. Each tool scatters its own copies and
-symlinks; you forget which ones exist, rewrite ones you already have, and copies drift out of sync.
-The naive fix — dump everything into one agent's dir — makes every session pay the token cost of
-loading hundreds of skill descriptions at once.
-
-skillshelf is **agent-agnostic** (Claude Code, Codex, Cursor, and compatible agents): the library
-is a neutral source, and `skl where` maps where every skill is actually deployed across all of
-them — surfacing untracked copies, drift, and dead links. It's the curation layer *over* your
-agent dirs, complementary to installers like [`vercel-labs/skills`](https://github.com/vercel-labs/skills).
-
-skillshelf is the middle path: a single git-backed **library** that is a *passive shelf*
-(nothing auto-loads), plus a CLI to **search, tag, bundle, and load** exactly the skills a
-project needs, exactly when it needs them. Find anything in one place; pay only for what you
-actually use.
+Your skills are scattered across **every agent you use** — `~/.claude/skills`, `~/.codex/skills`,
+`~/.cursor/skills`, Obsidian vaults, and a dozen per-project `.claude` dirs. Copies drift, you
+rewrite skills you already have, and you forget which exist. The naive fix — dump everything into
+one agent's dir — makes every session pay to load hundreds of skill descriptions at once.
+
+skillshelf is the middle path: one git-backed **library** that is a *passive shelf* (nothing
+auto-loads), plus a CLI to **search, tag, bundle, and load** exactly the skills a project needs,
+when it needs them. It's **agent-agnostic** (Claude Code, Codex, Cursor, …) — `skl where` maps
+where every skill is actually deployed across all of them, surfacing untracked copies, drift, and
+dead links. Find anything in one place; pay only for what you use. (Complementary to installers
+like [`vercel-labs/skills`](https://github.com/vercel-labs/skills).)
 
 ## Desktop app
 
@@ -148,27 +143,32 @@ skillshelf separates *owning* a skill from *loading* it.
 - **On-demand `show`** — prints only the SKILL.md instruction body and lists the paths of
   any bundled reference files (without reading them). Progressive disclosure: cheap by
   default, deep when you ask. Works mid-task with no reload.
-- **Owned vs linked entries** ([ADR-0004](./docs/adr/0004-owned-vs-linked-entries.md)) — the
-  library is a *bookshelf*: an entry either **owns** its bytes (a real copy; the library is
-  canonical — for downloads and stabilized skills) or is **linked** (a symlink to an external dev
-  repo that stays canonical — for skills you actively develop in their own git, e.g. `claim-log`).
-  `skl link --from <dev-repo>` registers a linked entry; `skl where` shows it as a clean
-  `✓ source`; `skl update` / `outdated` skip linked entries so they never pull upstream into your
-  dev repo. The mode is derived from the filesystem (a symlink resolving outside the library),
-  never stored, so it can't go stale.
+- **Owned vs linked entries** ([ADR-0004](./docs/adr/0004-owned-vs-linked-entries.md)) — an entry
+  either **owns** its bytes (a real copy — for downloads and stabilized skills) or is **linked**
+  (`skl link --from <dev-repo>` — a symlink to an external repo that stays canonical, for skills you
+  develop in their own git). `update` / `outdated` skip linked entries so they never push upstream
+  into your dev repo. The mode is derived from the filesystem, never stored, so it can't go stale.
 - **Updates never clobber your tags** — domain tags live in the central `taxonomy.json`
   ([ADR-0002](./docs/adr/0002-central-taxonomy-not-sidecars.md)), separate from the skill body, so
   `skl update` can swap an owned skill's upstream `SKILL.md` cleanly while your taxonomy survives.
 
-```
-                       skl search / ls / show          skl use <bundle>
-                                │                              │
-   ┌──────────────────────┐    │   ┌──────────────────────┐   │   ┌─────────────────────┐
-   │   canonical library  │────┴──▶│   bundles = tag query │───┴──▶│  project .claude/   │
-   │  (passive git shelf) │        │  bioinfo · coding · … │       │  skills/ (symlinks) │
-   └──────────┬───────────┘        └──────────────────────┘       └─────────────────────┘
-              │
-              └──── thin global core ──▶ ~/.claude/skills  (always-on, bounded)
+```mermaid
+flowchart LR
+    L["📚 Canonical library<br/><i>passive git shelf</i>"]
+    B["🏷️ Bundles<br/><i>tag query — bioinfo · coding · …</i>"]
+    P["📁 Project .claude/skills/<br/><i>symlinks, on demand</i>"]
+    G["⚡ ~/.claude/skills<br/><i>thin global core, always-on</i>"]
+
+    L -- "skl use bundle" --> B
+    B -- symlink --> P
+    L -- "thin global core" --> G
+
+    search(["skl search · ls · show"]) -. reads .-> L
+
+    classDef shelf fill:#1f2937,stroke:#4b5563,color:#e5e7eb;
+    classDef live fill:#064e3b,stroke:#10b981,color:#d1fae5;
+    class L,B shelf;
+    class P,G live;
 ```
 
 See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for the full design.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillshelf",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Agent-first skill registry + manager for Claude Code and compatible agents.",
   "type": "module",
   "license": "MIT",

package/src/commands/add.test.ts

@@ -0,0 +1,118 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run } from "./add.ts";
+import type { Ctx } from "../types.ts";
+
+interface Captured {
+  ctx: Ctx;
+  logs: string[];
+  errors: string[];
+  json: unknown[];
+}
+
+/** Minimal Ctx mock — add.run 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 };
+}
+
+function skillBody(name: string): string {
+  return `---\nname: ${name}\ndescription: a ${name} skill for testing\n---\n\n# ${name}\n\nbody for ${name}\n`;
+}
+
+/** Build a real local git repo holding the given skills, for offline `git:` add. */
+async function makeGitRepo(parent: string, skills: string[]): Promise<string> {
+  const repo = join(parent, "src-repo");
+  await mkdir(repo, { recursive: true });
+  for (const s of skills) {
+    await mkdir(join(repo, s), { recursive: true });
+    await writeFile(join(repo, s, "SKILL.md"), skillBody(s));
+  }
+  const run = (cmd: string[]) =>
+    Bun.spawn(cmd, { cwd: repo, stdout: "ignore", stderr: "ignore" }).exited;
+  await run(["git", "init", "-q"]);
+  await run(["git", "config", "user.email", "test@example.com"]);
+  await run(["git", "config", "user.name", "test"]);
+  await run(["git", "add", "-A"]);
+  await run(["git", "commit", "-q", "-m", "init"]);
+  return repo;
+}
+
+describe("skl add — retired-aware collision", () => {
+  let tmp: string;
+  let library: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-add-")));
+    library = join(tmp, "library");
+    await mkdir(library, { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("--all over a repo where one name is retired: skips it (no duplicate), installs the rest", async () => {
+    const repo = await makeGitRepo(tmp, ["caveman", "tdd"]);
+    // Retire "caveman": a tombstone under _retired/, NO active copy.
+    await mkdir(join(library, "_retired", "caveman"), { recursive: true });
+    await writeFile(join(library, "_retired", "caveman", "SKILL.md"), skillBody("caveman"));
+
+    const { ctx, json } = makeCtx(library);
+    const code = await run([`git:${repo}`, "--all", "--no-infer", "--json"], ctx);
+    expect(code).toBe(0);
+
+    const out = json[0] as {
+      results: Array<{ name: string; status: string; verdict: string; reason: string }>;
+    };
+    const caveman = out.results.find((r) => r.name === "caveman")!;
+    const tdd = out.results.find((r) => r.name === "tdd")!;
+
+    expect(caveman.status).toBe("skipped");
+    expect(caveman.verdict).toBe("retired");
+    expect(caveman.reason).toContain("skl unretire caveman");
+
+    // No active duplicate beside the tombstone.
+    expect(existsSync(join(library, "caveman"))).toBe(false);
+    expect(existsSync(join(library, "_retired", "caveman"))).toBe(true);
+
+    // The non-colliding name still installs.
+    expect(tdd.status).toBe("installed");
+    expect(existsSync(join(library, "tdd", "SKILL.md"))).toBe(true);
+  });
+
+  test("single add of a retired name refuses (exit 1, no duplicate)", async () => {
+    const repo = await makeGitRepo(tmp, ["caveman"]);
+    await mkdir(join(library, "_retired", "caveman"), { recursive: true });
+    await writeFile(join(library, "_retired", "caveman", "SKILL.md"), skillBody("caveman"));
+
+    const { ctx, errors } = makeCtx(library);
+    const code = await run([`git:${repo}`, "--no-infer"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("skl unretire caveman");
+    expect(existsSync(join(library, "caveman"))).toBe(false);
+  });
+
+  test("active-collision still refuses without --force (no regression)", async () => {
+    const repo = await makeGitRepo(tmp, ["tdd"]);
+    // An ACTIVE copy already exists.
+    await mkdir(join(library, "tdd"), { recursive: true });
+    await writeFile(join(library, "tdd", "SKILL.md"), skillBody("tdd") + "local edit\n");
+
+    const { ctx, errors } = makeCtx(library);
+    const code = await run([`git:${repo}`, "--no-infer"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("already exists");
+  });
+});

package/src/commands/add.ts

@@ -38,7 +38,7 @@ import { hashContent } from "../core/crawl.ts";
 import { recordEntry } from "../core/provenance.ts";
 import { setDomainsForName } from "../core/taxonomy.ts";
 import { assertSafeName } from "../core/lifecycle.ts";
-import { loadLibrary, findByName } from "../core/library.ts";
+import { loadLibrary, findByName, entryStatus } from "../core/library.ts";
 import { ensureDir, isSymlink, realpathOrSelf } from "../lib/fs.ts";
 
 export const meta = {
@@ -217,7 +217,7 @@ interface InstallOptions {
 interface InstallOutcome {
   name: string;
   subpath: string;
-  verdict: Verdict | "duplicate";
+  verdict: Verdict | "duplicate" | "retired";
   status: "installed" | "skipped" | "error";
   reason: string;
   path: string;
@@ -268,6 +268,21 @@ async function installOne(
     return { ...base, reason: err instanceof Error ? err.message : String(err) };
   }
 
+  // Retired-aware collision guard: if this name exists ONLY as a retired tombstone
+  // (<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).
+  const status = entryStatus(opts.libraryPath, rawName);
+  if (status.retired && !status.active) {
+    return {
+      ...base,
+      verdict: "retired",
+      status: "skipped",
+      reason: `a retired '${rawName}' exists — run \`skl unretire ${rawName}\` first`,
+    };
+  }
+
   const destDir = destDirFor(opts.libraryPath, opts.domainFolder, rawName);
   const verdict = await driftVerdict(skill, destDir);
   base.verdict = verdict;
@@ -608,6 +623,12 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         ctx.error("add:", o.reason);
         return 1;
       }
+      // A retired-name collision is a refusal in single mode (no duplicate written):
+      // surface it as an error + non-zero exit, pointing the user at `skl unretire`.
+      if (o.status === "skipped") {
+        ctx.error("add:", o.reason);
+        return 1;
+      }
       // Legacy single-skill summary shape (unchanged for existing consumers).
       const summary = {
         ok: true,

package/src/commands/import.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run } from "./import.ts";
+import type { Ctx } from "../types.ts";
+
+const BODY = "---\nname: caveman\ndescription: a test skill\n---\n\nbody\n";
+
+interface Captured {
+  ctx: Ctx;
+  logs: string[];
+  errors: string[];
+  json: unknown[];
+}
+
+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 import — retired-aware collision", () => {
+  let tmp: string;
+  let library: string;
+  let candidate: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-import-")));
+    library = join(tmp, "library");
+    await mkdir(library, { recursive: true });
+    // A candidate skill dir on disk to import.
+    candidate = join(tmp, "ext", "caveman");
+    await mkdir(candidate, { recursive: true });
+    await writeFile(join(candidate, "SKILL.md"), BODY);
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("importing to a retired name refuses (exit 1, no write)", async () => {
+    // Retire "caveman": a tombstone, no active copy.
+    await mkdir(join(library, "_retired", "caveman"), { recursive: true });
+    await writeFile(join(library, "_retired", "caveman", "SKILL.md"), BODY);
+
+    const { ctx, errors } = makeCtx(library);
+    const code = await run(["caveman", "--from", candidate, "--copy"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("skl unretire caveman");
+
+    // No active copy created; the candidate is untouched.
+    expect(existsSync(join(library, "caveman"))).toBe(false);
+    expect(existsSync(join(candidate, "SKILL.md"))).toBe(true);
+  });
+
+  test("importing a non-retired name still works (no regression)", async () => {
+    const { ctx } = makeCtx(library);
+    const code = await run(["caveman", "--from", candidate, "--copy", "--json"], ctx);
+    expect(code).toBe(0);
+    expect(existsSync(join(library, "caveman", "SKILL.md"))).toBe(true);
+  });
+});

package/src/commands/import.ts

@@ -34,6 +34,7 @@ import {
   isSymlink,
   realpathOrSelfAsync,
 } from "../lib/fs.ts";
+import { entryStatus } from "../core/library.ts";
 
 export const meta = {
   name: "import",
@@ -202,6 +203,18 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     // Flat, non-semantic layout (ADR-0001): always <library>/<name>/.
     const destDir = join(libraryPath, targetName);
 
+    // Retired-aware guard: refuse if the name exists ONLY as a retired tombstone
+    // (<library>/_retired/<name>). Importing beside it would strand a duplicate and
+    // break `skl unretire`; --force overwrites an ACTIVE copy, not a retired one, so
+    // this fires regardless. The user must unretire first (or import under --as).
+    const status = entryStatus(libraryPath, targetName);
+    if (status.retired && !status.active) {
+      ctx.error(
+        `skl import: a retired '${targetName}' exists — run \`skl unretire ${targetName}\` first (or import under another name with --as <slug>)`,
+      );
+      return 1;
+    }
+
     // Idempotency guard: refuse to clobber an existing library skill unless --force
     // (or the user re-aimed with --as). This protects a managed copy from a stray
     // re-import.

package/src/commands/link.test.ts

@@ -100,6 +100,20 @@ describe("skl link --from (LINKED mode)", () => {
     expect((await lstat(join(library, "claim-log"))).isSymbolicLink()).toBe(false);
   });
 
+  test("refuses to shelve over a retired tombstone (points at unretire)", async () => {
+    // "claim-log" exists only as a retired tombstone — no active library entry.
+    await makeSkillDir(join(library, "_retired"), "claim-log");
+    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("skl unretire claim-log");
+    // No active symlink created beside the tombstone.
+    expect(existsSync(join(library, "claim-log"))).toBe(false);
+    expect(existsSync(join(library, "_retired", "claim-log"))).toBe(true);
+  });
+
   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");

package/src/commands/link.ts

@@ -39,6 +39,7 @@ import {
   safeSymlink,
   realpathOrSelfAsync,
 } from "../lib/fs.ts";
+import { entryStatus } from "../core/library.ts";
 
 export const meta = {
   name: "link",
@@ -166,6 +167,16 @@ async function runFrom(flags: Flags, ctx: Ctx): Promise<number> {
       }
     }
 
+    // Retired-aware guard: refuse if the name exists ONLY as a retired tombstone
+    // (<library>/_retired/<name>). Shelving a symlink beside it would strand a duplicate
+    // and break `skl unretire`; --force replaces an ACTIVE entry, not a retired one, so
+    // this fires regardless. The user must unretire first.
+    const status = entryStatus(libraryPath, name);
+    if (status.retired && !status.active) {
+      ctx.error(`skl link: a retired '${name}' exists — run \`skl unretire ${name}\` first.`);
+      return 1;
+    }
+
     // An existing library entry won't be clobbered silently.
     const exists = existsSync(libDir) || isSymlink(libDir);
     if (exists && !flags.force) {

package/src/commands/new.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run } from "./new.ts";
+import type { Ctx } from "../types.ts";
+
+interface Captured {
+  ctx: Ctx;
+  logs: string[];
+  errors: string[];
+  json: unknown[];
+}
+
+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 new — retired-aware collision", () => {
+  let tmp: string;
+  let library: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-new-")));
+    library = join(tmp, "library");
+    await mkdir(library, { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("`skl new <retired-name>` refuses (exit 1, no write)", async () => {
+    await mkdir(join(library, "_retired", "caveman"), { recursive: true });
+    await writeFile(
+      join(library, "_retired", "caveman", "SKILL.md"),
+      "---\nname: caveman\ndescription: a test skill\n---\n\nbody\n",
+    );
+
+    const { ctx, errors } = makeCtx(library);
+    const code = await run(["caveman"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("skl unretire caveman");
+    expect(existsSync(join(library, "caveman"))).toBe(false);
+  });
+
+  test("`skl new <fresh-name>` still scaffolds (no regression)", async () => {
+    const { ctx } = makeCtx(library);
+    const code = await run(["fresh-skill"], ctx);
+    expect(code).toBe(0);
+    expect(existsSync(join(library, "fresh-skill", "SKILL.md"))).toBe(true);
+  });
+});

package/src/commands/new.ts

@@ -11,6 +11,7 @@ import { existsSync } from "node:fs";
 import type { Ctx } from "../types.ts";
 import { serializeFrontmatter } from "../lib/frontmatter.ts";
 import { ensureDir } from "../lib/fs.ts";
+import { entryStatus } from "../core/library.ts";
 
 export const meta = {
   name: "new",
@@ -119,6 +120,17 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     const skillDir = join(libraryPath, name);
     const bodyPath = join(skillDir, "SKILL.md");
 
+    // Retired-aware guard: refuse if the name exists ONLY as a retired tombstone
+    // (<library>/_retired/<name>). Scaffolding a fresh active copy beside it would
+    // strand a duplicate and break `skl unretire`; this fires regardless of --force.
+    const status = entryStatus(libraryPath, name);
+    if (status.retired && !status.active) {
+      ctx.error(
+        `skl new: a retired '${name}' exists — run \`skl unretire ${name}\` first (or choose another name)`,
+      );
+      return 1;
+    }
+
     if (existsSync(bodyPath) && !args.force) {
       ctx.error(
         `skl new: SKILL.md already exists at ${bodyPath} — pass --force to overwrite`,

package/src/commands/rename.test.ts

@@ -69,6 +69,20 @@ describe("skl rename — atomic slug move (friction #5)", () => {
     expect(errors.join("\n")).toContain("already exists");
   });
 
+  test("refuses renaming TO a retired name (points at unretire)", async () => {
+    // "beta" exists only as a retired tombstone — no active entry.
+    await mkdir(join(library, "_retired", "beta"), { recursive: true });
+    await writeFile(join(library, "_retired", "beta", "SKILL.md"), "---\nname: beta\n---\n\nb\n");
+
+    const { ctx, errors } = makeCtx(library);
+    const code = await renameRun(["alpha", "beta"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("skl unretire beta");
+    // alpha untouched; no active beta created.
+    expect(existsSync(join(library, "alpha", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(library, "beta"))).toBe(false);
+  });
+
   test("refuses a missing source", async () => {
     const { ctx, errors } = makeCtx(library);
     const code = await renameRun(["ghost", "x"], ctx);

package/src/core/library.ts

@@ -123,6 +123,60 @@ export function entryModeInfo(libraryPath: string, name: string): EntryModeInfo
   return owned ? { mode: "owned", linkTarget: null } : { mode: "linked", linkTarget: real };
 }
 
+/** Directory holding retired (soft-deleted) tombstones, relative to the library root. */
+export const RETIRED_DIR = "_retired";
+
+/**
+ * Reject a skill name that is not a single path segment — the choke point that keeps a
+ * crafted/typo'd/agent-supplied `name` (e.g. "../../etc") from escaping the library when
+ * it reaches `join(libraryPath, name)` and then `rm`/`rename`/copy. A name with no path
+ * separator and no `.`/`..` cannot resolve outside its parent dir, so containment is
+ * guaranteed without over-restricting otherwise-unusual existing slugs. Throws on a bad
+ * name. Lives here (not in lifecycle.ts) so it sits beside entryStatus — the single
+ * existence-resolution primitive both the read guards (add/import/new/link) and the write
+ * mutations (lifecycle.ts re-exports it) funnel through.
+ */
+export function assertSafeName(name: string): void {
+  if (
+    name === "" ||
+    name === "." ||
+    name === ".." ||
+    name.includes("/") ||
+    name.includes("\\") ||
+    name.includes("\0")
+  ) {
+    throw new Error(`invalid skill name '${name}' — must be a single name, no path separators or '..'`);
+  }
+}
+
+/** Whether a name occupies the active and/or retired slot in the library. */
+export interface EntryStatus {
+  /** <library>/<name> exists (real dir or symlink) */
+  active: boolean;
+  /** <library>/_retired/<name> exists (real dir or symlink) */
+  retired: boolean;
+}
+
+/**
+ * Single source of truth for "is this name taken?" across BOTH locations a skill can
+ * live: the active slot <library>/<name> and the retired tombstone
+ * <library>/_retired/<name>. Existence = existsSync OR isSymlink, so a LINKED entry (a
+ * symlink whose target may be absent) still counts as present. Name-validated via
+ * assertSafeName so a path-escaping `name` can never be joined; collision guards in
+ * add/import/new/link and the write mutations in lifecycle.ts (which delegates locateEntry
+ * to this) both resolve existence here, so the active+retired rule lives in exactly one
+ * place. Kept dependency-free of lifecycle.ts to avoid an import cycle.
+ */
+export function entryStatus(libraryPath: string, name: string): EntryStatus {
+  assertSafeName(name);
+  const activePath = join(libraryPath, name);
+  const retiredPath = join(libraryPath, RETIRED_DIR, name);
+  return {
+    active: existsSync(activePath) || isSymlink(activePath),
+    retired: existsSync(retiredPath) || isSymlink(retiredPath),
+  };
+}
+
 /** All unique domains across the library (sorted). */
 export function listDomains(skills: Skill[]): string[] {
   const set = new Set<string>();

package/src/core/lifecycle.ts

@@ -18,32 +18,13 @@ import { isSymlink, ensureDir } from "../lib/fs.ts";
 import { parseFrontmatter, serializeFrontmatter } from "../lib/frontmatter.ts";
 import { readTaxonomy, writeTaxonomy } from "./taxonomy.ts";
 import { readLockfile, writeLockfile } from "./provenance.ts";
-import { loadLibrary } from "./library.ts";
+import { loadLibrary, entryStatus, RETIRED_DIR, assertSafeName } from "./library.ts";
 import { writeIndex } from "./indexgen.ts";
 
-const RETIRED_DIR = "_retired";
-
-/**
- * Reject a skill name that is not a single path segment — the choke point that keeps
- * a crafted/typo'd/agent-supplied `name` (e.g. "../../etc") from escaping the library
- * when it reaches `join(libraryPath, name)` and then `rm`/`rename`. A name with no path
- * separator and no `.`/`..` cannot resolve outside its parent dir, so containment is
- * guaranteed without over-restricting otherwise-unusual existing slugs. Throws on a bad
- * name; every name-keyed mutation funnels through locateEntry, so validating here covers
- * removeSkill / retireSkill / unretireSkill / renameSkill in one place.
- */
-export function assertSafeName(name: string): void {
-  if (
-    name === "" ||
-    name === "." ||
-    name === ".." ||
-    name.includes("/") ||
-    name.includes("\\") ||
-    name.includes("\0")
-  ) {
-    throw new Error(`invalid skill name '${name}' — must be a single name, no path separators or '..'`);
-  }
-}
+// assertSafeName + RETIRED_DIR live in library.ts beside entryStatus (the single
+// existence-resolution primitive) and are re-exported here so existing importers that
+// reach for them via lifecycle.ts (e.g. add.ts) keep working.
+export { assertSafeName, RETIRED_DIR };
 
 /** Regenerate INDEX.md from the current library state. Returns the path written. */
 export async function reindexLibrary(libraryPath: string): Promise<string> {
@@ -63,14 +44,20 @@ export interface EntryLocation {
   isLink: boolean;
 }
 
-/** Locate a skill entry across the active and retired locations. */
+/**
+ * Locate a skill entry across the active and retired locations. The active/retired
+ * existence rule is NOT re-implemented here — it delegates to entryStatus (the single
+ * source of truth, which also runs assertSafeName), then enriches the two booleans with
+ * the resolved path (active preferred) and whether that path is a symlink, the extra the
+ * write mutations need.
+ */
 export function locateEntry(libraryPath: string, name: string): EntryLocation {
-  assertSafeName(name);
-  const activePath = join(libraryPath, name);
-  const retiredPath = join(libraryPath, RETIRED_DIR, name);
-  const active = existsSync(activePath) || isSymlink(activePath);
-  const retired = existsSync(retiredPath) || isSymlink(retiredPath);
-  const path = active ? activePath : retired ? retiredPath : null;
+  const { active, retired } = entryStatus(libraryPath, name);
+  const path = active
+    ? join(libraryPath, name)
+    : retired
+      ? join(libraryPath, RETIRED_DIR, name)
+      : null;
   const isLink = path ? isSymlink(path) : false;
   return { active, retired, path, isLink };
 }
@@ -181,7 +168,14 @@ export async function renameSkill(
 ): Promise<RenameResult> {
   const loc = locateEntry(libraryPath, from);
   if (!loc.path) throw new Error(`'${from}' is not in the library`);
-  if (locateEntry(libraryPath, to).path) {
+  const dest = locateEntry(libraryPath, to);
+  if (dest.path) {
+    // A retired-only target is a tombstone, not a usable name: point at `skl unretire`
+    // (renaming onto it would either collide or shadow the retired copy) rather than the
+    // generic "choose another name". An active target keeps the original message.
+    if (dest.retired && !dest.active) {
+      throw new Error(`a retired '${to}' exists — run \`skl unretire ${to}\` first (or choose another name)`);
+    }
     throw new Error(`'${to}' already exists in the library — choose another name`);
   }