diff --git a/commands/__tests__/skills-surface.test.ts b/commands/__tests__/skills-surface.test.ts
new file mode 100644
index 00000000..7571e479
--- /dev/null
+++ b/commands/__tests__/skills-surface.test.ts
@@ -0,0 +1,438 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { execFileSync } from "child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, join } from "path";
+import { computeRows, decidePaletteAction, skillsSurface } from "../skills.ts";
+
+function writeFile(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+}
+
+function makePackDir(): string {
+  return realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-surface-pack-")));
+}
+
+function writeStubs(packDir: string, verbs: Record<string, { engine: string; description: string }>): void {
+  writeFile(join(packDir, "pack", "stubs.jsonc"), JSON.stringify({ verbs }));
+}
+
+/** Trivial no-slot pipeline-step engine + fixture mattstack root, for apply's compile delegation. */
+function makeEngineFixture(): { mattstackDir: string; manifestPath: string } {
+  const mattstackDir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-surface-mattstack-")));
+  writeFile(
+    join(mattstackDir, "plugins", "mattstack", ".claude-plugin", "plugin.json"),
+    JSON.stringify({ version: "1.0.0" }),
+  );
+  writeFile(
+    join(mattstackDir, "plugins", "mattstack", "skills", "pipeline", "my-verb", "SKILL.md"),
+    `---\nname: my-verb\ndescription: "Do the thing"\ntype: pipeline-step\n---\n\nDo the thing.\n`,
+  );
+
+  const manifestDir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-surface-manifest-")));
+  const manifestPath = join(manifestDir, "skills.jsonc");
+  writeFile(manifestPath, JSON.stringify({ bindings: {} }));
+
+  return { mattstackDir, manifestPath };
+}
+
+let logSpy: ReturnType<typeof spyOn>;
+let logs: string[];
+
+beforeEach(() => {
+  logs = [];
+  logSpy = spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+    logs.push(args.map(String).join(" "));
+  });
+});
+
+afterEach(() => {
+  logSpy.mockRestore();
+  // Bun ignores process.exitCode = undefined once truthy; 0 is the only value that clears it.
+  process.exitCode = 0;
+});
+
+async function runExpectingCleanExit(fn: () => Promise<void>): Promise<{ exitCode: number | undefined; errors: string[] }> {
+  const errors: string[] = [];
+  const exitSpy = spyOn(process, "exit").mockImplementation(() => {
+    throw new Error("process.exit sentinel");
+  });
+  const errorSpy = spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+    errors.push(args.map(String).join(" "));
+  });
+  try {
+    await fn();
+    return { exitCode: undefined, errors };
+  } catch {
+    const exitCode = exitSpy.mock.calls.at(-1)?.[0] as number | undefined;
+    return { exitCode, errors };
+  } finally {
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  }
+}
+
+describe("skillsSurface list", () => {
+  test("no surface.jsonc: infers public/internal from current skills/ + attachments/ + stub verbs", async () => {
+    const packDir = makePackDir();
+    writeStubs(packDir, { "my-verb": { engine: "my-verb", description: "Do the thing" } });
+    writeFile(join(packDir, "skills", "hand-authored-public", "SKILL.md"), "---\nname: x\n---\nbody\n");
+    writeFile(join(packDir, "attachments", "hand-authored-internal", "SKILL.md"), "---\nname: y\n---\nbody\n");
+
+    await skillsSurface(["list", "--team", "t", "--pack-dir", packDir]);
+
+    const out = logs.join("\n");
+    expect(out).toContain("no surface.jsonc");
+    expect(out).toMatch(/public.*hand-authored-public/);
+    expect(out).toMatch(/internal.*hand-authored-internal/);
+    expect(out).toMatch(/public.*compiled.*my-verb/);
+  });
+
+  test("with surface.jsonc: statuses reflect the config, not disk placement", async () => {
+    const packDir = makePackDir();
+    writeStubs(packDir, {});
+    writeFile(join(packDir, "skills", "still-under-skills", "SKILL.md"), "---\nname: z\n---\nbody\n");
+    writeFile(join(packDir, "pack", "surface.jsonc"), JSON.stringify({ public: [] }));
+
+    await skillsSurface(["list", "--team", "t", "--pack-dir", packDir]);
+
+    const out = logs.join("\n");
+    expect(out).toContain("pack/surface.jsonc");
+    expect(out).toMatch(/internal.*still-under-skills/);
+  });
+
+  test("unrecognized argument: clean one-line error, exit 1", async () => {
+    const { exitCode, errors } = await runExpectingCleanExit(() =>
+      skillsSurface(["list", "--bogus"]),
+    );
+    expect(exitCode).toBe(1);
+    expect(errors[0]).toStartWith("rt skills: ");
+    expect(errors[0]).toContain("--bogus");
+  });
+});
+
+describe("skillsSurface set", () => {
+  test("--public on an attachments/ dir: bootstraps surface.jsonc, moves it to skills/ via apply (plain rename, no git repo)", async () => {
+    const packDir = makePackDir();
+    writeStubs(packDir, {});
+    writeFile(join(packDir, "attachments", "my-attach", "SKILL.md"), "---\nname: a\n---\nbody\n");
+    const { mattstackDir, manifestPath } = makeEngineFixture();
+
+    await skillsSurface([
+      "set", "my-attach", "--public",
+      "--team", "t", "--pack-dir", packDir, "--mattstack-dir", mattstackDir, "--manifest", manifestPath,
+    ]);
+
+    const surfacePath = join(packDir, "pack", "surface.jsonc");
+    expect(existsSync(surfacePath)).toBe(true);
+    const surface = JSON.parse(readFileSync(surfacePath, "utf8").replace(/^\/\/.*\n/, ""));
+    expect(surface.public).toContain("my-attach");
+
+    expect(existsSync(join(packDir, "skills", "my-attach", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(packDir, "attachments", "my-attach"))).toBe(false);
+
+    const out = logs.join("\n");
+    expect(out).toContain("not a git repo");
+  });
+
+  test("--internal on a skills/ dir: bootstraps surface.jsonc, moves it to attachments/ via apply", async () => {
+    const packDir = makePackDir();
+    writeStubs(packDir, {});
+    writeFile(join(packDir, "skills", "my-skill", "SKILL.md"), "---\nname: s\n---\nbody\n");
+    const { mattstackDir, manifestPath } = makeEngineFixture();
+
+    await skillsSurface([
+      "set", "my-skill", "--internal",
+      "--team", "t", "--pack-dir", packDir, "--mattstack-dir", mattstackDir, "--manifest", manifestPath,
+    ]);
+
+    expect(existsSync(join(packDir, "attachments", "my-skill", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(packDir, "skills", "my-skill"))).toBe(false);
+
+    const surfacePath = join(packDir, "pack", "surface.jsonc");
+    const surface = JSON.parse(readFileSync(surfacePath, "utf8").replace(/^\/\/.*\n/, ""));
+    expect(surface.public).not.toContain("my-skill");
+  });
+
+  test("--internal on a compiled stub verb: surface.jsonc updated, apply removes the compiled dir (never git-mv'd)", async () => {
+    const packDir = makePackDir();
+    writeStubs(packDir, { "my-verb": { engine: "my-verb", description: "Do the thing" } });
+    writeFile(join(packDir, "skills", "my-verb", "SKILL.md"), "---\nname: my-verb\n---\nold compiled content\n");
+    const { mattstackDir, manifestPath } = makeEngineFixture();
+
+    await skillsSurface([
+      "set", "my-verb", "--internal",
+      "--team", "t", "--pack-dir", packDir, "--mattstack-dir", mattstackDir, "--manifest", manifestPath,
+    ]);
+
+    expect(existsSync(join(packDir, "skills", "my-verb"))).toBe(false);
+    expect(existsSync(join(packDir, "attachments", "my-verb"))).toBe(false);
+
+    const out = logs.join("\n");
+    expect(out).not.toContain("moved my-verb");
+  });
+
+  test("--public on a compiled stub verb (bootstrap default already public): apply compiles it", async () => {
+    const packDir = makePackDir();
+    writeStubs(packDir, { "my-verb": { engine: "my-verb", description: "Do the thing" } });
+    const { mattstackDir, manifestPath } = makeEngineFixture();
+
+    await skillsSurface([
+      "set", "my-verb", "--public",
+      "--team", "t", "--pack-dir", packDir, "--mattstack-dir", mattstackDir, "--manifest", manifestPath,
+    ]);
+
+    const skillMd = readFileSync(join(packDir, "skills", "my-verb", "SKILL.md"), "utf8");
+    expect(skillMd).toContain("compiled by rt skills compile");
+  });
+
+  test("uses a real git mv when the pack dir is a git repo", async () => {
+    const packDir = makePackDir();
+    execFileSync("git", ["init", "-q"], { cwd: packDir });
+    execFileSync("git", ["config", "user.email", "t@example.com"], { cwd: packDir });
+    execFileSync("git", ["config", "user.name", "t"], { cwd: packDir });
+    writeStubs(packDir, {});
+    writeFile(join(packDir, "skills", "my-skill", "SKILL.md"), "---\nname: s\n---\nbody\n");
+    execFileSync("git", ["add", "-A"], { cwd: packDir });
+    const { mattstackDir, manifestPath } = makeEngineFixture();
+
+    await skillsSurface([
+      "set", "my-skill", "--internal",
+      "--team", "t", "--pack-dir", packDir, "--mattstack-dir", mattstackDir, "--manifest", manifestPath,
+    ]);
+
+    expect(existsSync(join(packDir, "attachments", "my-skill", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(packDir, "skills", "my-skill"))).toBe(false);
+    // git mv on a never-committed add reports as a plain staged add at the new
+    // path (git has no prior commit to diff a rename against).
+    const status = execFileSync("git", ["status", "--porcelain"], { cwd: packDir, encoding: "utf8" });
+    expect(status).toContain("attachments/my-skill");
+
+    const out = logs.join("\n");
+    expect(out).not.toContain("not a git repo");
+  });
+
+  test("unknown name: clean one-line error, exit 1", async () => {
+    const packDir = makePackDir();
+    writeStubs(packDir, {});
+
+    const { exitCode, errors } = await runExpectingCleanExit(() =>
+      skillsSurface(["set", "no-such-skill", "--public", "--pack-dir", packDir]),
+    );
+
+    expect(exitCode).toBe(1);
+    expect(errors[0]).toStartWith("rt skills: ");
+    expect(errors[0]).toContain("no-such-skill");
+  });
+
+  test("missing --public/--internal: clean one-line error, exit 1", async () => {
+    const packDir = makePackDir();
+    writeStubs(packDir, {});
+    writeFile(join(packDir, "skills", "my-skill", "SKILL.md"), "---\nname: s\n---\nbody\n");
+
+    const { exitCode, errors } = await runExpectingCleanExit(() =>
+      skillsSurface(["set", "my-skill", "--pack-dir", packDir]),
+    );
+
+    expect(exitCode).toBe(1);
+    expect(errors[0]).toStartWith("rt skills: ");
+  });
+
+  test("missing name: clean one-line error, exit 1", async () => {
+    const { exitCode, errors } = await runExpectingCleanExit(() =>
+      skillsSurface(["set", "--public"]),
+    );
+
+    expect(exitCode).toBe(1);
+    expect(errors[0]).toStartWith("rt skills: ");
+  });
+});
+
+describe("skillsSurface apply", () => {
+  test("dry-run prints planned moves and touches nothing", async () => {
+    const packDir = makePackDir();
+    writeStubs(packDir, {});
+    writeFile(join(packDir, "attachments", "my-attach", "SKILL.md"), "---\nname: a\n---\nbody\n");
+    writeFile(join(packDir, "pack", "surface.jsonc"), JSON.stringify({ public: ["my-attach"] }));
+    const { mattstackDir, manifestPath } = makeEngineFixture();
+
+    await skillsSurface([
+      "apply", "--dry-run",
+      "--team", "t", "--pack-dir", packDir, "--mattstack-dir", mattstackDir, "--manifest", manifestPath,
+    ]);
+
+    expect(existsSync(join(packDir, "attachments", "my-attach"))).toBe(true);
+    expect(existsSync(join(packDir, "skills", "my-attach"))).toBe(false);
+    expect(logs.some((l) => l.includes("would move") && l.includes("my-attach"))).toBe(true);
+  });
+
+  test("no surface.jsonc: no moves, compiles the roster as usual", async () => {
+    const packDir = makePackDir();
+    writeStubs(packDir, { "my-verb": { engine: "my-verb", description: "Do the thing" } });
+    const { mattstackDir, manifestPath } = makeEngineFixture();
+
+    await skillsSurface([
+      "apply",
+      "--team", "t", "--pack-dir", packDir, "--mattstack-dir", mattstackDir, "--manifest", manifestPath,
+    ]);
+
+    expect(logs.some((l) => l.includes("no moves needed"))).toBe(true);
+    expect(existsSync(join(packDir, "skills", "my-verb", "SKILL.md"))).toBe(true);
+  });
+
+  test("unrecognized argument: clean one-line error, exit 1", async () => {
+    const { exitCode, errors } = await runExpectingCleanExit(() =>
+      skillsSurface(["apply", "--bogus"]),
+    );
+    expect(exitCode).toBe(1);
+    expect(errors[0]).toStartWith("rt skills: ");
+  });
+});
+
+describe("skillsSurface bare invocation (fzf palette)", () => {
+  test("non-tty: prints the list and the set-command hint, does not crash or write config", async () => {
+    const packDir = makePackDir();
+    writeStubs(packDir, {});
+    writeFile(join(packDir, "skills", "my-skill", "SKILL.md"), "---\nname: s\n---\nbody\n");
+
+    // bun test inherits stdin from the shell; force the non-tty fallback so this
+    // never spawns real fzf on an interactive run.
+    const previousIsTTY = process.stdin.isTTY;
+    Object.defineProperty(process.stdin, "isTTY", { value: false, configurable: true });
+    try {
+      await skillsSurface(["--team", "t", "--pack-dir", packDir]);
+    } finally {
+      Object.defineProperty(process.stdin, "isTTY", { value: previousIsTTY, configurable: true });
+    }
+
+    expect(existsSync(join(packDir, "pack", "surface.jsonc"))).toBe(false);
+    const out = logs.join("\n");
+    expect(out).toContain("my-skill");
+    expect(out).toContain("rt skills surface set");
+  });
+
+  test("empty pack: prints a no-skills message instead of crashing", async () => {
+    const packDir = makePackDir();
+    writeStubs(packDir, {});
+
+    await skillsSurface(["--pack-dir", packDir]);
+
+    expect(logs.some((l) => l.includes("no skills registered"))).toBe(true);
+  });
+
+  test("unrecognized subcommand: clean one-line error, exit 1", async () => {
+    const { exitCode, errors } = await runExpectingCleanExit(() =>
+      skillsSurface(["bogus-mode"]),
+    );
+    expect(exitCode).toBe(1);
+    expect(errors[0]).toStartWith("rt skills: ");
+    expect(errors[0]).toContain("bogus-mode");
+  });
+});
+
+describe("decidePaletteAction", () => {
+  test("zero-marked cursor-row artifact shows as a +1 delta the user can decline", () => {
+    // Everything was internal; fzf's default --multi accept on Enter with
+    // nothing marked emits the cursor row anyway -- that row now reads
+    // "public" in resultRows even though the user meant to uncheck everything.
+    const previousPublic = new Set<string>();
+    const resultRows = [{ name: "x", status: "public" as const }];
+
+    const action = decidePaletteAction(previousPublic, resultRows, false);
+
+    expect(action.kind).toBe("declined");
+    if (action.kind !== "no-changes") {
+      expect(action.delta.toPublic).toEqual(["x"]);
+      expect(action.delta.toInternal).toEqual([]);
+    }
+  });
+
+  test("decline writes nothing: the confirmed=false path never yields a write action", () => {
+    const previousPublic = new Set<string>();
+    const resultRows = [{ name: "x", status: "public" as const }];
+
+    const action = decidePaletteAction(previousPublic, resultRows, false);
+
+    expect(action.kind).not.toBe("write");
+  });
+
+  test("confirming a real delta yields a write action carrying it", () => {
+    const previousPublic = new Set(["y"]);
+    const resultRows = [
+      { name: "x", status: "public" as const },
+      { name: "y", status: "internal" as const },
+    ];
+
+    const action = decidePaletteAction(previousPublic, resultRows, true);
+
+    expect(action.kind).toBe("write");
+    if (action.kind === "write") {
+      expect(action.delta.toPublic).toEqual(["x"]);
+      expect(action.delta.toInternal).toEqual(["y"]);
+    }
+  });
+
+  test("no changes short-circuits regardless of the confirm answer", () => {
+    const previousPublic = new Set(["x"]);
+    const resultRows = [{ name: "x", status: "public" as const }];
+
+    expect(decidePaletteAction(previousPublic, resultRows, false).kind).toBe("no-changes");
+    expect(decidePaletteAction(previousPublic, resultRows, true).kind).toBe("no-changes");
+  });
+});
+
+describe("computeRows -- previously-public names absent from skills/, attachments/, stubs.jsonc", () => {
+  test("surfaces the orphan as a 'missing' row instead of dropping it", () => {
+    const packDir = makePackDir();
+    writeStubs(packDir, {});
+    writeFile(join(packDir, "skills", "real-skill", "SKILL.md"), "---\nname: real-skill\n---\nbody\n");
+
+    const surface = { public: ["ghost", "real-skill"] };
+    const { rows } = computeRows(packDir, new Set(), surface);
+
+    const ghostRow = rows.find((r) => r.name === "ghost");
+    expect(ghostRow).toEqual({ name: "ghost", kind: "missing", status: "public" });
+    const realRow = rows.find((r) => r.name === "real-skill");
+    expect(realRow?.status).toBe("public");
+  });
+
+  test("combined with decidePaletteAction: leaving the missing row untouched yields no delta", () => {
+    const packDir = makePackDir();
+    writeStubs(packDir, {});
+
+    const surface = { public: ["ghost"] };
+    const { rows } = computeRows(packDir, new Set(), surface);
+    const previousPublic = new Set(surface.public);
+
+    // Simulates the palette round trip: the fzf row for "ghost" exists and stays
+    // preselected because the user never touched it.
+    const resultRows = rows.map((r) => ({ name: r.name, status: r.status }));
+
+    const action = decidePaletteAction(previousPublic, resultRows, false);
+    expect(action.kind).toBe("no-changes");
+  });
+
+  test("combined with decidePaletteAction: explicitly demoting the missing row surfaces the removal", () => {
+    const packDir = makePackDir();
+    writeStubs(packDir, {});
+
+    const surface = { public: ["ghost"] };
+    const { rows } = computeRows(packDir, new Set(), surface);
+    const previousPublic = new Set(surface.public);
+
+    const resultRows = rows.map((r) => ({ name: r.name, status: "internal" as const }));
+
+    const preview = decidePaletteAction(previousPublic, resultRows, false);
+    expect(preview.kind).toBe("declined");
+    if (preview.kind !== "no-changes") {
+      expect(preview.delta.toInternal).toEqual(["ghost"]);
+    }
+
+    const decision = decidePaletteAction(previousPublic, resultRows, true);
+    expect(decision.kind).toBe("write");
+    if (decision.kind === "write") {
+      expect(decision.delta.toInternal).toEqual(["ghost"]);
+    }
+  });
+});
diff --git a/commands/__tests__/skills.test.ts b/commands/__tests__/skills.test.ts
new file mode 100644
index 00000000..63acf1b1
--- /dev/null
+++ b/commands/__tests__/skills.test.ts
@@ -0,0 +1,450 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, statSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, join } from "path";
+import { skillsCheck, skillsCompile } from "../skills.ts";
+import { compileSkill } from "../../lib/skills/compile.ts";
+import { invocableRoster, loadAttachment, loadStepSource } from "../../lib/skills/sources.ts";
+import type { PluginRoots } from "../../lib/skills/sources.ts";
+import type { VerbDef } from "../../lib/skills/types.ts";
+
+function writeFile(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+}
+
+const WATCH_CI_SKILL_MD = `---
+name: watch-ci
+description: "Watch CI until it goes green"
+type: pipeline-step
+allowed-tools:
+  - "Bash(gh:*)"
+  - "Read"
+slots:
+  domain: { contract: "watch-ci-domain@1" }
+  forge: { contract: "ci-forge@1", required: true }
+---
+
+Poll the pipeline every 30s and report status. See \${CLAUDE_SKILL_DIR}/scripts/ci-watch.sh for the poller.
+`;
+
+const WATCH_CI_SCRIPT = "#!/bin/sh\necho polling\n";
+
+const DOMAIN_SKILL_MD = `---
+name: watch-ci-domain
+description: "Domain rules for watch-ci"
+metadata:
+  provides: "watch-ci-domain@1"
+allowed-tools:
+  - "Read(\${CLAUDE_SKILL_DIR}/ci-config.json)"
+---
+
+Domain rules live at \${CLAUDE_SKILL_DIR}/ci-config.json for details.
+`;
+
+const CI_CONFIG_JSON = `{ "noisy": ["flaky-job"] }\n`;
+
+const FORGE_SKILL_MD = `---
+name: gitlab-forge
+description: "Talk to GitLab via glab"
+metadata:
+  provides: "ci-forge@1"
+allowed-tools:
+  - "Bash(glab:*)"
+---
+
+Talk to GitLab via glab.
+`;
+
+const STUBS_JSONC = `{
+  "verbs": {
+    "watch-ci": {
+      "engine": "watch-ci",
+      "description": "Use when watching or triaging CI."
+    }
+  }
+}
+`;
+
+function manifestJsonc(team: string, withForge: boolean): string {
+  const bindings = withForge
+    ? `{
+      "domain": "claimview:watch-ci-domain",
+      "forge": "mattstack:gitlab-forge"
+    }`
+    : `{
+      "domain": "claimview:watch-ci-domain"
+    }`;
+  return `// GENERATED by merge-manifests.sh -- do not hand-edit;
+// provenance (binding <- source):
+//   mattstack:watch-ci domain <- ${team}@${team}
+{
+  "bindings": {
+    "mattstack:watch-ci": ${bindings}
+  }
+}
+`;
+}
+
+/**
+ * Fixture "mattstack home" root: plugins/<name>/ mirrors resolvePluginRoots()'s
+ * real shape (dir + .claude-plugin/plugin.json) so skillsCompile's test-mode
+ * root resolution and the golden compile below walk identical trees.
+ */
+function makeMattstackDir(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-cli-mattstack-")));
+
+  const mattstackPluginDir = join(dir, "plugins", "mattstack");
+  writeFile(join(mattstackPluginDir, ".claude-plugin", "plugin.json"), JSON.stringify({ version: "1.2.0" }));
+  writeFile(join(mattstackPluginDir, "skills", "pipeline", "watch-ci", "SKILL.md"), WATCH_CI_SKILL_MD);
+  writeFile(join(mattstackPluginDir, "skills", "pipeline", "watch-ci", "scripts", "ci-watch.sh"), WATCH_CI_SCRIPT);
+  chmodSync(join(mattstackPluginDir, "skills", "pipeline", "watch-ci", "scripts", "ci-watch.sh"), 0o755);
+  writeFile(join(mattstackPluginDir, "skills", "gitlab-forge", "SKILL.md"), FORGE_SKILL_MD);
+
+  const claimviewPluginDir = join(dir, "plugins", "claimview");
+  writeFile(join(claimviewPluginDir, ".claude-plugin", "plugin.json"), JSON.stringify({ version: "0.3.0" }));
+  writeFile(join(claimviewPluginDir, "attachments", "watch-ci-domain", "SKILL.md"), DOMAIN_SKILL_MD);
+  writeFile(join(claimviewPluginDir, "attachments", "watch-ci-domain", "ci-config.json"), CI_CONFIG_JSON);
+
+  return dir;
+}
+
+function makePackDir(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-cli-pack-")));
+  writeFile(join(dir, "pack", "stubs.jsonc"), STUBS_JSONC);
+  return dir;
+}
+
+function makeManifest(team: string, withForge = true): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-cli-manifest-")));
+  const path = join(dir, "skills.jsonc");
+  writeFile(path, manifestJsonc(team, withForge));
+  return path;
+}
+
+function computeGolden(mattstackDir: string) {
+  const roots: PluginRoots = {
+    byName: {
+      mattstack: { dir: join(mattstackDir, "plugins", "mattstack"), version: "1.2.0" },
+      claimview: { dir: join(mattstackDir, "plugins", "claimview"), version: "0.3.0" },
+    },
+  };
+  const verb: VerbDef = { name: "watch-ci", engine: "watch-ci", description: "Use when watching or triaging CI." };
+  const step = loadStepSource("watch-ci", roots);
+  const domain = loadAttachment("claimview:watch-ci-domain", "domain", roots);
+  const forge = loadAttachment("mattstack:gitlab-forge", "forge", roots);
+  const invocable = invocableRoster(roots);
+  return compileSkill(verb, step, { domain, forge }, invocable);
+}
+
+let logSpy: ReturnType<typeof spyOn>;
+let logs: string[];
+
+beforeEach(() => {
+  logs = [];
+  logSpy = spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+    logs.push(args.map(String).join(" "));
+  });
+});
+
+afterEach(() => {
+  logSpy.mockRestore();
+  // skillsCheck sets this on staleness; Bun ignores process.exitCode = undefined once
+  // truthy, so 0 is the only value that clears it before the suite's own exit status.
+  process.exitCode = 0;
+});
+
+/**
+ * Expected/domain errors print a clean one-liner and process.exit(1) instead
+ * of throwing a bare stack trace (matches commands/secrets.ts,
+ * commands/settings-keys.ts). Mock process.exit to throw a sentinel so the
+ * real test process never dies, and read the spies' recorded calls BEFORE
+ * mockRestore() -- bun's mockRestore() clears .mock.calls, unlike jest's.
+ */
+async function runExpectingCleanExit(fn: () => Promise<void>): Promise<{ exitCode: number | undefined; errors: string[] }> {
+  const errors: string[] = [];
+  const exitSpy = spyOn(process, "exit").mockImplementation(() => {
+    throw new Error("process.exit sentinel");
+  });
+  const errorSpy = spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+    errors.push(args.map(String).join(" "));
+  });
+  try {
+    await fn();
+    return { exitCode: undefined, errors };
+  } catch {
+    const exitCode = exitSpy.mock.calls.at(-1)?.[0] as number | undefined;
+    return { exitCode, errors };
+  } finally {
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  }
+}
+
+describe("skillsCompile", () => {
+  test("dry-run prints a would-write summary and writes nothing", async () => {
+    const mattstackDir = makeMattstackDir();
+    const packDir = makePackDir();
+    const manifestPath = makeManifest("t");
+
+    await skillsCompile([
+      "--team", "t",
+      "--dry-run",
+      "--pack-dir", packDir,
+      "--mattstack-dir", mattstackDir,
+      "--manifest", manifestPath,
+      "--verb", "watch-ci",
+    ]);
+
+    const summary = logs.find((l) => /would write \d+ files/.test(l));
+    expect(summary).toBeDefined();
+    expect(summary).toContain("watch-ci");
+    expect(existsSync(join(packDir, "skills", "watch-ci"))).toBe(false);
+  });
+
+  test("real run emits SKILL.md + vendored files matching a golden compile, byte for byte", async () => {
+    const mattstackDir = makeMattstackDir();
+    const packDir = makePackDir();
+    const manifestPath = makeManifest("t");
+
+    await skillsCompile([
+      "--team", "t",
+      "--pack-dir", packDir,
+      "--mattstack-dir", mattstackDir,
+      "--manifest", manifestPath,
+      "--verb", "watch-ci",
+    ]);
+
+    expect(logs.some((l) => l.includes("compiled watch-ci") && l.includes("3 files"))).toBe(true);
+
+    const golden = computeGolden(mattstackDir);
+    const outDir = join(packDir, "skills", "watch-ci");
+
+    for (const file of golden.files) {
+      const dest = join(outDir, file.path);
+      expect(existsSync(dest)).toBe(true);
+      const expected = "content" in file ? file.content : readFileSync(file.copyFrom, "utf8");
+      expect(readFileSync(dest, "utf8")).toBe(expected);
+    }
+
+    const scriptPath = join(outDir, "scripts", "ci-watch.sh");
+    expect(statSync(scriptPath).mode & 0o111).not.toBe(0);
+  });
+
+  test("missing required binding: clean one-line error naming verb and slot, exit 1, no partial write", async () => {
+    const mattstackDir = makeMattstackDir();
+    const packDir = makePackDir();
+    const manifestPath = makeManifest("t", false);
+
+    const { exitCode, errors } = await runExpectingCleanExit(() =>
+      skillsCompile([
+        "--team", "t",
+        "--pack-dir", packDir,
+        "--mattstack-dir", mattstackDir,
+        "--manifest", manifestPath,
+        "--verb", "watch-ci",
+      ]),
+    );
+
+    expect(exitCode).toBe(1);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toStartWith("rt skills: ");
+    expect(errors[0]).not.toContain("\n    at "); // no stack trace
+    expect(errors[0]).toContain("watch-ci");
+    expect(errors[0]).toContain("forge");
+    expect(existsSync(join(packDir, "skills", "watch-ci"))).toBe(false);
+  });
+
+  test("unrecognized argument: clean one-line error, exit 1", async () => {
+    const { exitCode, errors } = await runExpectingCleanExit(() =>
+      skillsCompile(["--bogus-flag"]),
+    );
+
+    expect(exitCode).toBe(1);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toStartWith("rt skills: ");
+    expect(errors[0]).toContain("--bogus-flag");
+  });
+
+  test("unknown verb: clean one-line error, exit 1", async () => {
+    const mattstackDir = makeMattstackDir();
+    const packDir = makePackDir();
+    const manifestPath = makeManifest("t");
+
+    const { exitCode, errors } = await runExpectingCleanExit(() =>
+      skillsCompile([
+        "--team", "t",
+        "--pack-dir", packDir,
+        "--mattstack-dir", mattstackDir,
+        "--manifest", manifestPath,
+        "--verb", "no-such-verb",
+      ]),
+    );
+
+    expect(exitCode).toBe(1);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toStartWith("rt skills: ");
+    expect(errors[0]).toContain("no-such-verb");
+  });
+
+  test("absent manifest (no skills.jsonc names the team): clean one-line error, exit 1", async () => {
+    const mattstackDir = makeMattstackDir();
+    const packDir = makePackDir();
+
+    const { exitCode, errors } = await runExpectingCleanExit(() =>
+      skillsCompile([
+        "--team", "t",
+        "--pack-dir", packDir,
+        "--mattstack-dir", mattstackDir,
+        "--verb", "watch-ci",
+      ]),
+    );
+
+    expect(exitCode).toBe(1);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toStartWith("rt skills: ");
+    expect(errors[0]).toContain("skills.jsonc");
+  });
+
+  test("default pack dir formula (--team + --mattstack-dir, no --pack-dir)", async () => {
+    const mattstackDir = makeMattstackDir();
+    const manifestPath = makeManifest("t");
+    writeFile(join(mattstackDir, "teams", "t", "mattstack", "packs", "t", "pack", "stubs.jsonc"), STUBS_JSONC);
+
+    await skillsCompile([
+      "--team", "t",
+      "--dry-run",
+      "--mattstack-dir", mattstackDir,
+      "--manifest", manifestPath,
+    ]);
+
+    expect(logs.some((l) => /would write \d+ files/.test(l) && l.includes("watch-ci"))).toBe(true);
+  });
+
+  test("default manifest lookup (--mattstack-dir only, no --manifest)", async () => {
+    const mattstackDir = makeMattstackDir();
+    const packDir = makePackDir();
+    writeFile(join(mattstackDir, "repos", "some-repo", "skills.jsonc"), manifestJsonc("t", true));
+
+    await skillsCompile([
+      "--team", "t",
+      "--dry-run",
+      "--pack-dir", packDir,
+      "--mattstack-dir", mattstackDir,
+      "--verb", "watch-ci",
+    ]);
+
+    expect(logs.some((l) => /would write \d+ files/.test(l))).toBe(true);
+  });
+});
+
+describe("skillsCheck", () => {
+  test("reports current right after a compile", async () => {
+    const mattstackDir = makeMattstackDir();
+    const packDir = makePackDir();
+    const manifestPath = makeManifest("t");
+
+    await skillsCompile([
+      "--team", "t",
+      "--pack-dir", packDir,
+      "--mattstack-dir", mattstackDir,
+      "--manifest", manifestPath,
+      "--verb", "watch-ci",
+    ]);
+    logs = [];
+
+    await skillsCheck([
+      "--team", "t",
+      "--pack-dir", packDir,
+      "--mattstack-dir", mattstackDir,
+      "--manifest", manifestPath,
+      "--verb", "watch-ci",
+    ]);
+
+    expect(logs.some((l) => l.includes("watch-ci") && l.includes("current"))).toBe(true);
+    expect(logs.some((l) => l.includes("stale"))).toBe(false);
+    expect(process.exitCode).not.toBe(1);
+  });
+
+  test("hand-edited SKILL.md reports stale and exits 1", async () => {
+    const mattstackDir = makeMattstackDir();
+    const packDir = makePackDir();
+    const manifestPath = makeManifest("t");
+
+    await skillsCompile([
+      "--team", "t",
+      "--pack-dir", packDir,
+      "--mattstack-dir", mattstackDir,
+      "--manifest", manifestPath,
+      "--verb", "watch-ci",
+    ]);
+
+    const skillMdPath = join(packDir, "skills", "watch-ci", "SKILL.md");
+    writeFileSync(skillMdPath, readFileSync(skillMdPath, "utf8") + "\nhand-edited drift\n");
+    logs = [];
+
+    await skillsCheck([
+      "--team", "t",
+      "--pack-dir", packDir,
+      "--mattstack-dir", mattstackDir,
+      "--manifest", manifestPath,
+      "--verb", "watch-ci",
+    ]);
+
+    const staleLine = logs.find((l) => l.includes("stale"));
+    expect(staleLine).toBeDefined();
+    expect(staleLine).toContain("watch-ci");
+    expect(staleLine).toContain("SKILL.md");
+    expect(process.exitCode).toBe(1);
+  });
+
+  test("orphan file left over from a previous compile reports stale and exits 1", async () => {
+    const mattstackDir = makeMattstackDir();
+    const packDir = makePackDir();
+    const manifestPath = makeManifest("t");
+
+    await skillsCompile([
+      "--team", "t",
+      "--pack-dir", packDir,
+      "--mattstack-dir", mattstackDir,
+      "--manifest", manifestPath,
+      "--verb", "watch-ci",
+    ]);
+
+    writeFileSync(join(packDir, "skills", "watch-ci", "leftover.txt"), "stale content\n");
+    logs = [];
+
+    await skillsCheck([
+      "--team", "t",
+      "--pack-dir", packDir,
+      "--mattstack-dir", mattstackDir,
+      "--manifest", manifestPath,
+      "--verb", "watch-ci",
+    ]);
+
+    const staleLine = logs.find((l) => l.includes("stale"));
+    expect(staleLine).toBeDefined();
+    expect(staleLine).toContain("watch-ci");
+    expect(staleLine).toContain("leftover.txt");
+    expect(process.exitCode).toBe(1);
+  });
+
+  test("never-compiled public verb (missing outDir) reports stale and exits 1", async () => {
+    const mattstackDir = makeMattstackDir();
+    const packDir = makePackDir();
+    const manifestPath = makeManifest("t");
+
+    await skillsCheck([
+      "--team", "t",
+      "--pack-dir", packDir,
+      "--mattstack-dir", mattstackDir,
+      "--manifest", manifestPath,
+      "--verb", "watch-ci",
+    ]);
+
+    const staleLine = logs.find((l) => l.includes("stale"));
+    expect(staleLine).toBeDefined();
+    expect(staleLine).toContain("watch-ci");
+    expect(process.exitCode).toBe(1);
+  });
+});
diff --git a/commands/skills.ts b/commands/skills.ts
new file mode 100644
index 00000000..27dc95d8
--- /dev/null
+++ b/commands/skills.ts
@@ -0,0 +1,799 @@
+/**
+ * rt skills -- compile pack verbs from step sources + manifest bindings into
+ * committed SKILL.md files, and check compiled output against its sources.
+ *
+ *   rt skills compile [--team <name>] [--verb <name> ...] [--manifest <path>] [--dry-run]
+ *   rt skills check [--team <name>] [--verb <name> ...] [--manifest <path>]
+ *
+ * --pack-dir / --mattstack-dir are test-only escape hatches (hidden from the
+ * command tree): they let tests point the whole resolution chain at a
+ * mkdtemp fixture instead of the real ~/.mattstack, without a PATH-shimmed
+ * `claude` binary -- execSync inside this process ignores runtime PATH
+ * mutations (resolved at Bun's own startup), so a fake `claude` on PATH is
+ * not a reliable test seam. --mattstack-dir stands in for both the
+ * ~/.mattstack root (pack-dir and manifest defaults) and the Claude plugin
+ * cache (mirrored under <dir>/plugins/<name>/) that resolvePluginRoots()
+ * queries for real via `claude plugin list --json`.
+ */
+
+import { execFileSync, spawnSync } from "child_process";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "fs";
+import { createInterface } from "node:readline";
+import { dirname, join } from "path";
+import { resolveFzf } from "../lib/fzf.ts";
+import { mattstackHome } from "../lib/rt-paths.ts";
+import { compileSkill, HEADER_COMMENT } from "../lib/skills/compile.ts";
+import {
+  invocableRoster,
+  loadAttachment,
+  loadStepSource,
+  readManifestBindings,
+  readSurface,
+  readVerbRoster,
+  resolvePluginRoots,
+  stripFrontmatter,
+  type PluginRoots,
+  type SurfaceConfig,
+} from "../lib/skills/sources.ts";
+import type { AttachmentSource, CompileResult, VerbDef } from "../lib/skills/types.ts";
+
+/**
+ * Marks an error as an expected, user-facing condition (bad flags, absent
+ * binding, unknown verb) rather than a bug in this command -- withCleanErrors
+ * prints these as a one-line "rt skills: <message>" and exits 1 with no
+ * stack trace; anything else propagates to the top-level crash handler.
+ */
+class SkillsUsageError extends Error {}
+
+async function withCleanErrors(fn: () => Promise<void>): Promise<void> {
+  try {
+    await fn();
+  } catch (err) {
+    if (err instanceof SkillsUsageError) {
+      console.error(`rt skills: ${err.message}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+
+type Flags = {
+  team: string;
+  verbs: string[] | null;
+  manifest: string | null;
+  dryRun: boolean;
+  packDir: string | null;
+  mattstackDir: string | null;
+};
+
+function parseFlags(args: string[]): Flags {
+  const verbs: string[] = [];
+  let team = "claimview";
+  let manifest: string | null = null;
+  let dryRun = false;
+  let packDir: string | null = null;
+  let mattstackDir: string | null = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    switch (a) {
+      case "--team": team = args[++i] ?? team; break;
+      case "--verb": { const v = args[++i]; if (v) verbs.push(v); break; }
+      case "--manifest": manifest = args[++i] ?? null; break;
+      case "--dry-run": dryRun = true; break;
+      case "--pack-dir": packDir = args[++i] ?? null; break;
+      case "--mattstack-dir": mattstackDir = args[++i] ?? null; break;
+      default:
+        throw new SkillsUsageError(`unrecognized argument "${a}"`);
+    }
+  }
+
+  return { team, verbs: verbs.length ? verbs : null, manifest, dryRun, packDir, mattstackDir };
+}
+
+function packRootDir(mattstackRoot: string, team: string): string {
+  return join(mattstackRoot, "teams", team, "mattstack", "packs", team);
+}
+
+function leadingCommentBlock(raw: string): string {
+  const lines: string[] = [];
+  for (const line of raw.split("\n")) {
+    if (line.trim().startsWith("//")) {
+      lines.push(line);
+      continue;
+    }
+    break;
+  }
+  return lines.join("\n");
+}
+
+function listSubdirs(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function listFilesRecursive(dir: string, prefix = ""): string[] {
+  if (!existsSync(dir)) return [];
+  const files: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      files.push(...listFilesRecursive(join(dir, entry.name), relPath));
+    } else {
+      files.push(relPath);
+    }
+  }
+  return files;
+}
+
+function findDefaultManifest(mattstackRoot: string, team: string): string {
+  const reposRoot = join(mattstackRoot, "repos");
+  const candidates: { path: string; mtimeMs: number }[] = [];
+
+  for (const repoName of listSubdirs(reposRoot)) {
+    const manifestPath = join(reposRoot, repoName, "skills.jsonc");
+    if (!existsSync(manifestPath)) continue;
+    const header = leadingCommentBlock(readFileSync(manifestPath, "utf8"));
+    if (!header.includes(team)) continue;
+    candidates.push({ path: manifestPath, mtimeMs: statSync(manifestPath).mtimeMs });
+  }
+
+  if (candidates.length === 0) {
+    throw new SkillsUsageError(
+      `no skills.jsonc under ${reposRoot}/*/ names team "${team}" in its provenance header; pass --manifest explicitly`,
+    );
+  }
+
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  const newest = candidates[0]!;
+  const tied = candidates.filter((c) => c.mtimeMs === newest.mtimeMs);
+  if (tied.length > 1) {
+    throw new SkillsUsageError(
+      `ambiguous manifest for team "${team}" -- candidates tie for newest:\n${tied.map((c) => c.path).join("\n")}\npass --manifest explicitly`,
+    );
+  }
+
+  return newest.path;
+}
+
+/** Test-mode-only: scans <dir>/plugins/<name>/.claude-plugin/plugin.json, bypassing the real `claude plugin list --json`. */
+function resolvePluginRootsFromDir(dir: string): PluginRoots {
+  const pluginsDir = join(dir, "plugins");
+  const byName: PluginRoots["byName"] = {};
+
+  for (const name of listSubdirs(pluginsDir)) {
+    const pluginDir = join(pluginsDir, name);
+    let version = "unknown";
+    try {
+      const parsed = JSON.parse(readFileSync(join(pluginDir, ".claude-plugin", "plugin.json"), "utf8"));
+      if (typeof parsed.version === "string") version = parsed.version;
+    } catch {
+      // best-effort: a fixture plugin without a readable manifest still resolves a root
+    }
+    byName[name] = { dir: pluginDir, version };
+  }
+
+  return { byName };
+}
+
+function selectVerbs(roster: VerbDef[], names: string[] | null): VerbDef[] {
+  if (!names) return roster;
+  const byName = new Map(roster.map((v) => [v.name, v]));
+  return names.map((name) => {
+    const verb = byName.get(name);
+    if (!verb) throw new SkillsUsageError(`verb "${name}" not found in roster`);
+    return verb;
+  });
+}
+
+type Resolved = {
+  packDir: string;
+  roster: VerbDef[];
+  bindings: Record<string, Record<string, string>>;
+  pluginRoots: PluginRoots;
+  invocable: Set<string>;
+  surface: SurfaceConfig | null;
+  internalRoster: Set<string>;
+};
+
+/**
+ * Internal roster tokens mirror invocableRoster's "<team>:<name>" shape so
+ * they line up with body-prose tokens and fill bindings. A dir under
+ * <packDir>/skills/ not (yet) named in surface.jsonc's public list is
+ * internal by default -- this is what lets a fill inline through the
+ * transition window before it physically moves. Non-public stub verbs seed
+ * the roster too: a retired verb's dir is deleted, so the dir scan alone
+ * would let dangling references to it slip through. attachments/ dirs seed
+ * it as well: `surface apply` moves a skill there once it goes internal, so
+ * without this a name that migrated from skills/ to attachments/ falls out
+ * of the roster and a body token naming it downgrades from a compile error
+ * to a mere "not invocable" warning.
+ */
+function computeInternalRoster(
+  team: string,
+  packDir: string,
+  surface: SurfaceConfig | null,
+  fullRoster: VerbDef[],
+): Set<string> {
+  const internal = new Set<string>();
+  if (!surface) return internal;
+  const publicSet = new Set(surface.public);
+  for (const name of listSubdirs(join(packDir, "skills"))) {
+    if (!publicSet.has(name)) internal.add(`${team}:${name}`);
+  }
+  for (const name of listSubdirs(join(packDir, "attachments"))) {
+    if (!publicSet.has(name)) internal.add(`${team}:${name}`);
+  }
+  for (const verb of fullRoster) {
+    if (!publicSet.has(verb.name)) internal.add(`${team}:${verb.name}`);
+  }
+  return internal;
+}
+
+function resolve(flags: Flags): Resolved {
+  const mattstackRoot = flags.mattstackDir ?? mattstackHome();
+  const packDir = flags.packDir ?? packRootDir(mattstackRoot, flags.team);
+  const manifestPath = flags.manifest ?? findDefaultManifest(mattstackRoot, flags.team);
+
+  const fullRoster = readVerbRoster(packDir);
+  const roster = selectVerbs(fullRoster, flags.verbs);
+  const bindings = readManifestBindings(manifestPath);
+  const pluginRoots = flags.mattstackDir ? resolvePluginRootsFromDir(mattstackRoot) : resolvePluginRoots();
+  const invocable = invocableRoster(pluginRoots);
+  const surface = readSurface(packDir);
+  const internalRoster = computeInternalRoster(flags.team, packDir, surface, fullRoster);
+
+  return { packDir, roster, bindings, pluginRoots, invocable, surface, internalRoster };
+}
+
+function compileVerb(verb: VerbDef, resolved: Resolved): CompileResult {
+  let step;
+  try {
+    step = loadStepSource(verb.engine, resolved.pluginRoots);
+  } catch (err) {
+    throw new SkillsUsageError(`verb "${verb.name}": ${(err as Error).message}`);
+  }
+
+  const slotBindings = resolved.bindings[`${step.plugin}:${verb.engine}`] ?? {};
+  const fills: Record<string, AttachmentSource | null> = {};
+  for (const slotName of Object.keys(step.slots)) {
+    const bindingName = slotBindings[slotName];
+    if (!bindingName) {
+      fills[slotName] = null;
+      continue;
+    }
+    try {
+      fills[slotName] = loadAttachment(bindingName, slotName, resolved.pluginRoots);
+    } catch (err) {
+      throw new SkillsUsageError(`verb "${verb.name}": ${(err as Error).message}`);
+    }
+  }
+
+  try {
+    return compileSkill(verb, step, fills, resolved.invocable, { internalRoster: resolved.internalRoster });
+  } catch (err) {
+    // compileSkill's own message already names verb + slot -- pass it through unchanged.
+    throw new SkillsUsageError((err as Error).message);
+  }
+}
+
+function writeCompiledVerb(outDir: string, result: CompileResult): void {
+  rmSync(outDir, { recursive: true, force: true });
+  mkdirSync(outDir, { recursive: true });
+
+  for (const file of result.files) {
+    const dest = join(outDir, file.path);
+    mkdirSync(dirname(dest), { recursive: true });
+    if ("content" in file) {
+      writeFileSync(dest, file.content);
+    } else {
+      copyFileSync(file.copyFrom, dest);
+      chmodSync(dest, statSync(file.copyFrom).mode);
+    }
+  }
+}
+
+export async function skillsCompile(args: string[]): Promise<void> {
+  await withCleanErrors(async () => {
+    const flags = parseFlags(args);
+    const resolved = resolve(flags);
+    const publicSet = resolved.surface ? new Set(resolved.surface.public) : null;
+
+    for (const verb of resolved.roster) {
+      const outDir = join(resolved.packDir, "skills", verb.name);
+
+      if (publicSet && !publicSet.has(verb.name)) {
+        console.log(`internal: ${verb.name} (not compiled; roster entry retired)`);
+        if (!flags.dryRun && existsSync(outDir)) {
+          rmSync(outDir, { recursive: true, force: true });
+        }
+        continue;
+      }
+
+      const result = compileVerb(verb, resolved);
+      if (result.errors.length > 0) {
+        throw new SkillsUsageError(`verb "${verb.name}": ${result.errors.join("; ")}`);
+      }
+
+      if (flags.dryRun) {
+        console.log(`would write ${result.files.length} files for ${verb.name}`);
+        for (const warning of result.warnings) console.log(`  ${warning}`);
+        continue;
+      }
+
+      writeCompiledVerb(outDir, result);
+      console.log(`compiled ${verb.name} (${result.files.length} files, ${result.warnings.length} warnings)`);
+      for (const warning of result.warnings) console.log(`  ${warning}`);
+    }
+
+    if (publicSet) {
+      for (const name of listSubdirs(join(resolved.packDir, "skills"))) {
+        if (!publicSet.has(name)) {
+          console.log(`misplaced: ${name} (run rt skills surface apply, or move it)`);
+          process.exitCode = 1;
+        }
+      }
+    }
+  });
+}
+
+export async function skillsCheck(args: string[]): Promise<void> {
+  await withCleanErrors(async () => {
+    const flags = parseFlags(args);
+    const resolved = resolve(flags);
+    // No surface.jsonc means the pack has no public/internal split yet -- every roster verb is public.
+    const publicSet = resolved.surface ? new Set(resolved.surface.public) : null;
+
+    let anyStale = false;
+
+    for (const verb of resolved.roster) {
+      const outDir = join(resolved.packDir, "skills", verb.name);
+      const isPublic = !publicSet || publicSet.has(verb.name);
+
+      if (!existsSync(outDir)) {
+        if (isPublic) {
+          anyStale = true;
+          console.log(`${verb.name}: stale (never compiled -- outDir missing; run rt skills compile)`);
+        }
+        continue;
+      }
+
+      const result = compileVerb(verb, resolved);
+      const staleFiles: string[] = [];
+      const expectedPaths = new Set(result.files.map((f) => f.path));
+
+      for (const file of result.files) {
+        const dest = join(outDir, file.path);
+        const expected = "content" in file ? Buffer.from(file.content) : readFileSync(file.copyFrom);
+        if (!existsSync(dest) || !readFileSync(dest).equals(expected)) {
+          staleFiles.push(file.path);
+        }
+      }
+
+      // A file left behind by an earlier compile: writeCompiledVerb would delete it on
+      // the next real compile, so "current" here would be a false clean bill of health.
+      for (const onDisk of listFilesRecursive(outDir)) {
+        if (!expectedPaths.has(onDisk)) staleFiles.push(`${onDisk} (orphan)`);
+      }
+
+      if (staleFiles.length > 0) {
+        anyStale = true;
+        console.log(`${verb.name}: stale (recompile or investigate drift with git diff) -- ${staleFiles.join(", ")}`);
+      } else {
+        console.log(`${verb.name}: current`);
+      }
+    }
+
+    if (anyStale) process.exitCode = 1;
+  });
+}
+
+// ─── rt skills surface -- list / set / apply / fzf palette ────────────────
+
+type SurfaceFlags = {
+  team: string;
+  dryRun: boolean;
+  packDir: string | null;
+  mattstackDir: string | null;
+  manifest: string | null;
+};
+
+type SurfaceRow = { name: string; kind: "compiled" | "hand-authored" | "missing"; status: "public" | "internal" };
+
+function kindLabel(kind: SurfaceRow["kind"]): string {
+  return kind === "missing" ? "(no files on disk)" : kind;
+}
+
+function parseSurfaceFlags(args: string[]): { flags: SurfaceFlags; rest: string[] } {
+  let team = "claimview";
+  let dryRun = false;
+  let packDir: string | null = null;
+  let mattstackDir: string | null = null;
+  let manifest: string | null = null;
+  const rest: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    switch (a) {
+      case "--team": team = args[++i] ?? team; break;
+      case "--dry-run": dryRun = true; break;
+      case "--pack-dir": packDir = args[++i] ?? null; break;
+      case "--mattstack-dir": mattstackDir = args[++i] ?? null; break;
+      case "--manifest": manifest = args[++i] ?? null; break;
+      default: rest.push(a);
+    }
+  }
+
+  return { flags: { team, dryRun, packDir, mattstackDir, manifest }, rest };
+}
+
+function resolveSurfacePaths(flags: SurfaceFlags): { packDir: string } {
+  const mattstackRoot = flags.mattstackDir ?? mattstackHome();
+  const packDir = flags.packDir ?? packRootDir(mattstackRoot, flags.team);
+  return { packDir };
+}
+
+function isCompiledDir(dir: string): boolean {
+  const skillMdPath = join(dir, "SKILL.md");
+  if (!existsSync(skillMdPath)) return false;
+  const { body } = stripFrontmatter(readFileSync(skillMdPath, "utf8"));
+  return body.startsWith(HEADER_COMMENT);
+}
+
+/** Stub verb names are always compile targets; a materialized dir carrying the compiler header is one too, even if its verb was since retired from stubs.jsonc. */
+function classify(name: string, dir: string | null, verbNames: Set<string>): "compiled" | "hand-authored" {
+  if (verbNames.has(name)) return "compiled";
+  if (dir && isCompiledDir(dir)) return "compiled";
+  return "hand-authored";
+}
+
+function collectRegistry(packDir: string, verbNames: Set<string>) {
+  const skillsNames = new Set(listSubdirs(join(packDir, "skills")));
+  const attachmentNames = new Set(listSubdirs(join(packDir, "attachments")));
+  const allNames = new Set<string>([...skillsNames, ...attachmentNames, ...verbNames]);
+  return { skillsNames, attachmentNames, allNames };
+}
+
+/** The set `set`'s first use bootstraps surface.jsonc from -- so the first edit is a delta from reality, not a cliff. */
+function defaultPublicSet(skillsNames: Set<string>, verbNames: Set<string>): Set<string> {
+  return new Set<string>([...skillsNames, ...verbNames]);
+}
+
+export function computeRows(
+  packDir: string,
+  verbNames: Set<string>,
+  surface: SurfaceConfig | null,
+): { source: string; rows: SurfaceRow[] } {
+  const { skillsNames, attachmentNames, allNames } = collectRegistry(packDir, verbNames);
+  const publicSet = surface ? new Set(surface.public) : defaultPublicSet(skillsNames, verbNames);
+  const source = surface
+    ? "pack/surface.jsonc"
+    : "(no surface.jsonc yet -- inferred from current skills/ + stubs.jsonc placement)";
+
+  // A name in surface.jsonc's public list but absent from skills/, attachments/, and
+  // stubs.jsonc would otherwise never become a row -- the palette write derives the new
+  // public list from rows alone, so omitting it here means the write silently drops it.
+  const names = new Set<string>(allNames);
+  for (const name of publicSet) names.add(name);
+
+  const rows = [...names].sort().map((name) => {
+    const dir = skillsNames.has(name)
+      ? join(packDir, "skills", name)
+      : attachmentNames.has(name)
+        ? join(packDir, "attachments", name)
+        : null;
+    return {
+      name,
+      kind: allNames.has(name) ? classify(name, dir, verbNames) : ("missing" as const),
+      status: (publicSet.has(name) ? "public" : "internal") as "public" | "internal",
+    };
+  });
+
+  return { source, rows };
+}
+
+function writeSurfaceConfig(packDir: string, publicList: string[]): void {
+  const path = join(packDir, "pack", "surface.jsonc");
+  mkdirSync(dirname(path), { recursive: true });
+  const json = JSON.stringify({ public: publicList }, null, 2);
+  writeFileSync(path, `// surface.jsonc -- names this pack's public skills/ directories.\n${json}\n`);
+}
+
+function compileArgs(flags: SurfaceFlags, packDir: string): string[] {
+  const args = ["--team", flags.team, "--pack-dir", packDir];
+  if (flags.mattstackDir) args.push("--mattstack-dir", flags.mattstackDir);
+  if (flags.manifest) args.push("--manifest", flags.manifest);
+  if (flags.dryRun) args.push("--dry-run");
+  return args;
+}
+
+function isInsideGitWorkTree(dir: string): boolean {
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: dir, stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** git mv keeps rename history for the common case; fixtures (and any non-git pack dir) fall back to a plain rename. */
+function moveHandAuthoredDir(packDir: string, name: string, from: "skills" | "attachments", to: "skills" | "attachments"): string | null {
+  const fromRel = join(from, name);
+  const toRel = join(to, name);
+  mkdirSync(join(packDir, to), { recursive: true });
+
+  if (isInsideGitWorkTree(packDir)) {
+    execFileSync("git", ["mv", fromRel, toRel], { cwd: packDir, stdio: "pipe" });
+    return null;
+  }
+
+  renameSync(join(packDir, fromRel), join(packDir, toRel));
+  return "plain rename -- pack dir is not a git repo";
+}
+
+function printSurfaceRows(flags: SurfaceFlags, source: string, rows: SurfaceRow[]): void {
+  console.log(`rt skills surface -- team ${flags.team}`);
+  console.log(`source: ${source}`);
+  for (const row of rows) {
+    console.log(`  ${row.status.padEnd(9)}${kindLabel(row.kind).padEnd(15)}${row.name}`);
+  }
+}
+
+async function runList(flags: SurfaceFlags): Promise<void> {
+  const { packDir } = resolveSurfacePaths(flags);
+  const verbNames = new Set(readVerbRoster(packDir).map((v) => v.name));
+  const surface = readSurface(packDir);
+  const { source, rows } = computeRows(packDir, verbNames, surface);
+
+  printSurfaceRows(flags, source, rows);
+  if (rows.length === 0) console.log("(no skills registered in this pack)");
+}
+
+async function runApply(flags: SurfaceFlags): Promise<void> {
+  const { packDir } = resolveSurfacePaths(flags);
+  const verbNames = new Set(readVerbRoster(packDir).map((v) => v.name));
+  const surface = readSurface(packDir);
+  const { skillsNames, attachmentNames } = collectRegistry(packDir, verbNames);
+  const publicSet = surface ? new Set(surface.public) : defaultPublicSet(skillsNames, verbNames);
+
+  const candidates = [...new Set<string>([...skillsNames, ...attachmentNames])].sort();
+  let moved = 0;
+
+  for (const name of candidates) {
+    const currentlyUnderSkills = skillsNames.has(name);
+    const dir = join(packDir, currentlyUnderSkills ? "skills" : "attachments", name);
+    if (classify(name, dir, verbNames) === "compiled") continue; // regenerated/removed by the compile step below, never git-mv'd
+
+    const wantPublic = publicSet.has(name);
+    if (currentlyUnderSkills === wantPublic) continue;
+
+    const from = currentlyUnderSkills ? "skills" : "attachments";
+    const to = currentlyUnderSkills ? "attachments" : "skills";
+    moved++;
+
+    if (flags.dryRun) {
+      console.log(`would move ${name}: ${from}/ -> ${to}/`);
+      continue;
+    }
+
+    const note = moveHandAuthoredDir(packDir, name, from, to);
+    console.log(`moved ${name}: ${from}/ -> ${to}/${note ? ` (${note})` : ""}`);
+  }
+
+  if (moved === 0) console.log("no moves needed");
+
+  await skillsCompile(compileArgs(flags, packDir));
+}
+
+async function runSet(name: string, want: "public" | "internal", flags: SurfaceFlags): Promise<void> {
+  const { packDir } = resolveSurfacePaths(flags);
+  const verbNames = new Set(readVerbRoster(packDir).map((v) => v.name));
+  const { skillsNames, allNames } = collectRegistry(packDir, verbNames);
+
+  if (!allNames.has(name)) {
+    throw new SkillsUsageError(
+      `"${name}" is not a known skill or verb in this pack (checked skills/, attachments/, stubs.jsonc)`,
+    );
+  }
+
+  const surface = readSurface(packDir);
+  const publicSet = surface ? new Set(surface.public) : defaultPublicSet(skillsNames, verbNames);
+
+  if (want === "public") publicSet.add(name);
+  else publicSet.delete(name);
+
+  writeSurfaceConfig(packDir, [...publicSet].sort());
+  console.log(`${name}: ${want}`);
+
+  await runApply(flags);
+}
+
+export type SurfaceDelta = { toPublic: string[]; toInternal: string[] };
+
+export type PaletteAction =
+  | { kind: "no-changes" }
+  | { kind: "write"; delta: SurfaceDelta }
+  | { kind: "declined"; delta: SurfaceDelta };
+
+/**
+ * Pure decision seam for the palette's accept path -- fzf's default --multi
+ * semantics emit the cursor row on Enter even when nothing is marked, so a
+ * deliberate "uncheck everything" can silently reintroduce one row. Called
+ * once (confirmed=false) to compute the delta for the pre-write preview, and
+ * again with the real answer once the user has seen it.
+ */
+export function decidePaletteAction(
+  previousPublic: Set<string>,
+  resultRows: { name: string; status: "public" | "internal" }[],
+  confirmed: boolean,
+): PaletteAction {
+  const toPublic: string[] = [];
+  const toInternal: string[] = [];
+
+  for (const row of resultRows) {
+    const was = previousPublic.has(row.name);
+    const now = row.status === "public";
+    if (was === now) continue;
+    if (now) toPublic.push(row.name);
+    else toInternal.push(row.name);
+  }
+  toPublic.sort();
+  toInternal.sort();
+
+  if (toPublic.length === 0 && toInternal.length === 0) return { kind: "no-changes" };
+  const delta = { toPublic, toInternal };
+  return confirmed ? { kind: "write", delta } : { kind: "declined", delta };
+}
+
+function printDelta(delta: SurfaceDelta): void {
+  console.log("changes:");
+  for (const name of delta.toPublic) console.log(`  + public   ${name}`);
+  for (const name of delta.toInternal) console.log(`  - public   ${name}`);
+}
+
+function confirmYesNo(promptText: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(promptText, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes");
+    });
+  });
+}
+
+async function runPalette(flags: SurfaceFlags): Promise<void> {
+  const { packDir } = resolveSurfacePaths(flags);
+  const verbNames = new Set(readVerbRoster(packDir).map((v) => v.name));
+  const surface = readSurface(packDir);
+  const { skillsNames } = collectRegistry(packDir, verbNames);
+  const previousPublic = surface ? new Set(surface.public) : defaultPublicSet(skillsNames, verbNames);
+  const { source, rows } = computeRows(packDir, verbNames, surface);
+
+  if (rows.length === 0) {
+    console.log("(no skills registered in this pack)");
+    return;
+  }
+
+  const fzfPath = resolveFzf();
+  if (!fzfPath || !process.stdin.isTTY) {
+    printSurfaceRows(flags, source, rows);
+    console.log("");
+    console.log("no tty or fzf not found -- edit one at a time: rt skills surface set <name> --public|--internal");
+    return;
+  }
+
+  const preselected = rows
+    .map((row, i) => (row.status === "public" ? i + 1 : null))
+    .filter((i): i is number => i !== null);
+  const loadBind = preselected.length
+    ? `load:${preselected.map((pos) => `pos(${pos})+toggle`).join("+")}+pos(1)`
+    : "load:pos(1)";
+
+  const input = rows
+    .map((row) => `${row.name}\t${row.status.padEnd(9)}${kindLabel(row.kind).padEnd(15)}${row.name}`)
+    .join("\n");
+
+  const result = spawnSync(
+    "fzf",
+    [
+      "--multi",
+      "--with-nth=2..",
+      "--delimiter=\t",
+      "--layout=reverse",
+      "--border=rounded",
+      "--border-label= rt skills surface ",
+      "--prompt=  filter: ",
+      "--header=space: toggle public  tab: toggle+next  enter: review changes  esc: cancel",
+      "--no-mouse",
+      "--bind=space:toggle,tab:toggle+down",
+      `--bind=${loadBind}`,
+    ],
+    { input, stdio: ["pipe", "pipe", "inherit"], encoding: "utf8" },
+  );
+
+  if (result.status !== 0) {
+    console.log("cancelled -- no changes made");
+    return;
+  }
+
+  const selectedSet = new Set(
+    (result.stdout ?? "")
+      .replace(/\n$/, "")
+      .split("\n")
+      .map((line) => line.split("\t")[0]!)
+      .filter(Boolean),
+  );
+
+  const resultRows = rows.map((row) => ({
+    name: row.name,
+    status: (selectedSet.has(row.name) ? "public" : "internal") as "public" | "internal",
+  }));
+
+  const preview = decidePaletteAction(previousPublic, resultRows, false);
+  if (preview.kind === "no-changes") {
+    console.log("no changes -- surface.jsonc left as is");
+    return;
+  }
+
+  printDelta(preview.delta);
+  const confirmed = await confirmYesNo("  apply these changes? [y/N] ");
+  const decision = decidePaletteAction(previousPublic, resultRows, confirmed);
+
+  if (decision.kind !== "write") {
+    console.log("declined -- no changes made");
+    return;
+  }
+
+  writeSurfaceConfig(packDir, [...selectedSet].sort());
+  console.log(`surface.jsonc updated: ${selectedSet.size} public`);
+
+  await runApply(flags);
+}
+
+export async function skillsSurface(args: string[]): Promise<void> {
+  await withCleanErrors(async () => {
+    const mode = args[0];
+
+    if (mode === "list") {
+      const { flags, rest } = parseSurfaceFlags(args.slice(1));
+      if (rest.length) throw new SkillsUsageError(`unrecognized argument "${rest[0]}"`);
+      await runList(flags);
+      return;
+    }
+
+    if (mode === "apply") {
+      const { flags, rest } = parseSurfaceFlags(args.slice(1));
+      if (rest.length) throw new SkillsUsageError(`unrecognized argument "${rest[0]}"`);
+      await runApply(flags);
+      return;
+    }
+
+    if (mode === "set") {
+      const name = args[1];
+      if (!name || name.startsWith("--")) {
+        throw new SkillsUsageError("set requires a skill name: rt skills surface set <name> --public|--internal");
+      }
+      const { flags, rest } = parseSurfaceFlags(args.slice(2));
+      let want: "public" | "internal" | null = null;
+      for (const a of rest) {
+        if (a === "--public") want = "public";
+        else if (a === "--internal") want = "internal";
+        else throw new SkillsUsageError(`unrecognized argument "${a}"`);
+      }
+      if (!want) throw new SkillsUsageError("set requires --public or --internal");
+      await runSet(name, want, flags);
+      return;
+    }
+
+    if (mode !== undefined && !mode.startsWith("--")) {
+      throw new SkillsUsageError(`unrecognized subcommand "${mode}" (expected list, set, or apply)`);
+    }
+
+    const { flags, rest } = parseSurfaceFlags(args);
+    if (rest.length) throw new SkillsUsageError(`unrecognized argument "${rest[0]}"`);
+    await runPalette(flags);
+  });
+}
diff --git a/lib/command-tree-def.ts b/lib/command-tree-def.ts
index cdc380fc..a2127bfc 100644
--- a/lib/command-tree-def.ts
+++ b/lib/command-tree-def.ts
@@ -750,6 +750,43 @@ export const TREE: Record<string, CommandNode> = {
     },
   },
 
+  skills: {
+    description: "Compile, check, and manage the surface of the pack's committed skills",
+    subcommands: {
+      compile: {
+        description: "Compile pack verbs from step sources + manifest bindings into committed SKILL.md files",
+        module: "./commands/skills.ts",
+        fn: "skillsCompile",
+        args: [
+          { name: "Team", flag: "--team", type: "text", placeholder: "claimview", hint: "Pack team; default claimview" },
+          { name: "Verb", flag: "--verb", type: "text", placeholder: "watch-ci", hint: "Compile only this verb (repeatable); omit for every verb in the roster" },
+          { name: "Manifest", flag: "--manifest", type: "text", placeholder: "/path/to/skills.jsonc", hint: "Manifest path; omit to auto-find the newest ~/.mattstack/repos/*/skills.jsonc naming this team" },
+          { name: "Dry run", flag: "--dry-run", type: "boolean", default: false, hint: "Print what would be written without touching disk" },
+        ],
+      },
+      check: {
+        description: "Report compiled skills that no longer match their sources",
+        module: "./commands/skills.ts",
+        fn: "skillsCheck",
+        args: [
+          { name: "Team", flag: "--team", type: "text", placeholder: "claimview", hint: "Pack team; default claimview" },
+          { name: "Verb", flag: "--verb", type: "text", placeholder: "watch-ci", hint: "Check only this verb (repeatable); omit for every compiled verb" },
+          { name: "Manifest", flag: "--manifest", type: "text", placeholder: "/path/to/skills.jsonc", hint: "Manifest path; omit to auto-find the newest ~/.mattstack/repos/*/skills.jsonc naming this team" },
+        ],
+      },
+      surface: {
+        description: "List, set, or apply the pack's public/internal skill surface (bare invocation opens an fzf multi-toggle palette)",
+        module: "./commands/skills.ts",
+        fn: "skillsSurface",
+        args: [
+          { name: "Mode", type: "text", placeholder: "list", hint: "list | set <name> --public|--internal | apply; omit for the fzf palette" },
+          { name: "Team", flag: "--team", type: "text", placeholder: "claimview", hint: "Pack team; default claimview" },
+          { name: "Dry run", flag: "--dry-run", type: "boolean", default: false, hint: "apply only: print planned moves without touching disk" },
+        ],
+      },
+    },
+  },
+
   plugin: {
     description: "Manage user plugins",
     subcommands: {
diff --git a/lib/fzf.ts b/lib/fzf.ts
index 7b23ef38..70dbbecb 100644
--- a/lib/fzf.ts
+++ b/lib/fzf.ts
@@ -4,7 +4,10 @@
  * — never installed, or reaped by `brew autoremove`/`brew cleanup` — we want a
  * single, actionable error rather than silently degrading to a non-fuzzy
  * picker or crashing with an opaque spawn ENOENT. Every fzf spawn site calls
- * ensureFzf() before spawning.
+ * ensureFzf() before spawning, except `rt skills surface`'s bare palette:
+ * that one deliberately soft-falls-back to printing the static list instead
+ * of erroring, since the same config-write path is also reachable via
+ * `rt skills surface set`.
  */
 import { bold, dim, yellow, reset } from "./tui.ts";
 
diff --git a/lib/module-registry.ts b/lib/module-registry.ts
index f862c755..ba9cf06a 100644
--- a/lib/module-registry.ts
+++ b/lib/module-registry.ts
@@ -17,6 +17,7 @@ import * as run from "../commands/run.ts";
 import * as secrets from "../commands/secrets.ts";
 import * as settings from "../commands/settings.ts";
 import * as settingsKeys from "../commands/settings-keys.ts";
+import * as skills from "../commands/skills.ts";
 import * as sync from "../commands/sync.ts";
 import * as rebase from "../commands/git/rebase.ts";
 import * as reset from "../commands/git/reset.ts";
@@ -47,6 +48,7 @@ export const MODULE_REGISTRY: Record<string, any> = {
   "./commands/secrets.ts": secrets,
   "./commands/settings.ts": settings,
   "./commands/settings-keys.ts": settingsKeys,
+  "./commands/skills.ts": skills,
   "./commands/sync.ts": sync,
   "./commands/git/rebase.ts": rebase,
   "./commands/git/reset.ts": reset,
diff --git a/lib/skills/__tests__/compile.test.ts b/lib/skills/__tests__/compile.test.ts
new file mode 100644
index 00000000..3142eb91
--- /dev/null
+++ b/lib/skills/__tests__/compile.test.ts
@@ -0,0 +1,336 @@
+import { describe, expect, test } from "bun:test";
+import { compileSkill } from "../compile.ts";
+import type { AttachmentSource, CompiledFile, StepSource, VerbDef } from "../types.ts";
+
+const verb: VerbDef = {
+  name: "watch-ci",
+  engine: "watch-ci-engine",
+  description: "Watch CI until it goes green",
+};
+
+const step: StepSource = {
+  name: "watch-ci",
+  plugin: "mattstack",
+  version: "1.2.0",
+  dir: "/plugins/mattstack/skills/pipeline/watch-ci",
+  body: "Poll the pipeline every 30s and report status. See ${CLAUDE_SKILL_DIR}/scripts/ci-watch.sh for the poller.",
+  slots: {
+    domain: { contract: "watch-ci-domain@1", required: true },
+    forge: { contract: "ci-forge@1", required: true },
+  },
+  allowedTools: ["Bash(gh:*)", "Read"],
+  stepFiles: ["references/polling-notes.md", "scripts/ci-watch.sh"],
+};
+
+const domainFill: AttachmentSource = {
+  binding: "claimview:watch-ci-domain",
+  plugin: "claimview",
+  version: "0.3.0",
+  dir: "/plugins/claimview/attachments/watch-ci-domain",
+  body: "Domain rules live at ${CLAUDE_SKILL_DIR}/ci-config.json for details.",
+  provides: "watch-ci-domain@1",
+  allowedTools: ["Read(${CLAUDE_SKILL_DIR}/ci-config.json)"],
+  extraFiles: ["ci-config.json"],
+  registered: false,
+};
+
+const forgeFill: AttachmentSource = {
+  binding: "mattstack:gitlab-forge",
+  plugin: "mattstack",
+  version: "1.2.0",
+  dir: "/plugins/mattstack/skills/gitlab-forge",
+  body: "Talk to GitLab via glab.",
+  provides: "ci-forge@1",
+  allowedTools: ["Bash(glab:*)", "Read"],
+  extraFiles: [],
+  registered: false,
+};
+
+const registeredForgeFill: AttachmentSource = {
+  binding: "mattstack:gitlab-forge",
+  plugin: "mattstack",
+  version: "1.2.0",
+  dir: "/plugins/mattstack/skills/gitlab-forge",
+  body: "Talk to GitLab via glab.",
+  provides: "ci-forge@1",
+  allowedTools: ["Bash(glab:*)", "Read(${CLAUDE_SKILL_DIR}/token.txt)"],
+  extraFiles: ["token.txt"],
+  registered: true,
+};
+
+const roster = new Set(["mattstack:watch-ci", "claimview:watch-ci-domain", "mattstack:gitlab-forge"]);
+
+function skillFileContent(files: CompiledFile[]): string {
+  const skillFile = files[0];
+  if (!skillFile || !("content" in skillFile)) {
+    throw new Error("expected files[0] to be a content file");
+  }
+  return skillFile.content;
+}
+
+function toolLinesBetween(content: string): string[] {
+  const match = content.match(/allowed-tools:\n([\s\S]*?)\nmetadata:/);
+  if (!match) {
+    throw new Error("allowed-tools block not found");
+  }
+  return (match[1] as string).split("\n").map((line) => line.trim());
+}
+
+describe("compileSkill", () => {
+  test("both slots bound: frontmatter, allowed-tools union, seams, body rewrite", () => {
+    const result = compileSkill(verb, step, { domain: domainFill, forge: forgeFill }, roster);
+
+    expect(result.warnings).toEqual([]);
+
+    const skillFile = result.files[0];
+    expect(skillFile?.path).toBe("SKILL.md");
+    const content = skillFileContent(result.files);
+
+    expect(content).toContain('name: "watch-ci"');
+    expect(content).toContain('description: "Watch CI until it goes green"');
+    expect(content).toContain(
+      'metadata:\n  compiled: "mattstack@1.2.0 + claimview:watch-ci-domain@0.3.0 + mattstack:gitlab-forge@1.2.0"',
+    );
+
+    expect(toolLinesBetween(content)).toEqual([
+      '- "Bash(gh:*)"',
+      '- "Read"',
+      '- "Read(${CLAUDE_SKILL_DIR}/parts/domain/ci-config.json)"',
+      '- "Bash(glab:*)"',
+    ]);
+
+    expect(content).toContain(
+      "<!-- compiled by rt skills compile from the sources below; slots pre-resolved; edits here are working-tree drift (rt skills promote) -->",
+    );
+    expect(content).toContain("<!-- part: step source=mattstack:watch-ci version=1.2.0 -->");
+    expect(content).toContain(
+      "<!-- part: slot:domain binding=claimview:watch-ci-domain version=0.3.0 -->",
+    );
+    expect(content).toContain(
+      "<!-- part: slot:forge binding=mattstack:gitlab-forge version=1.2.0 -->",
+    );
+
+    expect(content).toContain(
+      "Domain rules live at ${CLAUDE_SKILL_DIR}/parts/domain/ci-config.json for details.",
+    );
+    expect(content).toContain(
+      "Poll the pipeline every 30s and report status. See ${CLAUDE_SKILL_DIR}/scripts/ci-watch.sh for the poller.",
+    );
+  });
+
+  test("optional slot unbound: no seam, no part, no warning", () => {
+    const stepWithOptional: StepSource = {
+      ...step,
+      slots: {
+        ...step.slots,
+        notify: { contract: "notify@1", required: false },
+      },
+    };
+
+    const result = compileSkill(
+      verb,
+      stepWithOptional,
+      { domain: domainFill, forge: forgeFill, notify: null },
+      roster,
+    );
+
+    expect(result.warnings).toEqual([]);
+    const content = skillFileContent(result.files);
+    expect(content).not.toContain("slot:notify");
+    expect(result.files.some((f) => f.path.startsWith("parts/notify/"))).toBe(false);
+  });
+
+  test("required slot unbound throws naming verb, slot, contract", () => {
+    let error: Error | undefined;
+    try {
+      compileSkill(verb, step, { domain: null, forge: forgeFill }, roster);
+    } catch (e) {
+      error = e as Error;
+    }
+    expect(error).toBeInstanceOf(Error);
+    expect(error?.message).toContain("watch-ci");
+    expect(error?.message).toContain("domain");
+    expect(error?.message).toContain("watch-ci-domain@1");
+  });
+
+  test("provides mismatch throws naming expected vs actual", () => {
+    const badDomainFill: AttachmentSource = { ...domainFill, provides: "watch-ci-domain@2" };
+
+    let error: Error | undefined;
+    try {
+      compileSkill(verb, step, { domain: badDomainFill, forge: forgeFill }, roster);
+    } catch (e) {
+      error = e as Error;
+    }
+    expect(error).toBeInstanceOf(Error);
+    expect(error?.message).toContain("watch-ci");
+    expect(error?.message).toContain("domain");
+    expect(error?.message).toContain("watch-ci-domain@1");
+    expect(error?.message).toContain("watch-ci-domain@2");
+    expect(error?.message).toContain("claimview:watch-ci-domain");
+  });
+
+  test("vendoring: stepFiles and extraFiles map to exact copyFrom paths", () => {
+    const result = compileSkill(verb, step, { domain: domainFill, forge: forgeFill }, roster);
+
+    expect(result.files).toContainEqual({
+      path: "scripts/ci-watch.sh",
+      copyFrom: "/plugins/mattstack/skills/pipeline/watch-ci/scripts/ci-watch.sh",
+    });
+    expect(result.files).toContainEqual({
+      path: "references/polling-notes.md",
+      copyFrom: "/plugins/mattstack/skills/pipeline/watch-ci/references/polling-notes.md",
+    });
+    expect(result.files).toContainEqual({
+      path: "parts/domain/ci-config.json",
+      copyFrom: "/plugins/claimview/attachments/watch-ci-domain/ci-config.json",
+    });
+    expect(result.files.some((f) => f.path.startsWith("parts/forge/"))).toBe(false);
+  });
+
+  test("registered fill: reference line only, no seam/body, but still vendors extraFiles and joins allowed-tools", () => {
+    const result = compileSkill(
+      verb,
+      step,
+      { domain: domainFill, forge: registeredForgeFill },
+      roster,
+    );
+
+    expect(result.warnings).toEqual([]);
+
+    const content = skillFileContent(result.files);
+
+    expect(content).toContain(
+      "Slot forge is bound to `mattstack:gitlab-forge` (mattstack:gitlab-forge@1.2.0) -- invoke that skill when this flow needs it.",
+    );
+    expect(content).not.toContain("<!-- part: slot:forge");
+    expect(content).not.toContain("Talk to GitLab via glab.");
+
+    expect(result.files).toContainEqual({
+      path: "parts/forge/token.txt",
+      copyFrom: "/plugins/mattstack/skills/gitlab-forge/token.txt",
+    });
+
+    expect(toolLinesBetween(content)).toEqual([
+      '- "Bash(gh:*)"',
+      '- "Read"',
+      '- "Read(${CLAUDE_SKILL_DIR}/parts/domain/ci-config.json)"',
+      '- "Bash(glab:*)"',
+      '- "Read(${CLAUDE_SKILL_DIR}/parts/forge/token.txt)"',
+    ]);
+
+    expect(content).toContain(
+      'metadata:\n  compiled: "mattstack@1.2.0 + claimview:watch-ci-domain@0.3.0 + mattstack:gitlab-forge@1.2.0"',
+    );
+  });
+
+  test("name lint: unregistered token warns, roster member does not", () => {
+    const lintStep: StepSource = {
+      name: "watch-ci",
+      plugin: "mattstack",
+      version: "1.0.0",
+      dir: "/plugins/mattstack/skills/pipeline/watch-ci",
+      body: "This step defers domain judgment to claimview:watch-ci-domain and never invokes claimview:nonexistent.",
+      slots: {},
+      allowedTools: [],
+      stepFiles: [],
+    };
+    const lintRoster = new Set(["mattstack:watch-ci", "claimview:watch-ci-domain"]);
+
+    const result = compileSkill(verb, lintStep, {}, lintRoster);
+
+    expect(result.warnings).toEqual([
+      "body references claimview:nonexistent which is not invocable",
+    ]);
+  });
+
+  test("name lint: a bound fill's own seam comment does not warn even when its binding is unregistered", () => {
+    const rosterWithoutDomain = new Set(["mattstack:watch-ci", "mattstack:gitlab-forge"]);
+
+    const result = compileSkill(verb, step, { domain: domainFill, forge: forgeFill }, rosterWithoutDomain);
+
+    expect(result.warnings).toEqual([]);
+  });
+
+  test("name lint: the same binding name in author body prose still warns", () => {
+    const rosterWithoutDomain = new Set(["mattstack:watch-ci", "mattstack:gitlab-forge"]);
+    const stepMentioningBinding: StepSource = {
+      ...step,
+      body: `${step.body} This step composes with claimview:watch-ci-domain for domain rules.`,
+    };
+
+    const result = compileSkill(
+      verb,
+      stepMentioningBinding,
+      { domain: domainFill, forge: forgeFill },
+      rosterWithoutDomain,
+    );
+
+    expect(result.warnings).toEqual([
+      "body references claimview:watch-ci-domain which is not invocable",
+    ]);
+  });
+
+  test("path lint: vendored file reference is clean, missing file reference warns", () => {
+    const stepWithMissingRef: StepSource = {
+      ...step,
+      body: `${step.body} Also see \${CLAUDE_SKILL_DIR}/parts/domain/missing.json for details.`,
+    };
+
+    const result = compileSkill(
+      verb,
+      stepWithMissingRef,
+      { domain: domainFill, forge: forgeFill },
+      roster,
+    );
+
+    expect(result.warnings).toEqual([
+      "body references ${CLAUDE_SKILL_DIR}/parts/domain/missing.json which is not an emitted file",
+    ]);
+  });
+
+  test("empty allowed-tools union omits the key entirely", () => {
+    const bareStep: StepSource = {
+      name: "self-review",
+      plugin: "mattstack",
+      version: "1.2.0",
+      dir: "/plugins/mattstack/skills/review/self-review",
+      body: "Review your own diff before shipping.",
+      slots: {},
+      allowedTools: [],
+      stepFiles: [],
+    };
+    const bareVerb: VerbDef = {
+      name: "self-review",
+      engine: "self-review",
+      description: "Review your own change",
+    };
+
+    const result = compileSkill(bareVerb, bareStep, {}, roster);
+
+    expect(result.warnings).toEqual([]);
+    const content = skillFileContent(result.files);
+    expect(content).not.toContain("allowed-tools");
+    expect(content).toContain('description: "Review your own change"\nmetadata:');
+  });
+
+  test("determinism: structurally equal inputs produce identical content", () => {
+    const verbCopy: VerbDef = JSON.parse(JSON.stringify(verb));
+    const stepCopy: StepSource = JSON.parse(JSON.stringify(step));
+    const domainFillCopy: AttachmentSource = JSON.parse(JSON.stringify(domainFill));
+    const forgeFillCopy: AttachmentSource = JSON.parse(JSON.stringify(forgeFill));
+    const rosterCopy = new Set(roster);
+
+    const resultA = compileSkill(verb, step, { domain: domainFill, forge: forgeFill }, roster);
+    const resultB = compileSkill(
+      verbCopy,
+      stepCopy,
+      { domain: domainFillCopy, forge: forgeFillCopy },
+      rosterCopy,
+    );
+
+    expect(skillFileContent(resultB.files)).toBe(skillFileContent(resultA.files));
+    expect(resultB.files).toEqual(resultA.files);
+    expect(resultB.warnings).toEqual(resultA.warnings);
+  });
+});
diff --git a/lib/skills/__tests__/sources.test.ts b/lib/skills/__tests__/sources.test.ts
new file mode 100644
index 00000000..89119fee
--- /dev/null
+++ b/lib/skills/__tests__/sources.test.ts
@@ -0,0 +1,432 @@
+import { describe, test, expect, beforeEach, spyOn } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import {
+  buildPluginRoots,
+  invocableRoster,
+  loadAttachment,
+  loadStepSource,
+  readManifestBindings,
+  readVerbRoster,
+  stripFrontmatter,
+  stripJsonc,
+  type PluginRoots,
+} from "../sources.ts";
+
+function writeFile(path: string, content: string): void {
+  mkdirSync(join(path, ".."), { recursive: true });
+  writeFileSync(path, content);
+}
+
+const WATCH_CI_SKILL_MD = `---
+name: watch-ci
+description: "Watch CI until it goes green"
+type: pipeline-step
+allowed-tools:
+  - "Bash(gh:*)"
+  - "Read"
+slots:
+  domain: { contract: "watch-ci-domain@1" }
+  forge: { contract: "ci-forge@1", required: true }
+---
+
+Poll the pipeline every 30s and report status.
+`;
+
+const WATCH_CI_SCRIPT = "#!/bin/sh\necho polling\n";
+
+const WATCH_CI_DOMAIN_SKILL_MD = `---
+name: watch-ci-domain
+description: "Domain rules for watch-ci"
+metadata:
+  provides: "watch-ci-domain@1"
+allowed-tools:
+  - "Read(\${CLAUDE_SKILL_DIR}/ci-config.json)"
+---
+
+Domain rules live at \${CLAUDE_SKILL_DIR}/ci-config.json for details.
+`;
+
+const CI_CONFIG_JSON = `{ "noisy": ["flaky-job"] }\n`;
+
+/**
+ * mattstack root: skills/pipeline/watch-ci/SKILL.md (+ scripts/ci-watch.sh),
+ * matching the real plugin's group/engine nesting, plus
+ * attachments/pipeline/ship/SKILL.md -- an engine already moved out of
+ * skills/ (unregistered) that loadStepSource must still resolve.
+ * claimview root: attachments/watch-ci-domain/SKILL.md (+ ci-config.json), the
+ * unregistered fill; a registered copy also lives under skills/watch-ci-domain
+ * so loadAttachment can be exercised against both search roots.
+ */
+function makeFixtureRoots(): { rootDir: string; roots: PluginRoots } {
+  const rootDir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-src-")));
+
+  const mattstackDir = join(rootDir, "mattstack");
+  writeFile(join(mattstackDir, "skills", "pipeline", "watch-ci", "SKILL.md"), WATCH_CI_SKILL_MD);
+  writeFile(join(mattstackDir, "skills", "pipeline", "watch-ci", "scripts", "ci-watch.sh"), WATCH_CI_SCRIPT);
+  writeFile(join(mattstackDir, "skills", "pipeline", "watch-ci", "references", "polling-notes.md"), "Polling notes.\n");
+  writeFile(join(mattstackDir, "skills", "pipeline", "watch-ci", ".DS_Store"), "junk");
+  writeFile(join(mattstackDir, "skills", "pipeline", "watch-ci", "README.md"), "readme");
+  writeFile(join(mattstackDir, "skills", "pipeline", "watch-ci", "scripts", ".gitignore"), "*.pyc");
+  writeFile(join(mattstackDir, "skills", "pipeline", "watch-ci", "scripts", "__pycache__", "x.pyc"), "pyc");
+  writeFile(join(mattstackDir, "skills", "pipeline", "watch-ci", "scripts", "helper.pyc"), "pyc");
+  writeFile(join(mattstackDir, "skills", "pipeline", "watch-ci", "scripts", "poll.test.sh"), "test");
+  writeFile(join(mattstackDir, "skills", "pipeline", "watch-ci", "tests", "harness.sh"), "test");
+  writeFile(join(mattstackDir, ".claude-plugin", "plugin.json"), JSON.stringify({ version: "1.2.0" }));
+
+  const untypedSkillMd = WATCH_CI_SKILL_MD.replace("type: pipeline-step\n", "");
+  writeFile(join(mattstackDir, "skills", "pipeline", "untyped-step", "SKILL.md"), untypedSkillMd);
+
+  const shipSkillMd = WATCH_CI_SKILL_MD.replace(/name: watch-ci/, "name: ship").replace(
+    "Poll the pipeline every 30s and report status.",
+    "Ship it.",
+  );
+  writeFile(join(mattstackDir, "attachments", "pipeline", "ship", "SKILL.md"), shipSkillMd);
+
+  const claimviewDir = join(rootDir, "claimview");
+  writeFile(join(claimviewDir, "attachments", "watch-ci-domain", "SKILL.md"), WATCH_CI_DOMAIN_SKILL_MD);
+  writeFile(join(claimviewDir, "attachments", "watch-ci-domain", "ci-config.json"), CI_CONFIG_JSON);
+  writeFile(join(claimviewDir, "skills", "cvi-gates", "SKILL.md"), WATCH_CI_DOMAIN_SKILL_MD.replace("watch-ci-domain", "cvi-gates"));
+  writeFile(join(claimviewDir, ".claude-plugin", "plugin.json"), JSON.stringify({ version: "0.3.0" }));
+
+  const roots: PluginRoots = {
+    byName: {
+      mattstack: { dir: mattstackDir, version: "1.2.0" },
+      claimview: { dir: claimviewDir, version: "0.3.0" },
+    },
+  };
+
+  return { rootDir, roots };
+}
+
+describe("stripJsonc", () => {
+  test("removes full-line // comments but leaves inline content alone", () => {
+    const raw = [
+      "// header comment",
+      "{",
+      '  "url": "http://example.com",',
+      "  // trailing comment",
+      '  "n": 1',
+      "}",
+    ].join("\n");
+
+    const stripped = stripJsonc(raw);
+
+    expect(stripped).toBe(["{", '  "url": "http://example.com",', '  "n": 1', "}"].join("\n"));
+    expect(JSON.parse(stripped)).toEqual({ url: "http://example.com", n: 1 });
+  });
+
+  test("tolerates indented // comment lines", () => {
+    const raw = ['{', '  "a": 1,', '    // indented comment', '  "b": 2', "}"].join("\n");
+    const stripped = stripJsonc(raw);
+    expect(stripped).toBe(['{', '  "a": 1,', '  "b": 2', "}"].join("\n"));
+  });
+});
+
+describe("stripFrontmatter", () => {
+  test("round-trips body exactly and parses frontmatter", () => {
+    const body = "Line one.\nLine two.\n\nLine four after a blank.";
+    const md = `---\nname: foo\nnested:\n  x: 1\n---\n\n${body}\n`;
+
+    const result = stripFrontmatter(md);
+
+    expect(result.body).toBe(body);
+    expect(result.frontmatter).toEqual({ name: "foo", nested: { x: 1 } });
+  });
+
+  test("no frontmatter block returns the trimmed body and empty frontmatter", () => {
+    const result = stripFrontmatter("Just prose, no frontmatter.\n");
+    expect(result.body).toBe("Just prose, no frontmatter.");
+    expect(result.frontmatter).toEqual({});
+  });
+});
+
+describe("loadStepSource", () => {
+  test("finds the engine under skills/pipeline/, parses slots, lists stepFiles", () => {
+    const { roots } = makeFixtureRoots();
+
+    const step = loadStepSource("watch-ci", roots);
+
+    expect(step.name).toBe("watch-ci");
+    expect(step.plugin).toBe("mattstack");
+    expect(step.version).toBe("1.2.0");
+    expect(step.dir.endsWith(join("skills", "pipeline", "watch-ci"))).toBe(true);
+    expect(step.body).toBe("Poll the pipeline every 30s and report status.");
+    expect(step.slots).toEqual({
+      domain: { contract: "watch-ci-domain@1" },
+      forge: { contract: "ci-forge@1", required: true },
+    });
+    expect(step.allowedTools).toEqual(["Bash(gh:*)", "Read"]);
+    expect(step.stepFiles).toEqual(["references/polling-notes.md", "scripts/ci-watch.sh"]);
+  });
+
+  test("throws naming the file when the engine has no type: pipeline-step", () => {
+    const { roots } = makeFixtureRoots();
+
+    expect(() => loadStepSource("untyped-step", roots)).toThrow(/untyped-step.*SKILL\.md/s);
+  });
+
+  test("throws listing searched paths when the engine is absent entirely", () => {
+    const { roots } = makeFixtureRoots();
+    const expectedSkillsPath = join(
+      roots.byName.mattstack!.dir,
+      "skills",
+      "pipeline",
+      "no-such-engine",
+      "SKILL.md",
+    );
+    const expectedAttachmentsFlatPath = join(
+      roots.byName.mattstack!.dir,
+      "attachments",
+      "no-such-engine",
+      "SKILL.md",
+    );
+    const expectedAttachmentsGroupPath = join(
+      roots.byName.mattstack!.dir,
+      "attachments",
+      "pipeline",
+      "no-such-engine",
+      "SKILL.md",
+    );
+
+    let thrown: unknown;
+    try {
+      loadStepSource("no-such-engine", roots);
+    } catch (err) {
+      thrown = err;
+    }
+
+    expect(thrown).toBeInstanceOf(Error);
+    expect((thrown as Error).message).toContain(expectedSkillsPath);
+    expect((thrown as Error).message).toContain(expectedAttachmentsFlatPath);
+    expect((thrown as Error).message).toContain(expectedAttachmentsGroupPath);
+  });
+
+  test("falls back to attachments/<group>/<engine>/SKILL.md for an engine moved out of skills/", () => {
+    const { roots } = makeFixtureRoots();
+
+    const step = loadStepSource("ship", roots);
+
+    expect(step.name).toBe("ship");
+    expect(step.dir.endsWith(join("attachments", "pipeline", "ship"))).toBe(true);
+    expect(step.body).toBe("Ship it.");
+  });
+});
+
+describe("loadAttachment", () => {
+  test("finds a registered skill under skills/", () => {
+    const { roots } = makeFixtureRoots();
+
+    const fill = loadAttachment("claimview:cvi-gates", "domain", roots);
+
+    expect(fill.registered).toBe(true);
+    expect(fill.binding).toBe("claimview:cvi-gates");
+    expect(fill.plugin).toBe("claimview");
+    expect(fill.version).toBe("0.3.0");
+    expect(fill.provides).toBe("watch-ci-domain@1");
+    expect(fill.dir.endsWith(join("skills", "cvi-gates"))).toBe(true);
+  });
+
+  test("finds an unregistered skill under attachments/", () => {
+    const { roots } = makeFixtureRoots();
+
+    const fill = loadAttachment("claimview:watch-ci-domain", "domain", roots);
+
+    expect(fill.registered).toBe(false);
+    expect(fill.binding).toBe("claimview:watch-ci-domain");
+    expect(fill.provides).toBe("watch-ci-domain@1");
+    expect(fill.body).toBe("Domain rules live at ${CLAUDE_SKILL_DIR}/ci-config.json for details.");
+    expect(fill.allowedTools).toEqual(["Read(${CLAUDE_SKILL_DIR}/ci-config.json)"]);
+    expect(fill.dir.endsWith(join("attachments", "watch-ci-domain"))).toBe(true);
+  });
+
+  test("extraFiles excludes SKILL.md and includes nested files", () => {
+    const { rootDir, roots } = makeFixtureRoots();
+    writeFile(
+      join(rootDir, "claimview", "attachments", "watch-ci-domain", "nested", "extra.txt"),
+      "extra\n",
+    );
+
+    const fill = loadAttachment("claimview:watch-ci-domain", "domain", roots);
+
+    expect(fill.extraFiles.sort()).toEqual(["ci-config.json", "nested/extra.txt"]);
+  });
+
+  test("throws naming the slot and binding when neither search root has the skill", () => {
+    const { roots } = makeFixtureRoots();
+    const claimviewDir = roots.byName.claimview!.dir;
+    const expectedSkillsPath = join(claimviewDir, "skills", "no-such-skill", "SKILL.md");
+    const expectedAttachmentsPath = join(claimviewDir, "attachments", "no-such-skill", "SKILL.md");
+
+    let thrown: unknown;
+    try {
+      loadAttachment("claimview:no-such-skill", "domain", roots);
+    } catch (err) {
+      thrown = err;
+    }
+
+    expect(thrown).toBeInstanceOf(Error);
+    const message = (thrown as Error).message;
+    expect(message).toContain("domain");
+    expect(message).toContain("claimview:no-such-skill");
+    expect(message).toContain(expectedSkillsPath);
+    expect(message).toContain(expectedAttachmentsPath);
+  });
+});
+
+describe("readVerbRoster", () => {
+  test("parses the real stubs.jsonc shape (comment-bearing JSONC)", () => {
+    const rootDir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-pack-")));
+    const stubsJsonc = `// Verb stubs for this pack. generate-stubs.sh renders skills/<verb>/SKILL.md
+// from these; regenerate after edits, never hand-edit generated files.
+{
+  "verbs": {
+    "watch-ci": {
+      "engine": "watch-ci",
+      "description": "Use when watching or triaging CI."
+    },
+    "ship": {
+      "engine": "ship",
+      // inline verb comment
+      "description": "Use when ready to ship."
+    }
+  }
+}
+`;
+    writeFile(join(rootDir, "pack", "stubs.jsonc"), stubsJsonc);
+
+    const roster = readVerbRoster(rootDir);
+
+    expect(roster).toEqual([
+      { name: "watch-ci", engine: "watch-ci", description: "Use when watching or triaging CI." },
+      { name: "ship", engine: "ship", description: "Use when ready to ship." },
+    ]);
+  });
+
+  test("throws naming the offending key when a verb name is a path breakout", () => {
+    const rootDir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-pack-")));
+    const stubsJsonc = `{
+  "verbs": {
+    "../evil": {
+      "engine": "watch-ci",
+      "description": "Use when watching or triaging CI."
+    }
+  }
+}
+`;
+    writeFile(join(rootDir, "pack", "stubs.jsonc"), stubsJsonc);
+
+    expect(() => readVerbRoster(rootDir)).toThrow(/"\.\.\/evil"/);
+  });
+});
+
+describe("readManifestBindings", () => {
+  test("parses a fixture copied from the real manifest's bindings shape", () => {
+    const rootDir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-manifest-")));
+    const manifestJsonc = `// GENERATED by merge-manifests.sh -- do not hand-edit for keeps;
+// the next pack install or merge run rewrites this file.
+{
+  "version": 1,
+  "skills": { "enabled": ["mattstack:watch-ci"] },
+  "bindings": {
+    "mattstack:watch-ci": {
+      "domain": "claimview:watch-ci-domain",
+      "forge": "mattstack:ci-forge-gitlab"
+    },
+    "mattstack:work": {
+      "tiering": "mattstack:model-tiering"
+    }
+  }
+}
+`;
+    const manifestPath = join(rootDir, "skills.jsonc");
+    writeFile(manifestPath, manifestJsonc);
+
+    const bindings = readManifestBindings(manifestPath);
+
+    expect(bindings).toEqual({
+      "mattstack:watch-ci": {
+        domain: "claimview:watch-ci-domain",
+        forge: "mattstack:ci-forge-gitlab",
+      },
+      "mattstack:work": {
+        tiering: "mattstack:model-tiering",
+      },
+    });
+  });
+});
+
+describe("invocableRoster", () => {
+  test("lists plugin:skillDirName for one- and two-level skills/ entries", () => {
+    const { roots } = makeFixtureRoots();
+
+    const roster = invocableRoster(roots);
+
+    expect(roster.has("mattstack:watch-ci")).toBe(true);
+    expect(roster.has("mattstack:untyped-step")).toBe(true);
+    expect(roster.has("claimview:cvi-gates")).toBe(true);
+    expect(roster.has("claimview:watch-ci-domain")).toBe(false);
+    expect(roster.has("mattstack:ship")).toBe(false);
+  });
+});
+
+describe("buildPluginRoots", () => {
+  test("skips an entry whose installPath does not exist, warns once, and still resolves the rest", () => {
+    const rootDir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-plugin-roots-")));
+
+    const mattstackDir = join(rootDir, "mattstack");
+    writeFile(join(mattstackDir, ".claude-plugin", "plugin.json"), JSON.stringify({ version: "1.2.0" }));
+
+    const claimviewDir = join(rootDir, "claimview");
+    writeFile(join(claimviewDir, ".claude-plugin", "plugin.json"), JSON.stringify({ version: "0.3.0" }));
+
+    const staleInstallPath = join(rootDir, "current-time", "0.1.0");
+
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+    let roots: PluginRoots;
+    let callCount: number;
+    let warning: string;
+    try {
+      roots = buildPluginRoots([
+        { id: "mattstack@mattstack", installPath: mattstackDir },
+        { id: "current-time@mattstack", installPath: staleInstallPath },
+        { id: "claimview@assured", installPath: claimviewDir },
+      ]);
+      // mockRestore() clears .mock.calls (bun, unlike jest), so read it before restoring.
+      callCount = errorSpy.mock.calls.length;
+      warning = errorSpy.mock.calls[0]?.join(" ") ?? "";
+    } finally {
+      errorSpy.mockRestore();
+    }
+
+    expect(roots.byName.mattstack).toEqual({ dir: mattstackDir, version: "1.2.0" });
+    expect(roots.byName.claimview).toEqual({ dir: claimviewDir, version: "0.3.0" });
+    expect(roots.byName["current-time"]).toBeUndefined();
+
+    expect(callCount).toBe(1);
+    expect(warning).toContain("current-time");
+    expect(warning).toContain(staleInstallPath);
+  });
+
+  test("no missing entries: every plugin resolves, no warning printed", () => {
+    const { roots: fixtureRoots } = makeFixtureRoots();
+
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+    let roots: PluginRoots;
+    let callCount: number;
+    try {
+      roots = buildPluginRoots([
+        { id: "mattstack@mattstack", installPath: fixtureRoots.byName.mattstack!.dir },
+        { id: "claimview@assured", installPath: fixtureRoots.byName.claimview!.dir },
+      ]);
+      callCount = errorSpy.mock.calls.length;
+    } finally {
+      errorSpy.mockRestore();
+    }
+
+    expect(roots.byName.mattstack?.version).toBe("1.2.0");
+    expect(roots.byName.claimview?.version).toBe("0.3.0");
+    expect(callCount).toBe(0);
+  });
+});
diff --git a/lib/skills/__tests__/surface.test.ts b/lib/skills/__tests__/surface.test.ts
new file mode 100644
index 00000000..9f28c0f9
--- /dev/null
+++ b/lib/skills/__tests__/surface.test.ts
@@ -0,0 +1,566 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, join } from "path";
+import { skillsCompile } from "../../../commands/skills.ts";
+import { compileSkill } from "../compile.ts";
+import { readSurface } from "../sources.ts";
+import type { AttachmentSource, StepSource, VerbDef } from "../types.ts";
+
+function writeFile(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+}
+
+describe("readSurface", () => {
+  test("parses a comment-bearing surface.jsonc", () => {
+    const packDir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-surface-pack-")));
+    const surfaceJsonc = `// surface.jsonc -- names this pack's public skills/ directories.
+{
+  "public": [
+    "watch-ci",
+    // hand-authored skill, not a compiled verb
+    "cvi-gates"
+  ]
+}
+`;
+    writeFile(join(packDir, "pack", "surface.jsonc"), surfaceJsonc);
+
+    const surface = readSurface(packDir);
+
+    expect(surface).toEqual({ public: ["watch-ci", "cvi-gates"] });
+  });
+
+  test("returns null when surface.jsonc is absent", () => {
+    const packDir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-surface-pack-")));
+
+    expect(readSurface(packDir)).toBeNull();
+  });
+
+  test("falls back to a root-level surface.jsonc when pack/ has none", () => {
+    const packDir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-surface-pack-")));
+    writeFile(join(packDir, "surface.jsonc"), `{ "public": ["editing-skills"] }\n`);
+
+    expect(readSurface(packDir)).toEqual({ public: ["editing-skills"] });
+  });
+
+  test("pack/surface.jsonc wins over a root-level copy", () => {
+    const packDir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-surface-pack-")));
+    writeFile(join(packDir, "pack", "surface.jsonc"), `{ "public": ["from-pack"] }\n`);
+    writeFile(join(packDir, "surface.jsonc"), `{ "public": ["from-root"] }\n`);
+
+    expect(readSurface(packDir)).toEqual({ public: ["from-pack"] });
+  });
+});
+
+describe("compileSkill with internalRoster", () => {
+  const verb: VerbDef = { name: "watch-ci", engine: "watch-ci-engine", description: "Watch CI" };
+  const roster = new Set(["mattstack:watch-ci", "claimview:watch-ci-domain"]);
+
+  test("a body token naming an internal skill produces an errors entry with fix options; a public token does not", () => {
+    const step: StepSource = {
+      name: "watch-ci",
+      plugin: "mattstack",
+      version: "1.0.0",
+      dir: "/plugins/mattstack/skills/pipeline/watch-ci",
+      body: "This step defers to claimview:cvi-gates for the internal check and to claimview:watch-ci-domain for the public one.",
+      slots: {},
+      allowedTools: [],
+      stepFiles: [],
+    };
+    const internalRoster = new Set(["claimview:cvi-gates"]);
+
+    const result = compileSkill(verb, step, {}, roster, { internalRoster });
+
+    expect(result.errors).toEqual([
+      "body references claimview:cvi-gates which is surface-internal; inline it, reference it by path, or list it in surface.jsonc's public array",
+    ]);
+  });
+
+  test("a description token naming an internal skill produces a description-labeled errors entry", () => {
+    const dirtyVerb: VerbDef = {
+      name: "watch-ci",
+      engine: "watch-ci-engine",
+      description: "Watch CI; for a gut check use claimview:cvi-gates first.",
+    };
+    const step: StepSource = {
+      name: "watch-ci",
+      plugin: "mattstack",
+      version: "1.0.0",
+      dir: "/plugins/mattstack/skills/pipeline/watch-ci",
+      body: "Clean body.",
+      slots: {},
+      allowedTools: [],
+      stepFiles: [],
+    };
+    const internalRoster = new Set(["claimview:cvi-gates"]);
+
+    const result = compileSkill(dirtyVerb, step, {}, roster, { internalRoster });
+
+    expect(result.errors).toEqual([
+      "description references claimview:cvi-gates which is surface-internal; inline it, reference it by path, or list it in surface.jsonc's public array",
+    ]);
+  });
+
+  test("no internalRoster entries: errors is empty", () => {
+    const step: StepSource = {
+      name: "watch-ci",
+      plugin: "mattstack",
+      version: "1.0.0",
+      dir: "/plugins/mattstack/skills/pipeline/watch-ci",
+      body: "This step defers to claimview:watch-ci-domain.",
+      slots: {},
+      allowedTools: [],
+      stepFiles: [],
+    };
+
+    const result = compileSkill(verb, step, {}, roster);
+
+    expect(result.errors).toEqual([]);
+  });
+
+  test("a fill whose binding is internal-listed inlines despite registered=true, with a printed note", () => {
+    const stepWithSlot: StepSource = {
+      name: "watch-ci",
+      plugin: "mattstack",
+      version: "1.0.0",
+      dir: "/plugins/mattstack/skills/pipeline/watch-ci",
+      body: "Poll CI.",
+      slots: { domain: { contract: "watch-ci-domain@1", required: true } },
+      allowedTools: [],
+      stepFiles: [],
+    };
+    const registeredInternalFill: AttachmentSource = {
+      binding: "claimview:cvi-gates",
+      plugin: "claimview",
+      version: "0.3.0",
+      dir: "/plugins/claimview/skills/cvi-gates",
+      body: "Domain rules inlined from cvi-gates.",
+      provides: "watch-ci-domain@1",
+      allowedTools: [],
+      extraFiles: [],
+      registered: true,
+    };
+    const internalRoster = new Set(["claimview:cvi-gates"]);
+
+    const result = compileSkill(verb, stepWithSlot, { domain: registeredInternalFill }, roster, {
+      internalRoster,
+    });
+
+    const skillFile = result.files[0];
+    if (!skillFile || !("content" in skillFile)) throw new Error("expected files[0] to have content");
+
+    expect(skillFile.content).toContain("Domain rules inlined from cvi-gates.");
+    expect(skillFile.content).not.toContain("invoke that skill when this flow needs it");
+    expect(result.warnings).toContain("note: claimview:cvi-gates is surface-internal; inlined");
+  });
+
+  test("a fill whose binding is NOT internal-listed still references, not inlines, when registered=true", () => {
+    const stepWithSlot: StepSource = {
+      name: "watch-ci",
+      plugin: "mattstack",
+      version: "1.0.0",
+      dir: "/plugins/mattstack/skills/pipeline/watch-ci",
+      body: "Poll CI.",
+      slots: { domain: { contract: "watch-ci-domain@1", required: true } },
+      allowedTools: [],
+      stepFiles: [],
+    };
+    const registeredPublicFill: AttachmentSource = {
+      binding: "claimview:cvi-gates",
+      plugin: "claimview",
+      version: "0.3.0",
+      dir: "/plugins/claimview/skills/cvi-gates",
+      body: "Domain rules for cvi-gates.",
+      provides: "watch-ci-domain@1",
+      allowedTools: [],
+      extraFiles: [],
+      registered: true,
+    };
+
+    const result = compileSkill(verb, stepWithSlot, { domain: registeredPublicFill }, roster, {
+      internalRoster: new Set(),
+    });
+
+    const skillFile = result.files[0];
+    if (!skillFile || !("content" in skillFile)) throw new Error("expected files[0] to have content");
+
+    expect(skillFile.content).toContain("invoke that skill when this flow needs it");
+    expect(skillFile.content).not.toContain("Domain rules for cvi-gates.");
+    expect(result.warnings).not.toContain("note: claimview:cvi-gates is surface-internal; inlined");
+  });
+});
+
+const WATCH_CI_SKILL_MD = `---
+name: watch-ci
+description: "Watch CI until it goes green"
+type: pipeline-step
+---
+
+Poll the pipeline every 30s and report status.
+`;
+
+const OLD_VERB_SKILL_MD = `---
+name: old-verb
+description: "A retired verb"
+type: pipeline-step
+---
+
+This verb is retired.
+`;
+
+const DANGLING_STEP_SKILL_MD = `---
+name: dangling-step
+description: "References a retired door"
+type: pipeline-step
+---
+
+Defers to claimview:old-verb for cleanup.
+`;
+
+const STRAY_SKILL_MD = `---
+name: stray-skill
+description: "Hand-authored skill not yet declared public"
+---
+
+Stray content.
+`;
+
+function makeMattstackDir(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-surface-mattstack-")));
+  const mattstackPluginDir = join(dir, "plugins", "mattstack");
+  writeFile(join(mattstackPluginDir, ".claude-plugin", "plugin.json"), JSON.stringify({ version: "1.2.0" }));
+  writeFile(join(mattstackPluginDir, "skills", "pipeline", "watch-ci", "SKILL.md"), WATCH_CI_SKILL_MD);
+  writeFile(join(mattstackPluginDir, "skills", "pipeline", "old-verb", "SKILL.md"), OLD_VERB_SKILL_MD);
+  writeFile(join(mattstackPluginDir, "skills", "pipeline", "dangling-step", "SKILL.md"), DANGLING_STEP_SKILL_MD);
+  return dir;
+}
+
+function makePackDir(stubsJsonc: string, surfaceJsonc: string | null): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-surface-pack-")));
+  writeFile(join(dir, "pack", "stubs.jsonc"), stubsJsonc);
+  if (surfaceJsonc !== null) {
+    writeFile(join(dir, "pack", "surface.jsonc"), surfaceJsonc);
+  }
+  return dir;
+}
+
+function makeManifest(team: string): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-surface-manifest-")));
+  const path = join(dir, "skills.jsonc");
+  writeFile(
+    path,
+    `// GENERATED -- provenance: ${team}@${team}\n{\n  "bindings": {}\n}\n`,
+  );
+  return path;
+}
+
+const STUBS_TWO_VERBS = `{
+  "verbs": {
+    "watch-ci": { "engine": "watch-ci", "description": "Watch CI." },
+    "old-verb": { "engine": "old-verb", "description": "Retired." }
+  }
+}
+`;
+
+let logSpy: ReturnType<typeof spyOn>;
+let logs: string[];
+
+beforeEach(() => {
+  logs = [];
+  logSpy = spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+    logs.push(args.map(String).join(" "));
+  });
+});
+
+afterEach(() => {
+  logSpy.mockRestore();
+  // Bun's process.exitCode setter ignores undefined once set truthy -- 0 is
+  // the only value that actually clears it between tests in this file.
+  process.exitCode = 0;
+});
+
+describe("skillsCompile with a surface config", () => {
+  test("skips a non-public verb, prints an internal line, and removes its compiled skills/ dir", async () => {
+    const mattstackDir = makeMattstackDir();
+    const surfaceJsonc = `{ "public": ["watch-ci"] }\n`;
+    const packDir = makePackDir(STUBS_TWO_VERBS, surfaceJsonc);
+    writeFile(join(packDir, "skills", "old-verb", "SKILL.md"), "stale compiled output\n");
+    const manifestPath = makeManifest("t");
+
+    await skillsCompile([
+      "--team", "t",
+      "--pack-dir", packDir,
+      "--mattstack-dir", mattstackDir,
+      "--manifest", manifestPath,
+    ]);
+
+    expect(logs).toContain("internal: old-verb (not compiled; roster entry retired)");
+    expect(existsSync(join(packDir, "skills", "old-verb"))).toBe(false);
+    expect(existsSync(join(packDir, "skills", "watch-ci", "SKILL.md"))).toBe(true);
+  });
+
+  test("placement verification flags a non-public dir left under skills/ and sets a nonzero exit", async () => {
+    const mattstackDir = makeMattstackDir();
+    const surfaceJsonc = `{ "public": ["watch-ci"] }\n`;
+    const packDir = makePackDir(STUBS_TWO_VERBS, surfaceJsonc);
+    writeFile(join(packDir, "skills", "stray-skill", "SKILL.md"), STRAY_SKILL_MD);
+    const manifestPath = makeManifest("t");
+
+    await skillsCompile([
+      "--team", "t",
+      "--pack-dir", packDir,
+      "--mattstack-dir", mattstackDir,
+      "--manifest", manifestPath,
+    ]);
+
+    expect(logs).toContain("misplaced: stray-skill (run rt skills surface apply, or move it)");
+    expect(process.exitCode).toBe(1);
+    // it never moves anything
+    expect(existsSync(join(packDir, "skills", "stray-skill", "SKILL.md"))).toBe(true);
+  });
+
+  test("a retired stub verb with no dir on disk still seeds the internal roster: dangling references error", async () => {
+    const mattstackDir = makeMattstackDir();
+    const stubs = `{
+  "verbs": {
+    "dangling": { "engine": "dangling-step", "description": "Dangling." },
+    "old-verb": { "engine": "old-verb", "description": "Retired." }
+  }
+}
+`;
+    const surfaceJsonc = `{ "public": ["dangling"] }\n`;
+    const packDir = makePackDir(stubs, surfaceJsonc);
+    const manifestPath = makeManifest("claimview");
+
+    const errors: string[] = [];
+    const errSpy = spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+      errors.push(args.map(String).join(" "));
+    });
+    const exitSpy = spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("process.exit called");
+    }) as never);
+
+    try {
+      await expect(
+        skillsCompile([
+          "--team", "claimview",
+          "--pack-dir", packDir,
+          "--mattstack-dir", mattstackDir,
+          "--manifest", manifestPath,
+        ]),
+      ).rejects.toThrow("process.exit called");
+
+      expect(errors.join("\n")).toContain("claimview:old-verb");
+      expect(errors.join("\n")).toContain("surface-internal");
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+    }
+  });
+
+  test("no surface.jsonc present: all verbs compile, no internal/misplaced lines, no exit code", async () => {
+    const mattstackDir = makeMattstackDir();
+    const packDir = makePackDir(STUBS_TWO_VERBS, null);
+    const manifestPath = makeManifest("t");
+
+    await skillsCompile([
+      "--team", "t",
+      "--pack-dir", packDir,
+      "--mattstack-dir", mattstackDir,
+      "--manifest", manifestPath,
+    ]);
+
+    expect(logs.some((l) => l.startsWith("internal:"))).toBe(false);
+    expect(logs.some((l) => l.startsWith("misplaced:"))).toBe(false);
+    expect(existsSync(join(packDir, "skills", "watch-ci", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(packDir, "skills", "old-verb", "SKILL.md"))).toBe(true);
+    expect(process.exitCode).not.toBe(1);
+  });
+});
+
+/**
+ * computeInternalRoster reads <packDir>/skills/ while loadAttachment resolves
+ * "<team>:X" bindings against the plugin root claude resolves for that team --
+ * in production those are the same physical tree (the pack IS the installed
+ * plugin). The tests above never exercise that: makeMattstackDir/makePackDir
+ * keep the pack dir and the team's plugin dir separate. These fixtures make
+ * plugins/claimview/ BOTH --pack-dir and the resolved "claimview" plugin
+ * root, so a real end-to-end skillsCompile run is exercised.
+ */
+const CVI_GATES_SKILL_MD = `---
+name: cvi-gates
+description: "Domain gating rules"
+metadata:
+  provides: "watch-ci-domain@1"
+---
+
+Domain rules inlined from cvi-gates for the transition window.
+`;
+
+const WATCH_CI_WITH_SLOT_SKILL_MD = `---
+name: watch-ci
+description: "Watch CI until it goes green"
+type: pipeline-step
+slots:
+  domain: { contract: "watch-ci-domain@1", required: true }
+---
+
+Poll CI.
+`;
+
+const GATE_CHECK_SKILL_MD = `---
+name: gate-check
+description: "Gate check"
+type: pipeline-step
+---
+
+This step defers to claimview:cvi-gates for domain judgment.
+`;
+
+function makeManifestAt(bindingsJson: string): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-surface-int-manifest-")));
+  const path = join(dir, "skills.jsonc");
+  writeFile(path, `// GENERATED -- provenance: claimview@claimview\n{ "bindings": ${bindingsJson} }\n`);
+  return path;
+}
+
+async function runExpectingCleanExit(
+  fn: () => Promise<void>,
+): Promise<{ exitCode: number | undefined; errors: string[] }> {
+  const errors: string[] = [];
+  const exitSpy = spyOn(process, "exit").mockImplementation(() => {
+    throw new Error("process.exit sentinel");
+  });
+  const errorSpy = spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+    errors.push(args.map(String).join(" "));
+  });
+  try {
+    await fn();
+    return { exitCode: undefined, errors };
+  } catch {
+    const exitCode = exitSpy.mock.calls.at(-1)?.[0] as number | undefined;
+    return { exitCode, errors };
+  } finally {
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  }
+}
+
+describe("computeInternalRoster integration (pack dir doubles as plugin root)", () => {
+  test("a registered-but-not-yet-public fill inlines end to end, notes, and is flagged misplaced", async () => {
+    const mattstackDir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-surface-int-")));
+
+    const claimviewDir = join(mattstackDir, "plugins", "claimview");
+    writeFile(join(claimviewDir, ".claude-plugin", "plugin.json"), JSON.stringify({ version: "0.3.0" }));
+    writeFile(
+      join(claimviewDir, "pack", "stubs.jsonc"),
+      `{ "verbs": { "watch-ci": { "engine": "watch-ci", "description": "Watch CI." } } }\n`,
+    );
+    writeFile(join(claimviewDir, "pack", "surface.jsonc"), `{ "public": ["watch-ci"] }\n`);
+    writeFile(join(claimviewDir, "skills", "cvi-gates", "SKILL.md"), CVI_GATES_SKILL_MD);
+
+    const mattstackPluginDir = join(mattstackDir, "plugins", "mattstack");
+    writeFile(join(mattstackPluginDir, ".claude-plugin", "plugin.json"), JSON.stringify({ version: "1.2.0" }));
+    writeFile(
+      join(mattstackPluginDir, "skills", "pipeline", "watch-ci", "SKILL.md"),
+      WATCH_CI_WITH_SLOT_SKILL_MD,
+    );
+
+    const manifestPath = makeManifestAt('{ "mattstack:watch-ci": { "domain": "claimview:cvi-gates" } }');
+
+    await skillsCompile([
+      "--team", "claimview",
+      "--pack-dir", claimviewDir,
+      "--mattstack-dir", mattstackDir,
+      "--manifest", manifestPath,
+      "--verb", "watch-ci",
+    ]);
+
+    const content = readFileSync(join(claimviewDir, "skills", "watch-ci", "SKILL.md"), "utf8");
+    expect(content).toContain("Domain rules inlined from cvi-gates for the transition window.");
+    expect(content).not.toContain("invoke that skill when this flow needs it");
+
+    expect(logs).toContain("  note: claimview:cvi-gates is surface-internal; inlined");
+    // cvi-gates is still physically under skills/ and isn't in surface.public --
+    // it compiles (inlined) AND is flagged for the move surface apply would do.
+    expect(logs).toContain("misplaced: cvi-gates (run rt skills surface apply, or move it)");
+    expect(process.exitCode).toBe(1);
+  });
+
+  test("a body reference to an internal skill aborts that verb via the errors channel, cleanly, with no partial write", async () => {
+    const mattstackDir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-surface-int-")));
+
+    const claimviewDir = join(mattstackDir, "plugins", "claimview");
+    writeFile(join(claimviewDir, ".claude-plugin", "plugin.json"), JSON.stringify({ version: "0.3.0" }));
+    writeFile(
+      join(claimviewDir, "pack", "stubs.jsonc"),
+      `{ "verbs": { "gate-check": { "engine": "gate-check", "description": "Gate check." } } }\n`,
+    );
+    writeFile(join(claimviewDir, "pack", "surface.jsonc"), `{ "public": ["gate-check"] }\n`);
+    writeFile(join(claimviewDir, "skills", "cvi-gates", "SKILL.md"), CVI_GATES_SKILL_MD);
+
+    const mattstackPluginDir = join(mattstackDir, "plugins", "mattstack");
+    writeFile(join(mattstackPluginDir, ".claude-plugin", "plugin.json"), JSON.stringify({ version: "1.2.0" }));
+    writeFile(join(mattstackPluginDir, "skills", "pipeline", "gate-check", "SKILL.md"), GATE_CHECK_SKILL_MD);
+
+    const manifestPath = makeManifestAt("{}");
+
+    const { exitCode, errors } = await runExpectingCleanExit(() =>
+      skillsCompile([
+        "--team", "claimview",
+        "--pack-dir", claimviewDir,
+        "--mattstack-dir", mattstackDir,
+        "--manifest", manifestPath,
+        "--verb", "gate-check",
+      ]),
+    );
+
+    expect(exitCode).toBe(1);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toStartWith("rt skills: ");
+    expect(errors[0]).toContain("gate-check");
+    expect(errors[0]).toContain("claimview:cvi-gates");
+    expect(errors[0]).toContain("surface-internal");
+    expect(existsSync(join(claimviewDir, "skills", "gate-check"))).toBe(false);
+  });
+
+  test("post-move steady state: a skill already under attachments/ still seeds the internal roster; a body reference errors", async () => {
+    const mattstackDir = realpathSync(mkdtempSync(join(tmpdir(), "rt-skills-surface-int-")));
+
+    const claimviewDir = join(mattstackDir, "plugins", "claimview");
+    writeFile(join(claimviewDir, ".claude-plugin", "plugin.json"), JSON.stringify({ version: "0.3.0" }));
+    writeFile(
+      join(claimviewDir, "pack", "stubs.jsonc"),
+      `{ "verbs": { "gate-check": { "engine": "gate-check", "description": "Gate check." } } }\n`,
+    );
+    writeFile(join(claimviewDir, "pack", "surface.jsonc"), `{ "public": ["gate-check"] }\n`);
+    // cvi-gates already moved by a prior `surface apply` -- lives under
+    // attachments/, not skills/, and is absent from surface.public.
+    writeFile(join(claimviewDir, "attachments", "cvi-gates", "SKILL.md"), CVI_GATES_SKILL_MD);
+
+    const mattstackPluginDir = join(mattstackDir, "plugins", "mattstack");
+    writeFile(join(mattstackPluginDir, ".claude-plugin", "plugin.json"), JSON.stringify({ version: "1.2.0" }));
+    writeFile(join(mattstackPluginDir, "skills", "pipeline", "gate-check", "SKILL.md"), GATE_CHECK_SKILL_MD);
+
+    const manifestPath = makeManifestAt("{}");
+
+    const { exitCode, errors } = await runExpectingCleanExit(() =>
+      skillsCompile([
+        "--team", "claimview",
+        "--pack-dir", claimviewDir,
+        "--mattstack-dir", mattstackDir,
+        "--manifest", manifestPath,
+        "--verb", "gate-check",
+      ]),
+    );
+
+    expect(exitCode).toBe(1);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toStartWith("rt skills: ");
+    expect(errors[0]).toContain("gate-check");
+    expect(errors[0]).toContain("claimview:cvi-gates");
+    expect(errors[0]).toContain("surface-internal");
+    expect(existsSync(join(claimviewDir, "skills", "gate-check"))).toBe(false);
+  });
+});
diff --git a/lib/skills/compile.ts b/lib/skills/compile.ts
new file mode 100644
index 00000000..fc64fbcf
--- /dev/null
+++ b/lib/skills/compile.ts
@@ -0,0 +1,235 @@
+import type { AttachmentSource, CompiledFile, CompileResult, StepSource, VerbDef } from "./types.ts";
+
+const CLAUDE_SKILL_DIR_TOKEN = "${CLAUDE_SKILL_DIR}";
+
+/** Exported so `rt skills surface` can classify a directory as compiled by checking its SKILL.md body prefix. */
+export const HEADER_COMMENT =
+  "<!-- compiled by rt skills compile from the sources below; slots pre-resolved; edits here are working-tree drift (rt skills promote) -->";
+
+const REGISTERED_NAME_RE = /\b(mattstack|claimview|assured):[a-z][a-z0-9-]*\b/g;
+const SKILL_DIR_PATH_RE = /\$\{CLAUDE_SKILL_DIR\}\/[^\s"'`)]+/g;
+
+type BoundSlot = { slotName: string; fill: AttachmentSource };
+
+function rewriteSkillDirRefs(text: string, slotName: string): string {
+  return text.split(CLAUDE_SKILL_DIR_TOKEN).join(`${CLAUDE_SKILL_DIR_TOKEN}/parts/${slotName}`);
+}
+
+function dedupePreserveOrder(entries: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const entry of entries) {
+    if (!seen.has(entry)) {
+      seen.add(entry);
+      out.push(entry);
+    }
+  }
+  return out;
+}
+
+function yamlQuote(value: string): string {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function resolveBoundSlots(
+  verb: VerbDef,
+  step: StepSource,
+  fills: Record<string, AttachmentSource | null>,
+): BoundSlot[] {
+  const boundSlots: BoundSlot[] = [];
+
+  for (const slotName of Object.keys(step.slots)) {
+    const spec = step.slots[slotName];
+    if (!spec) continue;
+    const fill = fills[slotName] ?? null;
+
+    if (fill === null) {
+      if (spec.required) {
+        throw new Error(
+          `verb "${verb.name}": slot "${slotName}" requires contract "${spec.contract}" but is unbound`,
+        );
+      }
+      continue;
+    }
+
+    if (fill.provides !== spec.contract) {
+      throw new Error(
+        `verb "${verb.name}": slot "${slotName}" requires contract "${spec.contract}" but binding "${fill.binding}" provides "${fill.provides}"`,
+      );
+    }
+
+    boundSlots.push({ slotName, fill });
+  }
+
+  return boundSlots;
+}
+
+function buildAllowedTools(step: StepSource, boundSlots: BoundSlot[]): string[] {
+  const entries = [
+    ...step.allowedTools,
+    ...boundSlots.flatMap(({ slotName, fill }) =>
+      fill.allowedTools.map((tool) => rewriteSkillDirRefs(tool, slotName)),
+    ),
+  ];
+  return dedupePreserveOrder(entries);
+}
+
+function buildFrontmatter(verb: VerbDef, allowedTools: string[], compiledParts: string[]): string {
+  const lines: string[] = ["---"];
+  lines.push(`name: ${yamlQuote(verb.name)}`);
+  lines.push(`description: ${yamlQuote(verb.description)}`);
+  if (allowedTools.length > 0) {
+    lines.push("allowed-tools:");
+    for (const tool of allowedTools) {
+      lines.push(`  - ${yamlQuote(tool)}`);
+    }
+  }
+  lines.push("metadata:");
+  lines.push(`  compiled: ${yamlQuote(compiledParts.join(" + "))}`);
+  lines.push("---");
+  return lines.join("\n");
+}
+
+function buildBody(
+  step: StepSource,
+  boundSlots: BoundSlot[],
+  internalRoster: Set<string>,
+): { body: string; notes: string[] } {
+  const sections: string[] = [HEADER_COMMENT];
+  const notes: string[] = [];
+
+  sections.push(`<!-- part: step source=${step.plugin}:${step.name} version=${step.version} -->`);
+  sections.push(step.body);
+
+  for (const { slotName, fill } of boundSlots) {
+    const internal = internalRoster.has(fill.binding);
+
+    if (fill.registered && !internal) {
+      // Registered, surface-public skills stay singly-canonical: reference, never inline.
+      sections.push(
+        `Slot ${slotName} is bound to \`${fill.binding}\` (${fill.binding}@${fill.version}) -- invoke that skill when this flow needs it.`,
+      );
+      continue;
+    }
+
+    if (fill.registered && internal) {
+      // Transition window: the file already lives under skills/ but surface.jsonc
+      // has not declared it public yet -- inline so the compiled output stays correct.
+      notes.push(`note: ${fill.binding} is surface-internal; inlined`);
+    }
+
+    sections.push(`<!-- part: slot:${slotName} binding=${fill.binding} version=${fill.version} -->`);
+    sections.push(rewriteSkillDirRefs(fill.body, slotName));
+  }
+
+  return { body: sections.join("\n\n"), notes };
+}
+
+function buildVendoredFiles(step: StepSource, boundSlots: BoundSlot[]): CompiledFile[] {
+  const files: CompiledFile[] = [];
+
+  for (const entry of step.stepFiles) {
+    files.push({ path: entry, copyFrom: `${step.dir}/${entry}` });
+  }
+
+  for (const { slotName, fill } of boundSlots) {
+    for (const entry of fill.extraFiles) {
+      files.push({ path: `parts/${slotName}/${entry}`, copyFrom: `${fill.dir}/${entry}` });
+    }
+  }
+
+  return files;
+}
+
+function isCompilerCommentLine(line: string): boolean {
+  const trimmed = line.trim();
+  return trimmed === HEADER_COMMENT || trimmed.startsWith("<!-- part: ");
+}
+
+// Seam/header comments carry deliberately non-invocable names (e.g. an internal
+// attachment's binding); only author prose is lint material.
+function stripCompilerComments(body: string): string {
+  return body
+    .split("\n")
+    .filter((line) => !isCompilerCommentLine(line))
+    .join("\n");
+}
+
+function lintReferences(body: string, roster: Set<string>, files: CompiledFile[]): string[] {
+  const warnings: string[] = [];
+  const lintableBody = stripCompilerComments(body);
+
+  const seenNames = new Set<string>();
+  for (const match of lintableBody.matchAll(REGISTERED_NAME_RE)) {
+    const token = match[0];
+    if (seenNames.has(token)) continue;
+    seenNames.add(token);
+    if (!roster.has(token)) {
+      warnings.push(`body references ${token} which is not invocable`);
+    }
+  }
+
+  const emittedPaths = new Set(files.map((f) => f.path));
+  const seenPaths = new Set<string>();
+  for (const match of lintableBody.matchAll(SKILL_DIR_PATH_RE)) {
+    const full = match[0];
+    if (seenPaths.has(full)) continue;
+    seenPaths.add(full);
+    const relPath = full.slice(`${CLAUDE_SKILL_DIR_TOKEN}/`.length);
+    if (!emittedPaths.has(relPath)) {
+      warnings.push(`body references ${full} which is not an emitted file`);
+    }
+  }
+
+  return warnings;
+}
+
+function lintInternalRoster(text: string, internalRoster: Set<string>, where: string): string[] {
+  const errors: string[] = [];
+  const lintableText = stripCompilerComments(text);
+
+  const seenNames = new Set<string>();
+  for (const match of lintableText.matchAll(REGISTERED_NAME_RE)) {
+    const token = match[0];
+    if (seenNames.has(token)) continue;
+    seenNames.add(token);
+    if (internalRoster.has(token)) {
+      errors.push(
+        `${where} references ${token} which is surface-internal; inline it, reference it by path, or list it in surface.jsonc's public array`,
+      );
+    }
+  }
+
+  return errors;
+}
+
+export function compileSkill(
+  verb: VerbDef,
+  step: StepSource,
+  fills: Record<string, AttachmentSource | null>,
+  roster: Set<string>,
+  opts?: { internalRoster?: Set<string> },
+): CompileResult {
+  const internalRoster = opts?.internalRoster ?? new Set<string>();
+  const boundSlots = resolveBoundSlots(verb, step, fills);
+
+  const allowedTools = buildAllowedTools(step, boundSlots);
+  const compiledParts = [
+    `${step.plugin}@${step.version}`,
+    ...boundSlots.map(({ fill }) => `${fill.binding}@${fill.version}`),
+  ];
+
+  const { body, notes } = buildBody(step, boundSlots, internalRoster);
+  const frontmatter = buildFrontmatter(verb, allowedTools, compiledParts);
+  const content = `${frontmatter}\n\n${body}\n`;
+
+  const files: CompiledFile[] = [{ path: "SKILL.md", content }, ...buildVendoredFiles(step, boundSlots)];
+
+  const warnings = [...lintReferences(body, roster, files), ...notes];
+  const errors = [
+    ...lintInternalRoster(body, internalRoster, "body"),
+    ...lintInternalRoster(verb.description, internalRoster, "description"),
+  ];
+
+  return { files, warnings, errors };
+}
diff --git a/lib/skills/sources.ts b/lib/skills/sources.ts
new file mode 100644
index 00000000..e238ff7f
--- /dev/null
+++ b/lib/skills/sources.ts
@@ -0,0 +1,358 @@
+import { execSync } from "child_process";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "fs";
+import { join } from "path";
+import { parse as parseYaml } from "yaml";
+import type { AttachmentSource, SlotSpec, StepSource, VerbDef } from "./types.ts";
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+export function stripJsonc(raw: string): string {
+  return raw
+    .split("\n")
+    .filter((line) => !line.trim().startsWith("//"))
+    .join("\n");
+}
+
+export function stripFrontmatter(md: string): { body: string; frontmatter: Record<string, unknown> } {
+  const match = md.match(FRONTMATTER_RE);
+  if (!match) {
+    return { body: md.trim(), frontmatter: {} };
+  }
+  const parsed = parseYaml(match[1] ?? "");
+  const frontmatter = parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+  const body = md.slice(match[0].length).trim();
+  return { body, frontmatter };
+}
+
+export type PluginRoots = { byName: Record<string, { dir: string; version: string }> };
+
+export type PluginListEntry = { id: string; installPath: string };
+
+/**
+ * Entry-processing half of resolvePluginRoots, split out so it's testable
+ * without shelling out to `claude`. `claude plugin list --json` can list an
+ * entry whose installPath was since removed or moved (an uninstalled or
+ * relocated plugin the cache index hasn't caught up with yet) -- that must
+ * not take down resolution for every other plugin, so a missing installPath
+ * is skipped with a warning instead of throwing.
+ */
+export function buildPluginRoots(list: PluginListEntry[]): PluginRoots {
+  const byName: PluginRoots["byName"] = {};
+
+  for (const entry of list) {
+    const name = entry.id.split("@")[0];
+    if (!name) continue;
+    if (!existsSync(entry.installPath)) {
+      console.error(`rt: skipping plugin "${name}" -- installPath does not exist: ${entry.installPath}`);
+      continue;
+    }
+    const dir = realpathSync(entry.installPath);
+    let version = "unknown";
+    try {
+      const pluginJson = JSON.parse(readFileSync(join(dir, ".claude-plugin", "plugin.json"), "utf8"));
+      if (typeof pluginJson.version === "string") version = pluginJson.version;
+    } catch {
+      // best-effort: a plugin without a readable manifest still resolves a root
+    }
+    byName[name] = { dir, version };
+  }
+
+  return { byName };
+}
+
+/**
+ * Thin by design: shelling out to `claude plugin list` is slow and
+ * environment-dependent, so the subprocess call itself is not unit-tested;
+ * buildPluginRoots carries the tested logic and this wrapper is exercised
+ * live against real installed plugins in integration coverage instead.
+ */
+export function resolvePluginRoots(): PluginRoots {
+  const raw = execSync("claude plugin list --json", { encoding: "utf8" });
+  const list = JSON.parse(raw) as PluginListEntry[];
+  return buildPluginRoots(list);
+}
+
+function parseSlots(raw: unknown): Record<string, SlotSpec> {
+  if (!raw || typeof raw !== "object") return {};
+  const out: Record<string, SlotSpec> = {};
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!value || typeof value !== "object") continue;
+    const spec = value as Record<string, unknown>;
+    if (typeof spec.contract !== "string") continue;
+    out[key] = {
+      contract: spec.contract,
+      ...(typeof spec.required === "boolean" ? { required: spec.required } : {}),
+    };
+  }
+  return out;
+}
+
+function parseAllowedTools(raw: unknown): string[] {
+  if (Array.isArray(raw)) return raw.filter((entry): entry is string => typeof entry === "string");
+  if (typeof raw === "string") {
+    return raw
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+  return [];
+}
+
+/**
+ * Vendoring exclusions: development junk that must not ship inside a
+ * compiled verb -- dotfiles/dotdirs (.DS_Store, .gitignore), python
+ * bytecode, test harnesses, and READMEs. Load-bearing runtime files
+ * (scripts/, references/, data files) all pass.
+ */
+const VENDOR_EXCLUDED_DIRS = new Set(["__pycache__", "tests"]);
+
+function isVendorExcluded(name: string, isDir: boolean): boolean {
+  if (name.startsWith(".")) return true;
+  if (isDir) return VENDOR_EXCLUDED_DIRS.has(name);
+  return name.endsWith(".pyc") || name.endsWith(".test.sh") || name === "README.md";
+}
+
+function listFilesUnder(dir: string, exclude: Set<string>): string[] {
+  const out: string[] = [];
+  const walk = (sub: string) => {
+    const abs = sub ? join(dir, sub) : dir;
+    if (!existsSync(abs)) return;
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+      if (isVendorExcluded(entry.name, entry.isDirectory())) continue;
+      const rel = sub ? `${sub}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(rel);
+      } else if (entry.isFile() && !exclude.has(rel)) {
+        out.push(rel);
+      }
+    }
+  };
+  walk("");
+  return out.sort();
+}
+
+function listDirs(dir: string): string[] {
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+export function loadStepSource(engineName: string, roots: PluginRoots): StepSource {
+  const mattstack = roots.byName.mattstack;
+  if (!mattstack) {
+    throw new Error(`loadStepSource: no "mattstack" plugin root registered`);
+  }
+
+  const skillsDir = join(mattstack.dir, "skills");
+  const attachmentsDir = join(mattstack.dir, "attachments");
+  const searched: string[] = [];
+  let foundDir: string | null = null;
+
+  for (const group of listDirs(skillsDir)) {
+    const candidate = join(skillsDir, group, engineName, "SKILL.md");
+    searched.push(candidate);
+    if (existsSync(candidate)) {
+      foundDir = join(skillsDir, group, engineName);
+      break;
+    }
+  }
+
+  // Non-public engines live unregistered under attachments/ once moved out of
+  // skills/ (registration under skills/ is what puts an engine in the user's
+  // slash autocomplete); fall back there in the same shape loadAttachment
+  // searches -- flat, then one group level deep.
+  if (!foundDir) {
+    const flatCandidate = join(attachmentsDir, engineName, "SKILL.md");
+    searched.push(flatCandidate);
+    if (existsSync(flatCandidate)) {
+      foundDir = join(attachmentsDir, engineName);
+    }
+  }
+
+  if (!foundDir) {
+    for (const group of listDirs(attachmentsDir)) {
+      const candidate = join(attachmentsDir, group, engineName, "SKILL.md");
+      searched.push(candidate);
+      if (existsSync(candidate)) {
+        foundDir = join(attachmentsDir, group, engineName);
+        break;
+      }
+    }
+  }
+
+  if (!foundDir) {
+    throw new Error(
+      `loadStepSource: engine "${engineName}" not found under ${skillsDir}/* or ${attachmentsDir}/*; searched:\n${searched.join("\n")}`,
+    );
+  }
+
+  const skillMdPath = join(foundDir, "SKILL.md");
+  const { body, frontmatter } = stripFrontmatter(readFileSync(skillMdPath, "utf8"));
+
+  if (frontmatter.type !== "pipeline-step") {
+    throw new Error(`loadStepSource: "${skillMdPath}" is not typed "type: pipeline-step"`);
+  }
+
+  return {
+    name: engineName,
+    plugin: "mattstack",
+    version: mattstack.version,
+    dir: foundDir,
+    body,
+    slots: parseSlots(frontmatter.slots),
+    allowedTools: parseAllowedTools(frontmatter["allowed-tools"]),
+    stepFiles: listFilesUnder(foundDir, new Set(["SKILL.md"])),
+  };
+}
+
+export function loadAttachment(binding: string, slot: string, roots: PluginRoots): AttachmentSource {
+  const [plugin, skillName] = binding.split(":");
+  if (!plugin || !skillName) {
+    throw new Error(`loadAttachment: slot "${slot}": binding "${binding}" is not "<plugin>:<skill>"`);
+  }
+
+  const pluginRoot = roots.byName[plugin];
+  if (!pluginRoot) {
+    throw new Error(
+      `loadAttachment: slot "${slot}": no plugin root registered for "${plugin}" (binding "${binding}")`,
+    );
+  }
+
+  const searched: string[] = [];
+  let foundDir: string | null = null;
+  let registered = false;
+
+  const skillsDir = join(pluginRoot.dir, "skills");
+  const oneLevel = join(skillsDir, skillName, "SKILL.md");
+  searched.push(oneLevel);
+  if (existsSync(oneLevel)) {
+    foundDir = join(skillsDir, skillName);
+    registered = true;
+  }
+
+  if (!foundDir) {
+    for (const group of listDirs(skillsDir)) {
+      const candidate = join(skillsDir, group, skillName, "SKILL.md");
+      searched.push(candidate);
+      if (existsSync(candidate)) {
+        foundDir = join(skillsDir, group, skillName);
+        registered = true;
+        break;
+      }
+    }
+  }
+
+  if (!foundDir) {
+    const attachmentPath = join(pluginRoot.dir, "attachments", skillName, "SKILL.md");
+    searched.push(attachmentPath);
+    if (existsSync(attachmentPath)) {
+      foundDir = join(pluginRoot.dir, "attachments", skillName);
+      registered = false;
+    }
+  }
+
+  if (!foundDir) {
+    throw new Error(
+      `loadAttachment: slot "${slot}": binding "${binding}" not found; searched:\n${searched.join("\n")}`,
+    );
+  }
+
+  const skillMdPath = join(foundDir, "SKILL.md");
+  const { body, frontmatter } = stripFrontmatter(readFileSync(skillMdPath, "utf8"));
+
+  const metadata = frontmatter.metadata && typeof frontmatter.metadata === "object"
+    ? (frontmatter.metadata as Record<string, unknown>)
+    : {};
+  const provides = typeof metadata.provides === "string" ? metadata.provides : "";
+  if (!provides) {
+    throw new Error(`loadAttachment: slot "${slot}": "${skillMdPath}" has no metadata.provides`);
+  }
+
+  return {
+    binding,
+    plugin,
+    version: pluginRoot.version,
+    dir: foundDir,
+    body,
+    provides,
+    allowedTools: parseAllowedTools(frontmatter["allowed-tools"]),
+    extraFiles: listFilesUnder(foundDir, new Set(["SKILL.md"])),
+    registered,
+  };
+}
+
+/**
+ * Verb names flow unsanitized into join(packDir, "skills", name) at two
+ * destructive call sites (writeCompiledVerb's rmSync + the internal-verb
+ * skip's rmSync in commands/skills.ts) -- reject path-breakout characters
+ * here, at the one place every verb name is read from disk.
+ */
+function assertSafeVerbName(name: string, stubsPath: string): void {
+  if (name.includes("/") || name.includes("\\") || name.includes("..")) {
+    throw new Error(
+      `readVerbRoster: verb key "${name}" in ${stubsPath} is not a safe directory name (must not contain "/", "\\", or "..")`,
+    );
+  }
+}
+
+export function readVerbRoster(packDir: string): VerbDef[] {
+  const stubsPath = join(packDir, "pack", "stubs.jsonc");
+  const parsed = JSON.parse(stripJsonc(readFileSync(stubsPath, "utf8"))) as {
+    verbs?: Record<string, { engine: string; description: string }>;
+  };
+  const verbs = parsed.verbs ?? {};
+  return Object.entries(verbs).map(([name, def]) => {
+    assertSafeVerbName(name, stubsPath);
+    return { name, engine: def.engine, description: def.description };
+  });
+}
+
+export function readManifestBindings(manifestPath: string): Record<string, Record<string, string>> {
+  const parsed = JSON.parse(stripJsonc(readFileSync(manifestPath, "utf8"))) as {
+    bindings?: Record<string, Record<string, string>>;
+  };
+  return parsed.bindings ?? {};
+}
+
+export type SurfaceConfig = { public: string[] };
+
+export function readSurface(packDir: string): SurfaceConfig | null {
+  // Packs without a pack/ config dir (the mattstack plugin repo) declare their
+  // surface at the plugin root beside .claude-plugin; pack/surface.jsonc wins.
+  const surfacePath = [join(packDir, "pack", "surface.jsonc"), join(packDir, "surface.jsonc")]
+    .find((candidate) => existsSync(candidate));
+  if (!surfacePath) return null;
+  const parsed = JSON.parse(stripJsonc(readFileSync(surfacePath, "utf8"))) as { public?: unknown };
+  const publicList = Array.isArray(parsed.public)
+    ? parsed.public.filter((entry): entry is string => typeof entry === "string")
+    : [];
+  return { public: publicList };
+}
+
+export function invocableRoster(roots: PluginRoots): Set<string> {
+  const roster = new Set<string>();
+
+  for (const [pluginName, root] of Object.entries(roots.byName)) {
+    const skillsDir = join(root.dir, "skills");
+
+    for (const topName of listDirs(skillsDir)) {
+      if (existsSync(join(skillsDir, topName, "SKILL.md"))) {
+        roster.add(`${pluginName}:${topName}`);
+      }
+
+      const groupDir = join(skillsDir, topName);
+      for (const subName of listDirs(groupDir)) {
+        if (existsSync(join(groupDir, subName, "SKILL.md"))) {
+          roster.add(`${pluginName}:${subName}`);
+        }
+      }
+    }
+  }
+
+  return roster;
+}
diff --git a/lib/skills/types.ts b/lib/skills/types.ts
new file mode 100644
index 00000000..5acaff2d
--- /dev/null
+++ b/lib/skills/types.ts
@@ -0,0 +1,30 @@
+export type SlotSpec = { contract: string; required?: boolean };
+
+export type StepSource = {
+  name: string; // engine name, e.g. "watch-ci"
+  plugin: string; // e.g. "mattstack"
+  version: string; // plugin version string
+  dir: string; // absolute source dir
+  body: string; // frontmatter-stripped markdown
+  slots: Record<string, SlotSpec>;
+  allowedTools: string[]; // raw entries from frontmatter allowed-tools
+  stepFiles: string[]; // non-SKILL.md files relative to dir (scripts/, references/, ...), vendored path-preserving
+};
+
+export type AttachmentSource = {
+  binding: string; // e.g. "claimview:watch-ci-domain"
+  plugin: string;
+  version: string;
+  dir: string;
+  body: string;
+  provides: string; // frontmatter metadata.provides, e.g. "watch-ci-domain@1"
+  allowedTools: string[];
+  extraFiles: string[]; // non-SKILL.md files relative to dir, vendored under parts/<slot>/
+  registered: boolean; // true = top-level skill under skills/, referenced not inlined; false = internal attachment under attachments/, inlined
+};
+
+export type VerbDef = { name: string; engine: string; description: string };
+
+export type CompiledFile = { path: string; content: string } | { path: string; copyFrom: string };
+
+export type CompileResult = { files: CompiledFile[]; warnings: string[]; errors: string[] };