它到底是什么

/plugin 是 Claude Code 内置的插件管理命令，支持两种使用方式：交互面板（无参调用时弹出 TUI）和内联子命令（直接附加操作和参数）。

它同时承担两个职责：

1. 插件管理 — 安装、启用、禁用、卸载单个插件
2. Marketplace 管理 — 注册、更新、删除插件目录（marketplace）

插件（plugin）是一个自包含的目录，可向 Claude Code 贡献 skill、agent、hook、MCP server、LSP server、monitor 等组件。Marketplace 是插件的分发目录（catalog），不添加 marketplace 就无法从中安装插件。

官方 Anthropic marketplace（claude-plugins-official）在你启动 Claude Code 时自动可用。若 Claude Code 报告插件在任何 marketplace 中找不到，说明该 marketplace 缺失或过期：用 /plugin marketplace update claude-plugins-official 刷新；若此前从未添加过，则需手动执行 /plugin marketplace add anthropics/claude-plugins-official。

怎么触发 / 怎么使用

1. 交互面板（无参）

/plugin

打开一个带四个标签页的 TUI，用 Tab / Shift+Tab 切换：

2. 插件列表

/plugin list
/plugin list --enabled
/plugin list --disabled

不打开面板，直接在会话内输出插件列表；--enabled / --disabled 只显示对应状态的插件。

3. 安装插件

/plugin install <plugin-name>@<marketplace-name>

默认安装到 user scope（当前用户所有项目生效）。需要选择其他 scope 时，使用交互面板的 Discover 标签页按 Enter 进入详情，手动选择。

示例：

/plugin install github@claude-plugins-official
/plugin install commit-commands@claude-code-plugins

4. 启用 / 禁用 / 卸载

/plugin enable  <plugin-name>@<marketplace-name>
/plugin disable <plugin-name>@<marketplace-name>
/plugin uninstall <plugin-name>@<marketplace-name>

5. Marketplace 管理

# 添加 marketplace（支持多种来源格式）
/plugin marketplace add anthropics/claude-plugins-community   # GitHub owner/repo
/plugin marketplace add https://gitlab.com/org/plugins.git    # 任意 Git URL
/plugin marketplace add https://gitlab.com/org/plugins.git#v1.0.0  # 指定分支/tag
/plugin marketplace add ./my-marketplace                      # 本地目录
/plugin marketplace add https://example.com/marketplace.json  # 远程 JSON URL

# 列出已配置的 marketplace
/plugin marketplace list

# 刷新 marketplace 的插件列表
/plugin marketplace update <marketplace-name>

# 删除 marketplace
/plugin marketplace remove <marketplace-name>

快捷写法：marketplace 可缩写为 market；remove 可缩写为 rm。

6. 安装后应用更改

安装、启用或禁用插件后，需在会话内运行：

/reload-plugins

输出将显示已加载的插件、skill、agent、hook、MCP server、LSP server 数量。若某个插件提供了 MCP server 且未使用 tool search 延迟加载，/reload-plugins 会显示 cache 失效警告；加 --force 强制应用：

/reload-plugins --force

7. 指定 scope 的 CLI 用法（会话外）

claude plugin install formatter@your-org --scope project
claude plugin uninstall formatter@your-org --scope project
claude plugin details <plugin-name>

监控 / 控制 / 键位

以下键位在 /plugin 交互面板内生效：

保存 / 配置 / 集成

安装 scope

团队统一配置

在 .claude/settings.json 中添加 extraKnownMarketplaces，当团队成员信任该目录时 Claude Code 会提示他们安装：

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

自动更新控制

官方 Anthropic marketplace 默认启用自动更新；第三方和本地开发 marketplace 默认禁用。

marketplace 重命名自动跟随(v2.1.193):当某个 marketplace 在其 catalog 里给插件声明了 renames 映射(把旧插件名映射到新名)时,v2.1.193 起 Claude Code 会自动跟随该映射,把你 settings 中引用的旧插件名更新为新名,避免重命名后插件突然"找不到"而被禁用。来源:Claude Code changelog v2.1.193 "Improved plugin auto-rename: marketplace renames maps are now followed automatically, updating your settings to the new name"。

注意:这是插件/marketplace 层的自动重命名,与会话级 /rename 命令(给当前会话起名)无关,两者只是中文都叫"重命名"。

运行约束 / 限制

跟同类原语对比

下表为作者整理的横向对比，便于理解 /plugin 在生态中的定位。/mcp、/agents、.claude/skills/、.claude/commands/ 各自的行为以其专属官方文档为准，本指南列出的来源仅覆盖 /plugin。

/plugin 是四者里打包粒度最大的：一个插件可以同时包含 skill、MCP server、hook 等多个组件，一次安装全部生效；其他原语只管理单一组件类型。

经典使用场景

• 启用代码智能补全：安装对应语言的 LSP 插件（如 pyright-lsp、rust-analyzer-lsp），让 Claude 在编辑后自动获得类型错误和 import 缺失提示，无需手动运行编译器。
• 接入外部服务：用 /plugin install github@claude-plugins-official 安装预配置好的 MCP 集成，避免手动配置 MCP server JSON。
• 团队统一工具链：在 .claude/settings.json 里配置 extraKnownMarketplaces，新成员 clone 仓库后 Claude Code 自动提示安装团队插件。
• Git 工作流提速：安装 commit-commands 插件后可直接用 /commit-commands:commit 自动生成提交信息并创建 commit。
• 审查候选插件：在 Discover 标签页选中插件后查看 Context cost（每轮增加的 token 数）和 Will install 列表，安装前确认其实际行为。

常见坑

1. 安装后 skill 不出现：忘记运行 /reload-plugins，插件组件不会在当前会话生效。官方文档还提到清除缓存：rm -rf ~/.claude/plugins/cache，重启后重装。

2. /plugin 命令无法识别：Claude Code 版本过旧。按提示检查 claude --version 并更新（Homebrew：brew upgrade claude-code；npm：npm install -g @anthropic-ai/claude-code@latest）。

3. LSP 插件安装后 Errors 标签出现 "Executable not found in $PATH"：LSP 插件本身只配置连接，实际语言服务器二进制（如 pyright-langserver、rust-analyzer）需单独安装到系统 PATH。

4. 误删 marketplace 导致插件消失：/plugin marketplace remove 会级联卸载该 marketplace 的所有插件，操作前确认清楚。

5. 含 MCP server 的插件 reload 被拒绝：MCP 工具未使用延迟加载时，/reload-plugins 默认拒绝（避免 cache 失效），需加 --force 强制执行，代价是下一次请求重新读取完整对话历史。

6. plugin.json 的 name 与 marketplace entry 名不一致时 Enable/Disable 失效（v2.1.195 前）：若某插件在 marketplace catalog 里登记的条目名与其自身 plugin.json 的 name 字段不同，在 /plugin 面板里点 Enable/Disable 会静默无效——状态切换不生效。v2.1.195 已修复该 bug（官方原文："Fixed /plugin Enable/Disable not working when a plugin's plugin.json name differs from its marketplace entry name"）。若你在旧版上遇到某插件怎么也启用/禁用不了，先升级到 ≥ v2.1.195 再试；治本则让插件作者把 plugin.json 的 name 与 marketplace 条目名对齐。

来源

• Discover and install prebuilt plugins through marketplaces — Claude Code Docs
• Plugins reference — Claude Code Docs
• Commands — Claude Code Docs