Plugins 深入

Skills、Subagents、Hooks、MCP 都是单点能力——你一个个配、一个个调。但一个团队的最佳实践往往是一整套：一套命令、几个子代理、若干钩子、再加几个 MCP 服务器。Plugin（插件）就是把这些东西打包成分发包，像应用商店里的 App 一样，一键安装、统一管理、跨项目复用。

如果说 Skills 是按需抽屉、Subagents 是外聘顾问、Hooks 是门卫、MCP 是万能插座，那 Plugin 就是应用商店——你不用自己一个个攒组件，挑一个评分高的装上就行。

这一篇讲清插件的结构、/plugin 命令、三种作用域、marketplace 源类型和命令防冲突机制。

插件是什么：一个分发包

插件是一个可分发的包，里面可以包含四类资产：

资产	位置	作用
Commands（命令）	`commands/` 目录	注册斜杠命令
Agents（子代理）	`agents/` 目录	注册自定义子代理
Hooks（钩子）	配置中的 hooks	注册生命周期钩子
MCP servers（MCP 服务器）	配置中的 mcp	接通外部服务

一个插件可以只含一类，也可以四类全有。装上之后，这些资产就和你自己手写的一样可用——但它们来自插件，因此可以统一启停、统一更新、统一卸载。

/plugin 命令：应用商店入口

所有插件操作都通过 /plugin 命令完成：

操作	怎么做
浏览可用插件	`/plugin` 打开面板，列出已安装和可发现插件
安装插件	`claude plugin install <name>@<marketplace>`
查看详情	`/plugin` 选插件，看它提供哪些能力
启用 / 禁用	`/plugin` 切换开关
添加 marketplace	`/plugin` → 添加新的市场源

命令行直接装：

claude plugin install code-reviewer@company-marketplace

<name>@<marketplace> 的格式说明插件由「名字 + 来源市场」唯一确定——不同市场可以有同名插件，靠 @marketplace 区分。

enabledPlugins：开关配置

插件装好之后，是否启用由 enabledPlugins 配置控制，写法是 {"插件名@市场名": true/false}：

{
  "enabledPlugins": {
    "code-reviewer@company-marketplace": true,
    "legacy-migrator@community": false
  }
}

true 表示启用，false 表示装了但先不用。这比卸载灵活——临时关掉某个插件，配置和资产还在，随时能开回来。

三种作用域

插件的启用范围分三个层级，和 settings 的层级一一对应：

作用域	配置位置	影响范围
user	`~/.claude/settings.json`	该用户的所有项目
project	项目 `.claude/settings.json`（通常提交进仓库）	团队所有成员
local	项目 `.claude/settings.local.json`（不提交）	仅当前本机

典型用法：

团队共用的工作流插件 → 写进 project 作用域，随仓库分发，大家 clone 后自动有。
个人偏好的插件 → 写进 user 作用域，全项目可用。
还在试水、不想影响别人的插件 → 写进 local 作用域，本机独享。

extraKnownMarketplaces：定义额外市场

默认市场之外，你可以添加自己的插件市场。用 extraKnownMarketplaces 配置：

{
  "extraKnownMarketplaces": {
    "company-marketplace": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

定义之后，claude plugin install xxx@company-marketplace 就能从你自己的市场装东西了。

三种 marketplace 源类型

市场从哪来？支持三种 source 类型：

类型	写法	适用场景
`github`	指向 GitHub 仓库	团队插件市场放在 GitHub repo
`git`	指向任意 Git URL	私有 Git 服务器、GitLab 自建
`directory`	指向本地目录	本地开发，改完立刻见效

本地开发插件时用 directory 最方便——指向你正在编辑的文件夹，改一行马上能测，不用反复发布：

{
  "extraKnownMarketplaces": {
    "dev": {
      "source": {
        "source": "directory",
        "path": "/Users/you/projects/my-plugins"
      }
    }
  }
}

插件命令：自带命名空间

插件提供的命令放在它的 commands/ 目录下。为了避免不同插件的命令撞名，插件命令采用带命名空间的调用格式：

/plugin-name:command-name

也就是「插件名 + 冒号 + 命令名」。比如 reviewer 插件里有个 pr-check 命令，调用时是 /reviewer:pr-check。这样即使两个插件都有 pr-check，也不会打架——前缀就是插件名，天然隔离。

插件能提供什么

回顾一下，装一个插件可能给你带来：

新命令：/plugin-name:command 直接调用，例如 /reviewer:pr-check
新子代理：自动注册到子代理列表，主代理可按需委托
新钩子：自动挂上生命周期钩子（注意：这有安全含义，下文讲）
新 MCP 服务器：插件可以声明它依赖的 MCP，装插件时一并接上

四者合一，一个插件就是一个完整的工作流打包。比如「团队代码审查」插件可能同时提供：一个 /reviewer:full-check 命令、一个 security-reviewer 子代理、一个「阻止改 lock 文件」的钩子、一个连 Sentry 的 MCP。装上等于把整套审查流水线搬进项目。

Plugin Marketplaces：企业管理

对团队而言，市场是可以集中治理的：

统一市场：运维或平台团队维护一个公司级 marketplace，所有插件经审核后上架。
作用域管控：通过 project 作用域的配置，规定哪些插件默认开启、哪些需申请。
来源限制：只允许 github/git 类型的受信市场，禁用随意 directory 指向外部目录。

这样团队既能享受插件「即装即用」的便利，又不会出现「人人各自装野插件」的失控局面。

安全提醒

插件能挂钩子、能接 MCP、能注册子代理——这意味着它能力很大。三件事要警惕：

钩子是自动执行的：插件带的 hook 一装上就生效，和你自己写的一样会自动跑。安装前看清楚它挂了哪些钩子。
MCP 暴露凭证：插件声明的 MCP 服务器会拿到你的 token（参见 MCP 深入的安全章节）。
来源可信度：只装信任市场里的插件，别装来路不明的，尤其是带 hooks 和 MCP 的——它们能读你的环境变量、能联网。

防护和 MCP 一样：审清来源、最小权限、定期审视。

何时用插件，何时用 Skills/Subagents

需求	推荐
单一专家能力，按需触发	Skill
独立上下文做某类重活	Subagent
一条强制规则	Hook
接一个外部服务	MCP
一整套工作流要打包分发	Plugin

判断逻辑很简单：单点用对应组件，成套用插件。如果你发现自己给同一个场景配了命令 + 子代理 + 钩子 + MCP，那它们就该被捆成一个插件，方便复用和版本管理。

最佳实践速记

能用 project 作用域就别用 user：随仓库分发，团队成员自动获得一致能力。
本地开发用 directory 源：改完即测，迭代飞快。
命名空间别省：插件命令一律 /plugin-name:command，避免冲突。
装前审钩子和 MCP：这是插件里最敏感的两类资产。
成套打包：场景级的命令/代理/钩子/MCP 捆成插件，而不是散落各处各自配置。

插件是 Claude Code 能力复用的最高层级——把零散组件捆成可分发的整体。到这里，进阶深入板块的五个组件就讲完了：Skills 按需加载、Subagents 独立上下文、Hooks 强制规则、MCP 接通外部、Plugins 打包分发。五者配合，就是你最趁手的工作流。🚀