# Turn a capability off (and keep it off) This guide shows you how to switch a MSD capability off so it stops taking part in the loop — and stays off — and how to switch off a single feature of a capability without disabling the whole thing. MSD resolves one capability state from three places: whether the capability is installed, whether it is surfaced, and whether each of its hooks is gated in config. "Off" means off across all three. For why the model works this way, see [Develop a Capability for MSD 1.6.0+](develop-a-capability.md). > **First-party vs. installed: pick the right off-switch.** The path depends on where the capability came from. > > - A **first-party** capability — one that ships with MSD (for example `ui`, `code-review`, `research`) — is turned off with `msd capability disable ` or gated with `msd capability set --gate …`. These verbs validate `` against the built-in capability registry. > - An **installed third-party overlay** — one you added with `msd capability install …` — is **not** in that build-time registry, so `disable`/`enable`/`set` reject it with `unknown capability: ""`. The off-switch for an installed overlay is `msd capability remove --scope `. > > The rest of this guide covers first-party capabilities. For installed overlays, jump to [Turn off an installed third-party capability](#turn-off-an-installed-third-party-capability). The reliable, fully general way to change first-party capability state is the `capability` command. The `/msd-surface` and `/msd-settings` slash commands are convenient interactive front-ends, but they operate on **skill clusters**, not arbitrary capabilities — so reach for the CLI when you want a precise, scriptable, per-capability switch. --- ## Turn a whole first-party capability off Disable the capability by id: ```bash msd capability disable ``` For example, to stop the UI capability: ```bash msd capability disable ui ``` This unsurfaces the capability's skills and makes all of its hooks inactive. It is reversible and needs no reinstall — the bundle stays on disk and your hook gates are preserved. `msd capability disable ` is exactly `msd capability set --off`; re-enable with `msd capability enable ` (i.e. `--on`). `disable`/`enable`/`set` only accept ids the built-in registry knows about. Run them against an installed third-party overlay and you get `unknown capability: ""` — see [Turn off an installed third-party capability](#turn-off-an-installed-third-party-capability) for that case. Check the result: ```bash msd capability state --raw ``` The capability now reports `enabled: false` and every hook `active: false`. --- ## Turn off one feature of a capability To keep a capability on but switch off a single hook, gate that hook instead of disabling the capability. A **gate** is a dotted config key declared in the capability's `config` slice whose boolean value controls whether one of its hooks fires. Set it to `false`: ```bash msd capability set code-review --gate workflow.code_review=false ``` The capability stays enabled; only that hook stops firing. `--gate` is repeatable, so you can set several gates in one call. See the [`set` reference](../reference/msd-capability-command.md#set) for the full contract. --- ## Capabilities that own no skills Some capabilities (for example, `research`) contribute only hooks and agents — they have no skills to unsurface, so disabling them via the surface has no effect. Switch these off by gating their hooks instead: ```bash msd capability set research --gate workflow.research=false ``` If you gate every hook of a capability off while it is still surfaced, `msd capability state` flags it as surfaced-but-inactive — a sign you probably meant to disable the capability itself. --- ## Turn off an installed third-party capability A capability you added with `msd capability install …` is an **installed overlay**, not a first-party capability. It is not present in the build-time registry that `disable`/`enable`/`set` validate against, so those verbs reject it: ```bash msd capability disable my-overlay # error: unknown capability: "my-overlay" ``` **Remove it.** This is the deactivation path for an installed overlay — it strips the overlay's files and edits for the chosen scope: ```bash msd capability remove my-overlay --scope global # default scope is global msd capability remove my-overlay --scope project # for a project-scoped install ``` `--scope` defaults to `global`, so pass `--scope project` for a project install. Add `--purge-data` to also delete the overlay's persisted data. If the id is not installed in the chosen scope you get `capability "my-overlay" is not installed in scope`. (Trying to `remove` a first-party id instead reports that it cannot be removed here — use the product uninstaller, `msd --uninstall`.) > The `/msd-surface` clusters described below are derived from the **built-in** capability registry, so they cover first-party skill-owning capabilities. For an installed overlay, `remove` is the off-switch. See [Remove a capability](remove-a-capability.md) for the full removal flow and [`msd capability remove`](../reference/msd-capability-command.md#remove) for every flag and output field. --- ## The interactive paths (`/msd-surface` and `/msd-settings`) The slash commands are the interactive equivalents, useful when you are working inside an agent session rather than scripting: - **`/msd-surface disable `** toggles a whole skill **cluster** on or off and re-stages the surface. Its argument is validated against the fixed set of cluster names — one of `core_loop`, `audit_review`, `milestone`, `research_ideate`, `workspace_state`, `docs`, `ui`, `ai_eval`, `ns_meta`, `utility` (the command rejects anything else and lists these). A few of these names coincide with first-party skill-owning capability ids (for example `ui`), so `/msd-surface disable ui` works — but the command does **not** accept an arbitrary capability id, including an installed overlay's id. To switch off a specific capability by id, use the CLI (`msd capability disable ` for first-party, `msd capability remove ` for an installed overlay). Reverse a cluster with `/msd-surface enable `. - **`/msd-settings`** is the interactive prompt for MSD's workflow toggles (the `workflow.*` config keys that gate hooks). Use it to turn workflow features on or off conversationally; it writes the same config keys that `msd capability set … --gate` writes. For anything you want to be exact about — a specific capability id, a single named gate, or a step in a script or CI job — prefer the CLI. --- ## Scripting it To mutate capability state directly (in scripts or CI), call the command non-interactively. The first three verbs work on **first-party** ids; the last works on **installed overlays**: ```bash # Disable a whole first-party capability msd capability disable # equivalently: msd capability set --off # Re-enable msd capability enable # equivalently: msd capability set --on # Toggle one hook gate msd capability set --gate = # Deactivate an installed third-party overlay (disable/set would reject it) msd capability remove --scope ``` See the [`msd capability` command reference](../reference/msd-capability-command.md) for every subcommand, flag, and output shape. --- ## Related - [`msd capability` command reference](../reference/msd-capability-command.md) — `disable`, `enable`, `set`, and the rest of the family - [Develop a Capability for MSD 1.6.0+](develop-a-capability.md) - [Install a minimal MSD and add skills later](install-minimal-and-add-skills.md) - [docs index](../README.md)