skill-toggle — disable / enable skills

Caution

10+ plugins means dozens of skills flooding Claude’s context. When every skill competes for attention, Claude’s auto-selection misfires — wrong skill fires, irrelevant triggers pile up, noise grows with every install. Claude Code has no native per-skill disable (#47747, #22345).

Tip

One command silences a skill permanently. State is stored separately from the plugin cache — claude plugin update never resets it. For agents, see /brewtools:agent-toggle.

Quick reference

CommandAction
/brewtools:skill-toggle disable brewui:image-genHide a skill (renames SKILL.md → _SKILL.md)
/brewtools:skill-toggle enable brewui:image-genRestore a hidden skill
/brewtools:skill-toggle statusShow all disabled skills (merged global + project)
/brewtools:skill-toggle listList every installed skill with enabled/disabled state
/brewtools:skill-toggle reapplyRe-apply state after manual plugin cache changes
/brewtools:skill-toggle pruneRemove state entries for uninstalled plugins

Target format: plugin:name — e.g., brewui:image-gen, brewcode:convention. Name without a plugin prefix triggers a clarifying question before any mutation.

When to use

  • Clutter reduction — hide skills you never invoke to shrink Claude’s active context
  • Quieter auto-triggers — disable skills whose trigger phrases collide with your normal workflow
  • Project-specific overrides — scope a disable to the current repo without touching global state
  • Keep plugins installed — the plugin stays updated; only the individual skill is silenced

Examples

# Disable a skill globally (default scope)
/brewtools:skill-toggle disable brewui:image-gen

# Natural language also works
"disable brewui:image-gen"
"hide the image-gen skill"
# Disable for current project only
/brewtools:skill-toggle disable brewcode:convention --scope=project

# Enable a previously disabled skill
/brewtools:skill-toggle enable brewui:image-gen
# Check what's currently disabled
/brewtools:skill-toggle status

# See everything — enabled and disabled
/brewtools:skill-toggle list
# After a plugin update, re-apply all stored disables
/brewtools:skill-toggle reapply

Interactive mode

Tip

Run with no args — /brewtools:skill-toggle — and a guided flow walks you through it. Explicit commands still skip the flow.

Four phases:

  1. Pick an op

    One question, four options: status, disable, enable, or list. Pre-selected: disable.

  2. Scan the catalog

    All targets printed as one space-separated line of plugin:name tokens. Use Ctrl+F / Cmd+F to search your terminal scrollback — no pagination, no multi-line clutter.

  3. Resolve the target

    Exact plugin:name or unique shortname runs immediately — no confirmation. Fuzzy phrase (“the noisy image one”) or ambiguous name triggers a single confirmation.

  4. See the result

    Every run ends with a status table: what’s disabled right now, plus a count of enabled skills. No guessing what state you’re in.

Note

Explicit commands skip the flow. disable brewui:image-gen runs directly — no questions asked. The interactive path only triggers when your intent is ambiguous.

How it works

  1. Parse intent

    Extracts operation, scope, and target from your command or natural language. No plugin prefix? Asks which plugin owns the skill before touching anything.

  2. Validate target

    Checks the plugin cache for both SKILL.md (enabled) and _SKILL.md (disabled). Unknown plugin or missing skill — stops with an error, no state written.

  3. Mutate state

    Writes (disable) or removes (enable) the entry in the appropriate JSON state file — global or project scope. Atomic write via tmp + rename, no partial updates.

  4. Rename file

    disable: renames SKILL.md → _SKILL.md in the plugin cache. enable: renames back. Claude Code ignores files that don’t match SKILL.md.

  5. Notify

    Prints a result table: plugin, name, scope, action, result. Reminds you to run /reload-plugins.

State files

ScopePath
Global (default)~/.claude/plugins/data/brewtools-claude-brewcode/toggle-state.json
Project<cwd>/.claude/brewtools/toggle-state.json

Project scope overrides global per key — a project-level enable wins over a global disable for the same skill.

State schema

{
  "disabled": {
    "brewui:image-gen": {
      "kind": "skill",
      "plugin": "brewui",
      "name": "image-gen",
      "disabled_at": "2026-04-16T10:30:00.000Z",
      "last_applied_version": "3.5.2"
    }
  }
}

Surviving plugin updates

Note

The reapply-disables hook fires on every SessionStart. It detects when the plugin cache has a new version directory and re-applies all entries from the state file automatically. If a plugin was uninstalled or a skill file is missing, the hook reports the drift (plugin_not_installed, file_missing) in additionalContext — visible at the top of the new session.

Reload required

Warning

Run /reload-plugins or restart the session after any disable or enable. Claude Code reads skill definitions once at startup — in-flight changes take effect only after a reload.

🤖

Agent Toggle

Same disable/enable mechanic for agents instead of skills.

📄

Brewtools overview

All brewtools skills in one place.

🔗

GitHub source

Source code and shared toggle helpers.

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.