skillshelf 0.4.0 → 0.5.0

package/README.md

@@ -3,26 +3,21 @@
 **A package manager for your agent skills — one canonical library, loaded on demand, never all at once.**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-black?logo=bun)](https://bun.sh)
+[![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.2-black?logo=bun)](https://bun.sh)
 [![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.
+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 **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.
+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
 
@@ -51,7 +46,7 @@ matrix (Global + the projects where it's pinned), plus lifecycle actions.
 
 ## Install
 
-skillshelf runs on [Bun](https://bun.sh) (>= 1.0). No other runtime dependencies.
+skillshelf runs on [Bun](https://bun.sh) (>= 1.2). No other runtime dependencies.
 
 > **Bun is required, not optional.** The `skl` bin is a TypeScript entrypoint with a
 > `#!/usr/bin/env bun` shebang — there is no compiled Node build. `npm i -g skillshelf`
@@ -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.
@@ -198,7 +198,7 @@ See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for the full design.
 | `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 refresh` | Re-sync this project's `./.claude/skills` symlinks to current library reality (repoint stale, prune vanished) | `--dry-run` |
-| `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. `--list` discovers + prints; `--dry-run` previews drift (new/identical/differs); a `differs` skill is skipped without `--force` | `--all`, `--skill <a,b>`, `--list`, `--dry-run`, `--domain <d>`, `--name <slug>`, `--no-infer`, `--force` |
+| `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 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) | — |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillshelf",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Agent-first skill registry + manager for Claude Code and compatible agents.",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "test": "bun test"
   },
   "engines": {
-    "bun": ">=1.0.0"
+    "bun": ">=1.2.0"
   },
   "publishConfig": {
     "access": "public"

package/src/adapters/inference/api.ts

@@ -93,10 +93,7 @@ function resolveEnvFilePath(env: NodeJS.ProcessEnv, override?: string): string |
 
 /** First non-empty trimmed value, or "". */
 function firstNonEmpty(...vals: (string | undefined)[]): string {
-  for (const v of vals) {
-    if (v && v.trim() !== "") return v.trim();
-  }
-  return "";
+  return vals.find(v => v?.trim())?.trim() ?? "";
 }
 
 /**

package/src/commands/add.published.test.ts

@@ -0,0 +1,390 @@
+// ADR-0012 — published set (manifest allowlist + metadata.internal) + the > 15 count gate.
+//
+// These tests drive `skl add` over real local git repos (offline `git:` channel,
+// HOME-isolated library) exercising:
+//   (a) manifest-present repo  -> --all installs only the allowlisted subset
+//   (b) --skill reaches an UNPUBLISHED (folder-excluded) skill, never gated
+//   (c) metadata.internal:true excluded from --all but installable by name
+//   (d) marketplace.json union across plugins
+//   (e) the > 15 count gate trips, and --yes bypasses it
+//   (f) --list shows the FULL set with published/unpublished/internal markers
+//   (g) a no-manifest repo still installs every skill (under the gate)
+
+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 { discoverSkills } from "../core/fetch.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 };
+}
+
+function skillBody(
+  name: string,
+  opts: { internal?: boolean; internalFlow?: boolean; description?: string } = {},
+): string {
+  const desc = opts.description ?? `a ${name} skill for testing`;
+  // Block style by default; flow style (`metadata: {internal: true}`) exercises the
+  // YAML-flow-mapping path so the internal signal can't be bypassed by author style.
+  const meta = opts.internalFlow
+    ? `metadata: {internal: true}\n`
+    : opts.internal
+      ? `metadata:\n  internal: true\n`
+      : "";
+  return `---\nname: ${name}\ndescription: ${desc}\n${meta}---\n\n# ${name}\n\nbody for ${name}\n`;
+}
+
+interface SkillSpec {
+  /** repo-relative dir, e.g. "engineering/foo" */
+  path: string;
+  /** frontmatter name (defaults to basename of path) */
+  name?: string;
+  internal?: boolean;
+  /** mark internal via inline flow mapping instead of a block mapping */
+  internalFlow?: boolean;
+}
+
+/** Build a real local git repo with the given skills + optional manifest files. */
+async function makeRepo(
+  parent: string,
+  skills: SkillSpec[],
+  manifest?: { kind: "plugin" | "marketplace"; json: unknown },
+): Promise<string> {
+  const repo = join(parent, "src-repo");
+  await mkdir(repo, { recursive: true });
+  for (const s of skills) {
+    const dir = join(repo, s.path);
+    await mkdir(dir, { recursive: true });
+    const nm = s.name ?? s.path.split("/").pop()!;
+    await writeFile(
+      join(dir, "SKILL.md"),
+      skillBody(nm, { internal: s.internal, internalFlow: s.internalFlow }),
+    );
+  }
+  if (manifest) {
+    await mkdir(join(repo, ".claude-plugin"), { recursive: true });
+    const file = manifest.kind === "plugin" ? "plugin.json" : "marketplace.json";
+    await writeFile(join(repo, ".claude-plugin", file), JSON.stringify(manifest.json, null, 2));
+  }
+  const gitRun = (cmd: string[]) =>
+    Bun.spawn(cmd, { cwd: repo, stdout: "ignore", stderr: "ignore" }).exited;
+  await gitRun(["git", "init", "-q"]);
+  await gitRun(["git", "config", "user.email", "test@example.com"]);
+  await gitRun(["git", "config", "user.name", "test"]);
+  await gitRun(["git", "add", "-A"]);
+  await gitRun(["git", "commit", "-q", "-m", "init"]);
+  return repo;
+}
+
+describe("ADR-0012 published set + count gate", () => {
+  let tmp: string;
+  let library: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-pub-")));
+    library = join(tmp, "library");
+    await mkdir(library, { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  // (a) manifest-present repo -> --all installs only the allowlisted subset.
+  test("plugin.json allowlist bounds --all to the listed skills", async () => {
+    const repo = await makeRepo(
+      tmp,
+      [
+        { path: "engineering/alpha" },
+        { path: "engineering/beta" },
+        { path: "deprecated/gamma" },
+        { path: "in-progress/delta" },
+      ],
+      { kind: "plugin", json: { name: "x", skills: ["./engineering/alpha", "./engineering/beta"] } },
+    );
+
+    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 }> };
+    const installed = out.results.filter((r) => r.status === "installed").map((r) => r.name).sort();
+    expect(installed).toEqual(["alpha", "beta"]);
+    expect(existsSync(join(library, "alpha", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(library, "beta", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(library, "gamma"))).toBe(false);
+    expect(existsSync(join(library, "delta"))).toBe(false);
+  });
+
+  // (b) --skill reaches an UNPUBLISHED (folder-excluded) skill, NOT gated.
+  test("--skill installs an unpublished skill the manifest omits", async () => {
+    const repo = await makeRepo(
+      tmp,
+      [
+        { path: "engineering/alpha" },
+        { path: "deprecated/gamma" },
+      ],
+      { kind: "plugin", json: { name: "x", skills: ["./engineering/alpha"] } },
+    );
+
+    const { ctx, json } = makeCtx(library);
+    const code = await run([`git:${repo}`, "--skill", "gamma", "--no-infer", "--json"], ctx);
+    expect(code).toBe(0);
+    const out = json[0] as { results: Array<{ name: string; status: string }> };
+    const gamma = out.results.find((r) => r.name === "gamma")!;
+    expect(gamma.status).toBe("installed");
+    expect(existsSync(join(library, "gamma", "SKILL.md"))).toBe(true);
+  });
+
+  // (c) metadata.internal:true excluded from --all but installable by name.
+  test("metadata.internal skill is excluded from --all but installable by --skill", async () => {
+    const repo = await makeRepo(
+      tmp,
+      [
+        { path: "engineering/alpha" },
+        { path: "engineering/secret", internal: true },
+      ],
+      { kind: "plugin", json: { name: "x", skills: ["./engineering/alpha", "./engineering/secret"] } },
+    );
+
+    // --all skips the internal one even though the manifest lists it.
+    const all = makeCtx(library);
+    const codeAll = await run([`git:${repo}`, "--all", "--no-infer", "--json"], all.ctx);
+    expect(codeAll).toBe(0);
+    const outAll = all.json[0] as { results: Array<{ name: string; status: string }> };
+    const installedAll = outAll.results.filter((r) => r.status === "installed").map((r) => r.name);
+    expect(installedAll).toEqual(["alpha"]);
+    expect(existsSync(join(library, "secret"))).toBe(false);
+
+    // ...but --skill reaches it.
+    const byName = makeCtx(library);
+    const codeName = await run([`git:${repo}`, "--skill", "secret", "--no-infer", "--json"], byName.ctx);
+    expect(codeName).toBe(0);
+    expect(existsSync(join(library, "secret", "SKILL.md"))).toBe(true);
+  });
+
+  // (c2) the internal signal can't be bypassed by writing it as a YAML FLOW mapping
+  // (`metadata: {internal: true}`) instead of a block mapping.
+  test("flow-style metadata.internal is still excluded from --all", async () => {
+    const repo = await makeRepo(
+      tmp,
+      [
+        { path: "engineering/alpha" },
+        { path: "engineering/secret", internalFlow: true },
+      ],
+      { kind: "plugin", json: { name: "x", skills: ["./engineering/alpha", "./engineering/secret"] } },
+    );
+    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 }> };
+    expect(out.results.filter((r) => r.status === "installed").map((r) => r.name)).toEqual(["alpha"]);
+    expect(existsSync(join(library, "secret"))).toBe(false);
+  });
+
+  // (d) marketplace.json union across plugins.
+  test("marketplace.json unions every plugin's skills", async () => {
+    const repo = await makeRepo(
+      tmp,
+      [
+        { path: "engineering/alpha" },
+        { path: "productivity/beta" },
+        { path: "deprecated/gamma" },
+      ],
+      {
+        kind: "marketplace",
+        json: {
+          plugins: [
+            { name: "eng", skills: ["./engineering/alpha"] },
+            { name: "prod", skills: ["./productivity/beta"] },
+          ],
+        },
+      },
+    );
+
+    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 }> };
+    const installed = out.results.filter((r) => r.status === "installed").map((r) => r.name).sort();
+    expect(installed).toEqual(["alpha", "beta"]);
+    expect(existsSync(join(library, "gamma"))).toBe(false);
+  });
+
+  // (e) the count gate trips at > 15 published, and --yes bypasses it.
+  test("count gate refuses > 15 published skills; --yes bypasses", async () => {
+    // 16 skills, NO manifest -> all 16 are published.
+    const specs: SkillSpec[] = Array.from({ length: 16 }, (_, i) => ({
+      path: `skills/s${String(i).padStart(2, "0")}`,
+    }));
+    const repo = await makeRepo(tmp, specs);
+
+    const gated = makeCtx(library);
+    const codeGated = await run([`git:${repo}`, "--all", "--no-infer", "--json"], gated.ctx);
+    expect(codeGated).toBe(1);
+    const errText = gated.errors.join("\n");
+    expect(errText).toContain("16");
+    expect(errText).toMatch(/--yes/);
+    // Nothing installed.
+    expect(existsSync(join(library, "s00"))).toBe(false);
+
+    const bypass = makeCtx(library);
+    const codeYes = await run([`git:${repo}`, "--all", "--yes", "--no-infer", "--json"], bypass.ctx);
+    expect(codeYes).toBe(0);
+    const out = bypass.json[0] as { counts: { installed: number } };
+    expect(out.counts.installed).toBe(16);
+  });
+
+  test("count gate does NOT trip at exactly 15", async () => {
+    const specs: SkillSpec[] = Array.from({ length: 15 }, (_, i) => ({
+      path: `skills/s${String(i).padStart(2, "0")}`,
+    }));
+    const repo = await makeRepo(tmp, specs);
+    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 { counts: { installed: number } };
+    expect(out.counts.installed).toBe(15);
+  });
+
+  test("--skill is never gated even over a large repo", async () => {
+    const specs: SkillSpec[] = Array.from({ length: 20 }, (_, i) => ({
+      path: `skills/s${String(i).padStart(2, "0")}`,
+    }));
+    const repo = await makeRepo(tmp, specs);
+    const { ctx } = makeCtx(library);
+    const code = await run([`git:${repo}`, "--skill", "s00,s01", "--no-infer", "--json"], ctx);
+    expect(code).toBe(0);
+    expect(existsSync(join(library, "s00", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(library, "s01", "SKILL.md"))).toBe(true);
+  });
+
+  // (f) --list shows the FULL set with published/unpublished/internal markers.
+  test("--list marks every skill published/unpublished/internal; never gated", async () => {
+    const repo = await makeRepo(
+      tmp,
+      [
+        { path: "engineering/alpha" },
+        { path: "deprecated/gamma" },
+        { path: "engineering/secret", internal: true },
+      ],
+      { kind: "plugin", json: { name: "x", skills: ["./engineering/alpha", "./engineering/secret"] } },
+    );
+
+    const { ctx, json } = makeCtx(library);
+    const code = await run([`git:${repo}`, "--list", "--json"], ctx);
+    expect(code).toBe(0);
+    const out = json[0] as {
+      skills: Array<{ name: string; published: boolean; internal: boolean }>;
+    };
+    const byName = new Map(out.skills.map((s) => [s.name, s]));
+    expect(out.skills.length).toBe(3);
+    expect(byName.get("alpha")!.published).toBe(true);
+    expect(byName.get("alpha")!.internal).toBe(false);
+    expect(byName.get("gamma")!.published).toBe(false); // unlisted by manifest
+    expect(byName.get("secret")!.published).toBe(false); // internal excluded
+    expect(byName.get("secret")!.internal).toBe(true);
+  });
+
+  test("--list is never gated even over a large repo", async () => {
+    const specs: SkillSpec[] = Array.from({ length: 30 }, (_, i) => ({
+      path: `skills/s${String(i).padStart(2, "0")}`,
+    }));
+    const repo = await makeRepo(tmp, specs);
+    const { ctx, json } = makeCtx(library);
+    const code = await run([`git:${repo}`, "--list", "--json"], ctx);
+    expect(code).toBe(0);
+    const out = json[0] as { skills: unknown[] };
+    expect(out.skills.length).toBe(30);
+  });
+
+  // (g) no-manifest repo still installs every (valid) discovered skill, under the gate.
+  test("no-manifest repo: --all installs every skill (today's behavior)", async () => {
+    const repo = await makeRepo(tmp, [
+      { path: "skills/alpha" },
+      { path: "skills/beta" },
+      { path: "skills/gamma" },
+    ]);
+    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 { counts: { installed: number } };
+    expect(out.counts.installed).toBe(3);
+  });
+
+  // --dry-run runs over the PUBLISHED set (the set --all would install), never gated.
+  test("--dry-run preflights only the published set", async () => {
+    const repo = await makeRepo(
+      tmp,
+      [
+        { path: "engineering/alpha" },
+        { path: "deprecated/gamma" },
+      ],
+      { kind: "plugin", json: { name: "x", skills: ["./engineering/alpha"] } },
+    );
+    const { ctx, json } = makeCtx(library);
+    const code = await run([`git:${repo}`, "--all", "--dry-run", "--json"], ctx);
+    expect(code).toBe(0);
+    const out = json[0] as { skills: Array<{ name: string }>; willInstall: number };
+    const names = out.skills.map((s) => s.name).sort();
+    expect(names).toEqual(["alpha"]); // gamma is unpublished -> not previewed
+    expect(out.willInstall).toBe(1);
+  });
+
+  // Discovery still finds EVERYTHING (existence) — the manifest is an allowlist, not a source of truth.
+  test("discoverSkills still surfaces all skills, tagged published/internal", async () => {
+    const repo = await makeRepo(
+      tmp,
+      [
+        { path: "engineering/alpha" },
+        { path: "deprecated/gamma" },
+        { path: "engineering/secret", internal: true },
+      ],
+      { kind: "plugin", json: { name: "x", skills: ["./engineering/alpha", "./engineering/secret"] } },
+    );
+    // discoverSkills runs against a CHECKOUT root; clone manually to a plain dir.
+    const checkout = join(tmp, "checkout");
+    await Bun.spawn(["git", "clone", "-q", repo, checkout], { stdout: "ignore", stderr: "ignore" }).exited;
+    const found = await discoverSkills(checkout);
+    const byName = new Map(found.map((d) => [d.name, d]));
+    expect(found.length).toBe(3);
+    expect(byName.get("alpha")!.published).toBe(true);
+    expect(byName.get("gamma")!.published).toBe(false);
+    expect(byName.get("secret")!.published).toBe(false);
+    expect(byName.get("secret")!.internal).toBe(true);
+  });
+
+  // A manifest entry that points at a path with no valid SKILL.md contributes nothing.
+  test("manifest allowlisting a nonexistent path contributes nothing", async () => {
+    const repo = await makeRepo(
+      tmp,
+      [{ path: "engineering/alpha" }],
+      { kind: "plugin", json: { name: "x", skills: ["./engineering/alpha", "./does/not/exist"] } },
+    );
+    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 { counts: { installed: number } };
+    expect(out.counts.installed).toBe(1);
+  });
+});

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");
+  });
+});