swe-workflow-skills 0.3.0 → 0.5.0

package/README.md

@@ -1,5 +1,6 @@
 # SWE Workflow Skills for Claude Code
 
+[![npm](https://img.shields.io/npm/v/swe-workflow-skills)](https://www.npmjs.com/package/swe-workflow-skills)
 [![roles-check](https://github.com/SWEStash/swe-workflow-skills/actions/workflows/roles-check.yml/badge.svg)](https://github.com/SWEStash/swe-workflow-skills/actions/workflows/roles-check.yml)
 ![skills](https://img.shields.io/badge/skills-65-blue)
 [![license: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
@@ -59,12 +60,28 @@ web, claude.ai chat, and Cowork):
 /plugin install swe-workflow-pm@swe-workflow
 ```
 
-**Want the whole library with the orchestrator** (CLI) — no clone needed:
+**Want the whole library with the orchestrator** (CLI) — no clone needed. This is a
+**two-step** setup:
 
 ```bash
-npx swe-workflow-skills install --global   # all 65 skills + router + /role + the SessionStart hook
+# 1. Install all 65 skills + router + /role + the hook script, and apply the baseline
+npx swe-workflow-skills install --global
 ```
 
+```jsonc
+// 2. Wire the hook: merge the snippet the installer prints into your settings.json
+//    (the installer never edits settings.json for you — it just prints the block).
+//    Then start a new session; /doctor should show the hook registered.
+{ "hooks": { "SessionStart": [ /* ...the printed block... */ ] } }
+```
+
+> ⚠️ **Don't skip step 2.** Step 1 alone installs the skills and prevents cropping, but
+> the hook is what nudges Claude to consult `skill-router` first — **without it, skills
+> won't auto-route** (the whole point of the library) and the baseline isn't re-asserted
+> after `/compact`. If you deliberately want no hook, pass `--no-hook`; auto-routing stays
+> off until a hook is wired. The **per-role plugin** path above needs no hook — it's
+> self-contained.
+
 Or from a clone: `node install.mjs --global`.
 
 > **Prerequisite:** Node.js ≥ 18 (already present wherever Claude Code runs).
@@ -97,7 +114,9 @@ for every method × surface, and **[ROLES.md](docs/ROLES.md)** for the activatio
 On any non-trivial task, Claude consults **`skill-router`** first; it reads the full
 catalog and invokes the matching skill(s) by name, re-routing as the work changes phase.
 The default SessionStart hook nudges Claude to do this automatically; you can also route
-explicitly ("use the security-audit skill") or switch the promoted set with `/role`.
+explicitly ("use the security-audit skill") or switch the promoted set with `/role`. Don't
+want a particular skill routed at all? `npx swe-workflow-skills disable <skill>` opts it out
+durably — see [disable a skill from routing](docs/ROLES.md#advanced-disable-a-skill-from-routing).
 
 **A routed chain, by phase** — e.g. *"add OAuth login"*:
 
@@ -144,6 +163,7 @@ review) live in the `skill-router` skill and **[ROLES.md](docs/ROLES.md)**.
 - **[EVALS.md](docs/EVALS.md)** — how the skills are tested (RED/GREEN, pressure tests, CI gate).
 - **[AUTHORING.md](docs/AUTHORING.md)** — write or modify a skill (descriptions, budget, progressive disclosure, evals).
 - **[RELEASING.md](docs/RELEASING.md)** — versioning policy and how to cut a release. Changes are tracked in **[CHANGELOG.md](CHANGELOG.md)**.
+- **[SECURITY.md](SECURITY.md)** — the security model: trust boundaries, what runs automatically, supply-chain guarantees, and how to report a vulnerability.
 
 ## Evaluation
 

package/VERSION

@@ -1 +1 @@
-0.3.0
+0.5.0

package/bin/cli.mjs

@@ -5,6 +5,9 @@
 //
 //   npx swe-workflow-skills install [--global|--dir DIR|--role R|--no-hook|...]
 //   npx swe-workflow-skills uninstall [--global|--dir DIR|--dry-run|--yes]
+//   npx swe-workflow-skills disable <skill> [--off] [--global | --dir DIR]
+//   npx swe-workflow-skills enable  <skill> [--global | --dir DIR]
+//   npx swe-workflow-skills list-disabled   [--global | --dir DIR]
 
 import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
@@ -17,21 +20,34 @@ const [sub, ...rest] = process.argv.slice(2);
 const HELP = `swe-workflow-skills <command> [options]
 
 Commands:
-  install      Install skills into a Claude config dir (passes flags to install.mjs)
-  uninstall    Remove the library (passes flags to uninstall.mjs)
+  install         Install skills into a Claude config dir (passes flags to install.mjs)
+  uninstall       Remove the library (passes flags to uninstall.mjs)
+  disable <skill> Opt a skill out of routing/auto-trigger (advanced; --off to fully hide)
+  enable  <skill> Re-enable a previously disabled skill
+  list-disabled   List skills currently disabled
 
 Examples:
   npx swe-workflow-skills install --global
   npx swe-workflow-skills install --role pm
   npx swe-workflow-skills uninstall --global --dry-run
+  npx swe-workflow-skills disable data-modeling --global
+  npx swe-workflow-skills enable data-modeling --global
 
 Run a command with --help to see its full option list.`;
 
+// disable/enable/list-disabled all run through disable.mjs; map the CLI verb to
+// the action positional it expects (list-disabled -> list).
+const DISABLE_ACTIONS = { disable: "disable", enable: "enable", "list-disabled": "list" };
+
 if (sub === "install" || sub === "uninstall") {
   const script = join(ROOT, sub === "install" ? "install.mjs" : "uninstall.mjs");
   // stdio inherited so install output and uninstall's confirm prompt pass through.
   const res = spawnSync(process.execPath, [script, ...rest], { stdio: "inherit" });
   process.exit(res.status ?? 1);
+} else if (sub in DISABLE_ACTIONS) {
+  const script = join(ROOT, "disable.mjs");
+  const res = spawnSync(process.execPath, [script, DISABLE_ACTIONS[sub], ...rest], { stdio: "inherit" });
+  process.exit(res.status ?? 1);
 } else if (sub === "-v" || sub === "--version" || sub === "version") {
   process.stdout.write(readFileSync(join(ROOT, "VERSION"), "utf-8"));
   process.exit(0);

package/commands/role.md

@@ -8,39 +8,61 @@ disable-model-invocation: true
 
 The user is managing the active swe-workflow skill role. The requested role argument is: `$ARGUMENTS`
 
-**Validate the argument before running anything.** It must be empty or match
-`^[a-z0-9_-]{1,32}$` (role keys are short kebab-case names). If it does not match —
-any spaces, quotes, `$`, backticks, slashes, or other characters — do NOT run the
-script below with it: reply that the role name is invalid and show the available
-roles by running only `node "@@RESOLVE@@" roles` (with `ROLES_JSON="@@ROLES@@"`
-exported).
-
-If the argument is valid, run this script exactly once via Bash, replacing
-`__ROLE__` with the validated argument (or with nothing when no argument was
-given), then report the result to the user concisely (the new active role, and
-that the change hot-reloads so it applies to the next prompt):
+**Validate the argument before running anything — this is the security-critical
+step.** It must be empty or match `^[a-z0-9_-]{1,32}$` (role keys are short
+kebab-case names). If it contains ANYTHING else — a space, quote, `$`, backtick,
+slash, semicolon, or any other character — the argument is invalid: do NOT run any
+Bash command that contains the argument in any form (not in a variable, not as an
+argument, not anywhere). Instead reply that the role name is invalid and list the
+available roles by running only the fixed command `node "@@RESOLVE@@" roles` with
+`ROLES_JSON="@@ROLES@@"` exported — that command does not reference the argument at
+all.
+
+If the argument is valid (or empty), run the setup block once, then run the ONE
+branch below that matches, substituting the validated role for `__ROLE__` **only
+where shown** (always inside double quotes as the final argument of a `node`
+call — never assigned to a shell variable). Then report the result concisely (the
+new active role, and that the change hot-reloads so it applies to the next
+prompt):
 
 ```bash
-ROLE="__ROLE__"
-case "$ROLE" in *[!a-zA-Z0-9_-]*) echo "invalid role name" >&2; exit 1;; esac
+# --- setup (no argument appears here) ---
 RESOLVE="@@RESOLVE@@"; SKILLS="@@SKILLS@@"; SETTINGS="@@SETTINGS@@"
 ROLES="@@ROLES@@"; ACTIVE="@@ACTIVE_ROLE@@"
 export ROLES_JSON="$ROLES"
-if [ -z "$ROLE" ]; then
-  echo "Active role: $(cat "$ACTIVE" 2>/dev/null || echo 'baseline (none)')"
-  echo "Available roles:"; node "$RESOLVE" roles
-elif [ "$ROLE" = "all" ] || [ "$ROLE" = "none" ]; then
-  node "$RESOLVE" apply "$SETTINGS" "$SKILLS" none && rm -f "$ACTIVE"
-  echo "Reset to baseline — only the pinned skills auto-trigger now."
-elif node "$RESOLVE" label "$ROLE" >/dev/null 2>&1; then
-  node "$RESOLVE" apply "$SETTINGS" "$SKILLS" "$ROLE" && printf '%s\n' "$ROLE" > "$ACTIVE"
-  echo "Active role set to '$ROLE' — its skills now auto-trigger."
+```
+
+Empty argument (no role given) — show current + available, no substitution:
+```bash
+echo "Active role: $(cat "$ACTIVE" 2>/dev/null || echo 'baseline (none)')"
+echo "Available roles:"; node "$RESOLVE" roles
+```
+
+Argument is `all` or `none` — reset to baseline:
+```bash
+node "$RESOLVE" apply "$SETTINGS" "$SKILLS" none && rm -f "$ACTIVE"
+echo "Reset to baseline — only the pinned skills auto-trigger now."
+```
+
+Any other validated role — apply it. `resolve.mjs` rejects an unknown role with a
+non-zero exit, so the `&&` short-circuits and the marker is only written for a role
+that actually resolved:
+```bash
+if node "$RESOLVE" apply "$SETTINGS" "$SKILLS" "__ROLE__" && printf '%s\n' "__ROLE__" > "$ACTIVE"; then
+  echo "Active role set — its skills now auto-trigger."
 else
-  echo "Unknown role '$ROLE'. Available roles:"; node "$RESOLVE" roles
+  echo "Unknown role. Available roles:"; node "$RESOLVE" roles
 fi
 ```
 
 Notes:
 - `skillOverrides` and the skill listing hot-reload when `settings.local.json` changes, so the new auto-trigger set takes effect on the next prompt without a restart.
 - This command is for the full (all-skills) CLI install. Hard-subset (`--role`) installs and the per-role marketplace plugins don't need it.
-- Security: the script deliberately never embeds `$ARGUMENTS` directly (slash-command templates interpolate it as text, so a crafted argument would execute in the shell). The value reaches the script only via the validated `__ROLE__` transfer above; the in-script `case` guard is defense-in-depth.
+- Security: `$ARGUMENTS` is never embedded directly (slash-command templates
+  interpolate it as text, so a crafted argument would execute in the shell). The
+  **primary control is the model-side regex validation above** — do it before
+  emitting any Bash. As a deterministic backstop, the validated value reaches the
+  shell only as the final quoted argv of a `node "$RESOLVE"` call, where
+  `resolve.mjs` (`roleOrDie`) rejects any string that is not a known role before
+  it is used — the value is never placed in a bare `ROLE=...` assignment. See
+  `SECURITY.md` for the residual (quote-escape) risk and why it is accepted.

package/disable.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+// Disable / enable a single skill from routing and auto-trigger, durably.
+//
+// The library installs a name-only baseline: skills don't auto-trigger, they're
+// invoked by the skill-router. Disabling goes one step further — it hides a skill
+// from the router too, for users who don't want the whole corpus routed. This is
+// an ADVANCED opt-out of the routed SWE-methodology; most people don't need it.
+//
+// Why a command (not a manual settings edit): the SessionStart hook re-writes
+// every installed skill's skillOverrides entry each session, so a hand edit is
+// reverted. This records the choice in a `.disabled-skills` marker beside the
+// skills, which the hook folds into the baseline every time — so it persists.
+//
+// Runs on Linux, macOS, and Windows using only Node.
+//
+//   node disable.mjs disable <skill>          # -> user-invocable-only (default)
+//   node disable.mjs disable <skill> --off    # -> off (fully hidden)
+//   node disable.mjs enable  <skill>          # re-enable (back to the baseline)
+//   node disable.mjs list                     # show disabled skills
+//   node disable.mjs disable <skill> --global # target the user config dir
+
+import { existsSync, statSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import {
+  loadRoles,
+  applyBaseline,
+  installedSkills,
+  readDisabled,
+  writeDisabled,
+  DEFAULT_DISABLE_STATE,
+} from "./scripts/resolve.mjs";
+
+// Exit cleanly when stdout is closed early (e.g. piped to `head`/`grep`) instead
+// of throwing an EPIPE stack trace.
+process.stdout.on("error", (e) => {
+  if (e && e.code === "EPIPE") process.exit(0);
+  throw e;
+});
+
+const REPO_ROOT = dirname(fileURLToPath(import.meta.url));
+
+const USAGE = `Usage: disable.mjs <disable|enable|list> [skill] [options]
+
+Disable or re-enable a skill from routing/auto-trigger (advanced opt-out).
+
+Actions:
+  disable <skill>   Hide <skill> from the router. Default state: user-invocable-only
+                    (you can still run it manually as /<skill>). Add --off to hide
+                    it entirely (not even user-invocable).
+  enable  <skill>   Re-enable <skill> (return it to the name-only baseline).
+  list              List currently disabled skills.
+
+Options:
+  --off          With 'disable': set state to "off" instead of user-invocable-only
+  -g, --global   Target the user config dir: $CLAUDE_CONFIG_DIR if set, else
+                 ~/.claude/ (default without this flag: ./.claude/)
+  -d, --dir DIR  Target a custom Claude config directory DIR
+  -h, --help     Show this help`;
+
+function isDir(p) {
+  return existsSync(p) && statSync(p).isDirectory();
+}
+function fatal(msg) {
+  process.stderr.write(`Error: ${msg}\n`);
+  process.exit(1);
+}
+function log(msg) {
+  process.stdout.write(msg + "\n");
+}
+function expandTilde(p) {
+  if (p === "~" || p.startsWith("~/") || p.startsWith("~\\")) return homedir() + p.slice(1);
+  return p;
+}
+
+// ---- arg parsing -----------------------------------------------------------
+
+let global = false;
+let off = false;
+let configDir = "";
+const positional = [];
+
+const argv = process.argv.slice(2);
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === "-g" || a === "--global") global = true;
+  else if (a === "--off") off = true;
+  else if (a === "-d" || a === "--dir") {
+    configDir = argv[++i];
+    if (configDir === undefined) fatal("--dir requires a path");
+  } else if (a.startsWith("--dir=")) configDir = a.slice("--dir=".length);
+  else if (a === "-h" || a === "--help") {
+    log(USAGE);
+    process.exit(0);
+  } else if (a.startsWith("-")) {
+    process.stderr.write(`Unknown option: ${a}\n${USAGE}\n`);
+    process.exit(1);
+  } else positional.push(a);
+}
+
+const action = positional[0];
+const skill = positional[1];
+if (!action || !["disable", "enable", "list"].includes(action)) {
+  process.stderr.write(`${USAGE}\n`);
+  process.exit(1);
+}
+if ((action === "disable" || action === "enable") && !skill) {
+  fatal(`'${action}' requires a <skill> name`);
+}
+// Reject path-like / malformed names before any filesystem use.
+if (skill && !/^[a-z0-9][a-z0-9-]*$/.test(skill)) {
+  fatal(`invalid skill name '${skill}' (expected lowercase letters, digits, hyphens)`);
+}
+
+let claudeDir;
+if (configDir) {
+  if (global) fatal("--dir and --global are mutually exclusive");
+  claudeDir = resolve(expandTilde(configDir));
+} else if (global) {
+  claudeDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+} else {
+  claudeDir = join(process.cwd(), ".claude");
+}
+const dest = join(claudeDir, "skills");
+const settingsLocal = join(claudeDir, "settings.local.json");
+
+if (!isDir(dest)) fatal(`no skills found at ${dest} (is the library installed there? try --global or --dir)`);
+
+// Roles data: prefer the installed marker beside the skills, else the repo copy.
+function loadRolesData() {
+  for (const p of [join(dest, ".roles.json"), join(REPO_ROOT, "roles.json")]) {
+    if (existsSync(p)) return loadRoles(p);
+  }
+  return null;
+}
+
+// Active role, so re-applying the baseline preserves the user's promoted set.
+function activeRole(data) {
+  const f = join(dest, ".active-role");
+  if (!existsSync(f)) return null;
+  try {
+    const r = readFileSync(f, "utf-8").replace(/\s+/g, "");
+    return r && data && data.roles && r in data.roles ? r : null;
+  } catch {
+    return null;
+  }
+}
+
+// Re-assert the baseline now so the change hot-reloads in the current session
+// (like /role), instead of waiting for the next session boundary.
+function reapply() {
+  const data = loadRolesData();
+  if (!data) return; // no roles data (partial/plugin install): marker still written
+  try {
+    applyBaseline(data, settingsLocal, dest, activeRole(data));
+  } catch (e) {
+    process.stderr.write(`Warning: wrote the marker but could not re-apply the baseline (${e.message}).\n`);
+    process.stderr.write("It will take effect at the next session start.\n");
+  }
+}
+
+// ---- actions ---------------------------------------------------------------
+
+const disabled = readDisabled(dest);
+
+if (action === "list") {
+  if (disabled.size === 0) {
+    log("No skills are disabled.");
+  } else {
+    log("Disabled skills:");
+    for (const name of [...disabled.keys()].sort()) log(`  ${name}  (${disabled.get(name)})`);
+  }
+  process.exit(0);
+}
+
+const data = loadRolesData();
+const installed = new Set(installedSkills(dest));
+
+if (action === "disable") {
+  if (!installed.has(skill)) fatal(`unknown skill '${skill}' — not installed at ${dest}`);
+  const state = off ? "off" : DEFAULT_DISABLE_STATE;
+  disabled.set(skill, state);
+  writeDisabled(dest, disabled);
+  reapply();
+  log(`Disabled '${skill}' -> ${state}.`);
+  if (state === DEFAULT_DISABLE_STATE) {
+    log(`The router will no longer invoke it; you can still run it manually as /${skill}.`);
+  } else {
+    log("It is now fully hidden (not routable and not user-invocable).");
+  }
+  if (data && Array.isArray(data.pinned) && data.pinned.includes(skill)) {
+    log(`Note: '${skill}' is a pinned safety skill — disabling it opts out of that guardrail.`);
+  }
+  log("This persists across sessions (the hook re-asserts it). Re-enable with:");
+  log(`  node disable.mjs enable ${skill}${global ? " --global" : ""}`);
+} else {
+  // enable
+  if (!disabled.has(skill)) {
+    log(`'${skill}' is not disabled — nothing to do.`);
+    process.exit(0);
+  }
+  disabled.delete(skill);
+  writeDisabled(dest, disabled);
+  reapply();
+  log(`Enabled '${skill}' — back to the name-only baseline (routable again).`);
+}

package/install.mjs

@@ -52,6 +52,9 @@ Options:
   -p, --prune      After installing the selected set, remove previously-installed
                    library skills that are NOT in the new selection (never touches
                    your own custom skills). Use to narrow a prior all-skills install.
+  -f, --force      Overwrite a same-named skill directory that this installer did
+                   not create (by default such a collision is skipped, so your own
+                   custom skill with a library name is never clobbered).
   -k, --hook       (default) Install the SessionStart hook that re-asserts the
                    name-only baseline each session + injects the router nudge
                    (prints the settings snippet; never edits settings)
@@ -106,6 +109,7 @@ function toPosix(p) {
 let global = false;
 let hook = true;
 let prune = false;
+let force = false;
 let configDir = "";
 let role = "";
 const selected = [];
@@ -125,6 +129,7 @@ for (let i = 0; i < argv.length; i++) {
     if (role === undefined) fatal("--role requires a role name");
   } else if (a.startsWith("--role=")) role = a.slice("--role=".length);
   else if (a === "-p" || a === "--prune") prune = true;
+  else if (a === "-f" || a === "--force") force = true;
   else if (a === "-k" || a === "--hook") hook = true;
   else if (a === "--no-hook") hook = false;
   else if (a === "-l" || a === "--list") {
@@ -192,9 +197,46 @@ if (skillSet.length === 0) {
   skillSet = role ? resolvedSkills(rolesData, role) : listSkillDirs();
 }
 
+// ---- provenance manifest ---------------------------------------------------
+// Records which skill directories THIS installer created, so uninstall/--prune
+// only ever remove our own skills and a re-install never clobbers a user's custom
+// skill that happens to share a library name. See docs SECURITY.md (LOW-003).
+const MANIFEST = join(dest, ".swe-workflow-manifest.json");
+
+function readManifestSkills() {
+  if (existsSync(MANIFEST)) {
+    try {
+      const m = JSON.parse(readFileSync(MANIFEST, "utf-8"));
+      if (Array.isArray(m.skills)) return new Set(m.skills);
+    } catch {
+      /* unreadable manifest -> treat as absent */
+    }
+  }
+  return null; // null = no manifest present
+}
+
+const priorManifest = readManifestSkills();
+// A prior swe-workflow install (any version) leaves these machinery markers even
+// before manifests existed. If neither a manifest nor a marker is present, the dest
+// is not one we've installed into, so a same-named dir there must be the user's.
+const priorInstall =
+  priorManifest !== null ||
+  existsSync(join(dest, ".roles.json")) ||
+  existsSync(join(claudeDir, "hooks", "resolve.mjs"));
+
+// Do we own the skill dir currently at dest? Manifest is authoritative when present;
+// otherwise fall back to "is this dest a prior swe install at all?" so pre-manifest
+// upgrades still overwrite our own skills rather than skipping them.
+function installerOwns(skill) {
+  if (priorManifest !== null) return priorManifest.has(skill);
+  return priorInstall;
+}
+
 // ---- copy skills -----------------------------------------------------------
 
 let errors = 0;
+const installedNow = [];
+const skippedCollisions = [];
 for (const skill of skillSet) {
   const src = join(SKILLS_DIR, skill);
   if (!isDir(src)) {
@@ -202,24 +244,59 @@ for (const skill of skillSet) {
     errors++;
     continue;
   }
+  const destPath = join(dest, skill);
+  // Never clobber a same-named directory we didn't create unless --force.
+  if (isDir(destPath) && !force && !installerOwns(skill)) {
+    warn(
+      `skipping '${skill}': a skill of that name already exists and was not installed ` +
+        `by swe-workflow-skills. Use --force to overwrite it.`,
+    );
+    skippedCollisions.push(skill);
+    continue;
+  }
   // Clean copy: drop any prior version first so files removed upstream don't linger.
-  rmSync(join(dest, skill), { recursive: true, force: true });
-  cpSync(src, join(dest, skill), { recursive: true });
-  log(`Installed: ${skill} -> ${join(dest, skill)}`);
+  rmSync(destPath, { recursive: true, force: true });
+  cpSync(src, destPath, { recursive: true });
+  installedNow.push(skill);
+  log(`Installed: ${skill} -> ${destPath}`);
 }
 
 // --prune: narrow a prior install to the current selection. Only ever removes skills
-// that exist in our source tree (so the user's own custom skills are never touched).
+// that exist in our source tree AND that this installer created (so the user's own
+// custom skills — including any that share a library name — are never touched).
+const pruned = new Set();
 if (prune) {
   const keep = new Set(skillSet);
   for (const s of listSkillDirs()) {
-    if (!keep.has(s) && isDir(join(dest, s))) {
+    if (!keep.has(s) && isDir(join(dest, s)) && installerOwns(s)) {
       rmSync(join(dest, s), { recursive: true, force: true });
+      pruned.add(s);
       log(`Pruned: ${s} (not in selection)`);
     }
   }
 }
 
+// Rewrite the provenance manifest: every library skill we own that is still present.
+// = (what we owned before) ∪ (installed this run) − (pruned this run), intersected
+// with library skill dirs actually on disk. Skipped collisions never enter it.
+const libNames = new Set(listSkillDirs());
+const ownedSkills = new Set([...(priorManifest || []), ...installedNow]);
+const manifestSkills = [...ownedSkills]
+  .filter((s) => !pruned.has(s) && libNames.has(s) && isDir(join(dest, s)))
+  .sort();
+if (installedNow.length > 0 || priorManifest !== null || prune) {
+  let manifestVersion = "";
+  try {
+    manifestVersion = readFileSync(join(REPO_ROOT, "VERSION"), "utf-8").trim();
+  } catch {
+    /* VERSION is optional metadata in the manifest */
+  }
+  writeFileSync(
+    MANIFEST,
+    JSON.stringify({ installer: "swe-workflow-skills", version: manifestVersion, skills: manifestSkills }, null, 2) + "\n",
+  );
+}
+
 // ---- orchestrator machinery (only when skill-router is in the set) ---------
 
 const hasRouter = skillSet.includes("skill-router");
@@ -292,17 +369,34 @@ if (hook) {
     hookPath = join(hookDestDir, "session-start.mjs");
     log(`Installed hook script -> ${hookPath}`);
     log("");
-    log("The name-only baseline is already applied. To have it re-asserted every");
-    log("session (and the router nudge injected), merge this into");
-    log(`${join(claudeDir, "settings.json")} (the installer does NOT edit settings for you):`);
+    log("========================================================================");
+    log("REQUIRED NEXT STEP — wire the router hook");
+    log("========================================================================");
+    log("Skills are installed and the name-only baseline is applied, so nothing");
+    log("will crop. But WITHOUT this step Claude won't be nudged to consult");
+    log("skill-router first, so skills won't auto-route — you lose the whole point");
+    log("of the library. The hook also re-asserts the baseline after /compact.");
+    log("");
+    log(`Merge this into ${join(claudeDir, "settings.json")}`);
+    log("(for your safety the installer does NOT edit settings.json for you):");
     log("");
     log(hookSnippet(hookPath));
     log("");
-    log("Start a new session and run /doctor to confirm the hook is registered.");
-    log("(Prefer no hook? Re-run with --no-hook; the baseline still applies.)");
+    log("Then start a new session and run /doctor to confirm the hook is registered.");
+    log("(Deliberately not using the hook? Re-run with --no-hook; the baseline still");
+    log(" applies, but auto-routing stays off until you wire a hook.)");
   }
 }
 
+// Per-skill collision warnings scroll away during a full install; restate them once
+// at the end so an unowned same-named skill that was left in place is not missed.
+if (skippedCollisions.length > 0) {
+  warn(
+    `left ${skippedCollisions.length} existing skill(s) untouched (not installed by ` +
+      `swe-workflow-skills): ${skippedCollisions.join(", ")}. Re-run with --force to overwrite.`,
+  );
+}
+
 if (errors !== 0) process.exit(1);
 
 function copyIfExists(src, destPath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swe-workflow-skills",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "A curated library of Claude Code Agent Skills covering the full software lifecycle, with orchestrator-routed activation that scales past the skill-listing budget.",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "bin/cli.mjs",
     "install.mjs",
     "uninstall.mjs",
+    "disable.mjs",
     "scripts/resolve.mjs",
     "hooks/session-start.mjs",
     "commands/role.md",

package/scripts/resolve.mjs

@@ -28,7 +28,7 @@
 //
 // roles.json is read from $ROLES_JSON if set, else ../roles.json relative to this file.
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, readdirSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, readdirSync, rmSync } from "node:fs";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -88,6 +88,73 @@ export function installedSkills(skillsDir) {
     .sort();
 }
 
+// ---- disabled-skills marker ------------------------------------------------
+//
+// Lets a user opt a skill OUT of routing/auto-trigger and have it *survive* the
+// SessionStart hook. A plain settings.local.json edit can't: applyBaseline owns
+// every installed skill's entry and rewrites it each session. Instead the choice
+// lives in a `.disabled-skills` marker beside the skills (like `.active-role`),
+// which applyBaseline folds in on every write — so the hook re-asserts the
+// disable rather than reverting it.
+//
+// Format: one skill per line, optional state after whitespace; `#` comments and
+// blank lines ignored. Valid states are the two that hide a skill from the model:
+//   data-modeling                 -> user-invocable-only (default; human /name still works)
+//   data-modeling off             -> off (fully hidden)
+
+export const DISABLE_STATES = new Set(["user-invocable-only", "off"]);
+export const DEFAULT_DISABLE_STATE = "user-invocable-only";
+
+export function disabledMarkerPath(skillsDir) {
+  return join(skillsDir, ".disabled-skills");
+}
+
+// Parse the marker into Map<skill, state>. Best-effort: a missing or unreadable
+// file yields an empty map (never throws — the hook must not fail on it).
+export function readDisabled(skillsDir) {
+  const path = disabledMarkerPath(skillsDir);
+  const map = new Map();
+  if (!(existsSync(path) && statSync(path).isFile())) return map;
+  let text = "";
+  try {
+    text = readFileSync(path, "utf-8");
+  } catch {
+    return map;
+  }
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const [name, state] = line.split(/\s+/);
+    if (!name) continue;
+    map.set(name, DISABLE_STATES.has(state) ? state : DEFAULT_DISABLE_STATE);
+  }
+  return map;
+}
+
+// Same, but restricted to skills actually installed here (stale names dropped).
+export function loadDisabled(skillsDir) {
+  const installed = new Set(installedSkills(skillsDir));
+  const map = new Map();
+  for (const [name, state] of readDisabled(skillsDir)) {
+    if (installed.has(name)) map.set(name, state);
+  }
+  return map;
+}
+
+// Persist Map<skill, state>, sorted. Removes the marker entirely when empty so an
+// enabled-everything state leaves no file behind (mirrors pruneSettings dropping
+// an empty skillOverrides).
+export function writeDisabled(skillsDir, map) {
+  const path = disabledMarkerPath(skillsDir);
+  const names = [...map.keys()].sort();
+  if (names.length === 0) {
+    if (existsSync(path)) rmSync(path);
+    return;
+  }
+  const lines = names.map((n) => (map.get(n) === DEFAULT_DISABLE_STATE ? n : `${n} ${map.get(n)}`));
+  writeFileSync(path, lines.join("\n") + "\n");
+}
+
 // ---- settings I/O ----------------------------------------------------------
 
 // Recursively sort object keys so output is deterministic (mirrors Python's
@@ -143,11 +210,19 @@ export function applyBaseline(data, settingsPath, skillsDir, role) {
   const merged = {};
   for (const [k, v] of Object.entries(existing)) if (!installedSet.has(k)) merged[k] = v;
   Object.assign(merged, desired);
+
+  // User-disabled skills override the baseline: an explicit opt-out wins over
+  // name-only AND over a pinned/role-promoted "on" (a pinned skill the user
+  // disabled becomes user-invocable-only, not on). Read from the marker each
+  // call so the hook re-asserts the disable instead of reverting it.
+  const disabled = loadDisabled(skillsDir);
+  for (const [s, state] of disabled) merged[s] = state;
+
   settings.skillOverrides = merged;
 
   writeSettings(settingsPath, settings);
   const nameOnly = Object.keys(desired).length;
-  return { nameOnly, on: installed.length - nameOnly, role };
+  return { nameOnly, on: installed.length - nameOnly, role, disabled: disabled.size };
 }
 
 // Remove the given skills from a settings file's skillOverrides. Returns removed count.

package/uninstall.mjs

@@ -12,7 +12,7 @@
 //   node uninstall.mjs --global         # remove from the user config dir
 //   node uninstall.mjs --dir DIR --dry-run
 
-import { existsSync, statSync, readdirSync, rmSync, rmdirSync } from "node:fs";
+import { existsSync, statSync, readdirSync, readFileSync, rmSync, rmdirSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
@@ -96,16 +96,39 @@ if (!isDir(claudeDir)) {
 
 const settingsLocal = join(claudeDir, "settings.local.json");
 
-// Build the removal list: only library skills present on disk, plus the machinery.
-const libSkills = readdirSync(SKILLS_DIR)
-  .filter((s) => isDir(join(SKILLS_DIR, s)) && isDir(join(dest, s)))
-  .sort();
+// Build the removal list: only library skills THIS installer created, plus the
+// machinery. The provenance manifest is authoritative when present, so a user's own
+// custom skill that shares a library name is never removed. Pre-manifest installs
+// have no manifest — fall back to matching source-tree skill names (the historical
+// behavior) so they can still be uninstalled.
+const manifestPath = join(dest, ".swe-workflow-manifest.json");
+let manifestSkills = null;
+if (existsSync(manifestPath)) {
+  try {
+    const m = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    if (Array.isArray(m.skills)) manifestSkills = m.skills;
+  } catch {
+    /* unreadable manifest -> fall back to name-match below */
+  }
+}
+
+let libSkills;
+if (manifestSkills !== null) {
+  const srcSkills = new Set(readdirSync(SKILLS_DIR).filter((s) => isDir(join(SKILLS_DIR, s))));
+  libSkills = manifestSkills.filter((s) => srcSkills.has(s) && isDir(join(dest, s))).sort();
+} else {
+  libSkills = readdirSync(SKILLS_DIR)
+    .filter((s) => isDir(join(SKILLS_DIR, s)) && isDir(join(dest, s)))
+    .sort();
+}
 
 const targets = [...libSkills.map((s) => join(dest, s))];
 for (const f of [
   join(dest, ".roles.json"),
   join(dest, ".catalog.json"),
   join(dest, ".active-role"),
+  join(dest, ".disabled-skills"),
+  join(dest, ".swe-workflow-manifest.json"),
   join(claudeDir, "hooks", "resolve.mjs"),
   join(claudeDir, "hooks", "session-start.mjs"),
   join(claudeDir, "commands", "role.md"),