skillshelf 0.4.1 → 0.5.0

package/README.md

@@ -3,7 +3,7 @@
 **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)
 
@@ -46,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`
@@ -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.1",
+  "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.ts

@@ -37,7 +37,7 @@ import { parseFrontmatter } from "../lib/frontmatter.ts";
 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 { assertSafeName, SLUG_RE } from "../core/lifecycle.ts";
 import { loadLibrary, findByName, entryStatus } from "../core/library.ts";
 import { ensureDir, isSymlink, realpathOrSelf } from "../lib/fs.ts";
 
@@ -45,15 +45,25 @@ export const meta = {
   name: "add",
   summary: "Install third-party skill(s) (github:/git:/registry); repo-wide via --all/--skill",
   usage:
-    "skl add <src> [--all|--skill <a,b,…>] [--list] [--dry-run] [--domain <d>] [--name <slug>] [--no-infer] [--force] [--json]",
+    "skl add <src> [--all|--skill <a,b,…>] [--list] [--dry-run] [--domain <d>] [--name <slug>] [--no-infer] [--force] [--yes] [--json]",
 } as const;
 
+/**
+ * The `--all` count gate threshold (ADR-0012): if the resolved published set has MORE
+ * than this many skills, `add --all` refuses (bounds blast radius) until the user passes
+ * `--yes`, narrows with `--skill`, or inspects with `--list`. `--skill`/`--list`/`--dry-run`
+ * are never gated. On the count, not the provenance — manifest or full discovery alike.
+ */
+export const ALL_COUNT_GATE = 15;
+
 interface Flags {
   json: boolean;
   domain: string | null;
   name: string | null;
   infer: boolean;
   force: boolean;
+  /** bypass ONLY the --all count gate (distinct from --force = overwrite differing body) */
+  yes: boolean;
   all: boolean;
   list: boolean;
   dryRun: boolean;
@@ -62,11 +72,10 @@ interface Flags {
   src: string | null;
 }
 
-// A skill slug is lowercase letters/digits/hyphens. This is also a SECURITY guard:
+// SLUG_RE is shared from core/lifecycle.ts. This is also a SECURITY guard here:
 // `name` may be derived from an untrusted third-party SKILL.md frontmatter and
 // `domain` from a flag, and both are joined into a library path. Rejecting anything
 // outside this charset stops `..`/`/` path traversal out of the library.
-const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
 
 function addSkillFilter(cur: string[] | null, raw: string): string[] {
   const names = raw.split(",").map((s) => s.trim()).filter((s) => s !== "");
@@ -80,6 +89,7 @@ function parseFlags(argv: string[]): Flags {
     name: null,
     infer: true,
     force: false,
+    yes: false,
     all: false,
     list: false,
     dryRun: false,
@@ -91,6 +101,7 @@ function parseFlags(argv: string[]): Flags {
     if (a === "--json") f.json = true;
     else if (a === "--no-infer") f.infer = false;
     else if (a === "--force") f.force = true;
+    else if (a === "--yes") f.yes = true;
     else if (a === "--all") f.all = true;
     else if (a === "--list") f.list = true;
     else if (a === "--dry-run") f.dryRun = true;
@@ -165,36 +176,15 @@ async function driftVerdict(skill: DiscoveredSkill, destDir: string): Promise<Ve
 }
 
 /**
- * Optionally run an AI inference tagging pass over a freshly-installed skill.
- *
- * A MISSING hook module is expected and stays silent (untagged is valid). But a hook
- * that IS present and THROWS is a real failure — we surface it via `warn` rather than
- * swallowing it. Either way the skill stays untagged. Returns the domains written.
+ * Optional AI inference tagging pass over a freshly-installed skill. No inference hook
+ * ships today, so this always leaves the skill untagged (returns null); installs land
+ * with whatever `--domain` gave them. Kept as a seam so `--infer`/`--no-infer` and the
+ * `tagged` summary field stay meaningful when a hook is wired in.
  */
 async function maybeInferTags(
-  skill: Skill,
-  warn?: (msg: string) => void,
+  _skill: Skill,
+  _warn?: (msg: string) => void,
 ): Promise<string[] | null> {
-  const candidates = ["../core/infer.ts", "../adapters/inference/tag.ts"];
-  for (const rel of candidates) {
-    const spec: string = rel;
-    const mod: unknown = await import(spec).catch(() => null);
-    if (!mod || typeof mod !== "object") continue;
-    const hook = (mod as Record<string, unknown>).tagSkill;
-    if (typeof hook !== "function") continue;
-    try {
-      const result = await (hook as (s: Skill) => Promise<string[] | null>)(skill);
-      if (Array.isArray(result)) {
-        return result.filter((d) => typeof d === "string" && d.trim() !== "");
-      }
-      return null;
-    } catch (err) {
-      warn?.(
-        `add: inference hook ${rel} failed (skill left untagged): ${err instanceof Error ? err.message : String(err)}`,
-      );
-      return null;
-    }
-  }
   return null;
 }
 
@@ -391,20 +381,27 @@ function reportList(
     description: d.description,
     subpath: d.subpath,
     inLibrary: Boolean(findByName(library, d.name)),
+    // ADR-0012: keep the FULL set visible, marked by published-set membership, so an
+    // unpublished/internal skill is discoverable even though `--all` skips it.
+    published: d.published,
+    internal: d.internal,
   }));
   if (flags.json) {
     ctx.json({ ok: true, action: "list", source: parsed.source, ref, count: rows.length, skills: rows });
     return 0;
   }
-  ctx.log(`${rows.length} skill(s) in ${parsed.source}${ref ? ` @ ${ref.slice(0, 10)}` : ""}:`);
+  const publishedCount = rows.filter((r) => r.published).length;
+  ctx.log(`${rows.length} skill(s) in ${parsed.source}${ref ? ` @ ${ref.slice(0, 10)}` : ""} (${publishedCount} published):`);
   ctx.log("");
   for (const r of rows) {
     const mark = r.inLibrary ? "✓" : " ";
-    ctx.log(`  ${mark} ${r.name.padEnd(28)} ${r.subpath || "(root)"}`);
+    const tag = r.published ? "published  " : r.internal ? "internal   " : "unpublished";
+    ctx.log(`  ${mark} ${tag}  ${r.name.padEnd(28)} ${r.subpath || "(root)"}`);
     if (r.description) ctx.log(`      ${r.description.length > 100 ? r.description.slice(0, 99) + "…" : r.description}`);
   }
   ctx.log("");
-  ctx.log(`✓ = already in your library. Install with: skl add ${flags.src} --all   (or --skill <name,…>)`);
+  ctx.log(`✓ = already in your library. published = installed by --all; unpublished/internal = only via --skill <name>.`);
+  ctx.log(`Install with: skl add ${flags.src} --all   (or --skill <name,…>)`);
   return 0;
 }
 
@@ -554,7 +551,11 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     const { data } = parseFrontmatter(body);
     const nm = typeof data.name === "string" && data.name.trim() !== "" ? data.name.trim() : basename(fetched.skillDir);
     const desc = typeof data.description === "string" ? data.description.trim() : "";
-    discovered = [{ name: nm, dir: fetched.skillDir, subpath: "", description: desc }];
+    const meta = data.metadata;
+    const internal =
+      typeof meta === "object" && meta !== null && (meta as Record<string, unknown>).internal === true;
+    // Single registry/explicit skill: no manifest context → published unless internal.
+    discovered = [{ name: nm, dir: fetched.skillDir, subpath: "", description: desc, internal, published: !internal }];
   }
 
   try {
@@ -574,9 +575,16 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
       return reportList(ctx, flags, parsed, ref, discovered, library);
     }
 
-    // ---- --dry-run (drift preflight over the full set, no writes) ----
+    // ---- --dry-run (drift preflight, no writes) ----
+    // Over the set it WOULD install: the published set for --all (ADR-0012), the named
+    // subset for --skill, else the full discovered set. Never gated (it doesn't write).
     if (flags.dryRun) {
-      return await reportDryRun(ctx, flags, parsed, ref, discovered, domainFolder);
+      const preview = flags.all
+        ? discovered.filter((d) => d.published)
+        : flags.skill !== null
+          ? discovered.filter((d) => flags.skill!.includes(d.name))
+          : discovered;
+      return await reportDryRun(ctx, flags, parsed, ref, preview, domainFolder);
     }
 
     // ---- selection ----
@@ -593,7 +601,26 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
       }
       multi = true;
     } else if (flags.all) {
-      selected = discovered;
+      // ADR-0012: --all installs the PUBLISHED set (manifest allowlist when present,
+      // else every discovered skill), always minus internal skills.
+      selected = discovered.filter((d) => d.published);
+      if (selected.length === 0) {
+        ctx.error(
+          `add: no published skills in ${parsed.source} — every discovered skill is unpublished or internal` +
+            ` (e.g. a .claude-plugin manifest that lists none/is unreadable, or skills marked metadata.internal).`,
+        );
+        ctx.error(`     inspect the full set with --list, or install one by name with --skill <name>.`);
+        return 1;
+      }
+      // COUNT GATE: refuse a large blast radius unless --yes. On the final selected
+      // count, regardless of provenance. --skill/--list/--dry-run are never gated.
+      if (selected.length > ALL_COUNT_GATE && !flags.yes) {
+        ctx.error(
+          `add: ${selected.length} published skills in ${parsed.source} exceeds the --all gate of ${ALL_COUNT_GATE}.`,
+        );
+        ctx.error(`     re-run with --yes to install them all, narrow with --skill <name,…>, or inspect with --list.`);
+        return 1;
+      }
       multi = true;
     } else if (discovered.length > 1) {
       ctx.error(