12 · 怎么给 AI 装插件

真正把 Claude Code 用进团队，不是每个人都手动抄一遍配置，而是把好用的能力打包、分发、更新。Plugin 解决的就是这个问题：把散装经验变成可安装的工具箱。——翔宇

1. 先从一个同事的问题开始

你已经把 Claude Code 配得很顺手。

你有：

• 一个项目级 CLAUDE.md，写着团队规范。
• 两个 Skills，用来做 code review 和 release note。
• 一个 MCP server，连接 GitHub。
• 三个 Hooks，负责格式化、敏感文件保护和任务结束前检查。
• 一套权限规则，禁止读 .env 和乱 push。

然后同事问：

你这套 Claude Code 怎么配的？我也想装。

你会发现麻烦来了。

单个文件可以复制，单段配置可以贴过去。但整套能力散落在 .claude/、settings.json、.mcp.json、脚本目录、依赖说明里。复制一次还行，给三个人复制就会出错。你更新 Hook 逻辑后，还得通知大家手动更新。

官方 Create plugins 文档给的定位很清楚：Plugins 用来把 skills、agents、hooks、MCP servers 等扩展能力分享给项目和团队。Standalone 配置适合个人和单项目；Plugin 适合跨项目、跨团队、版本化分发。

2. Standalone 和 Plugin 的分界线

先不要急着做插件。很多配置一开始就该散装。

这跟写代码一样：不要一开始就发 npm 包。先在本项目里跑通，稳定后再打包。

flowchart LR
    Idea["一个好用配置"]
    Local["本项目 standalone<br/>快速试错"]
    Stable["跨项目复用<br/>结构稳定"]
    Plugin["打成 Plugin<br/>安装 / 更新 / 分发"]
    Market["进入 Marketplace<br/>团队或社区发现"]

    Idea --> Local --> Stable --> Plugin --> Market

    style Local fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style Plugin fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Market fill:#fef3c7,stroke:#f59e0b,stroke-width:2px

3. Plugin 不是“一个功能”，而是“一个容器”

旧理解里，Plugin 常被说成只打包五类东西：commands、agents、skills、hooks、MCP。

当前官方口径更宽。一个 Plugin 可以包含这些组件：

• Skills：放在 skills/，给 Claude 增加任务流程和领域能力。
• Commands：放在 commands/，是 flat Markdown 命令；新插件优先用 skills/。
• Agents：放在 agents/，定义自定义 subagent。
• Hooks：放在 hooks/hooks.json，做自动化检查和事件处理。
• MCP servers：放在 .mcp.json，连接外部工具和服务。
• LSP servers：放在 .lsp.json，提供代码跳转、引用、诊断等精确代码感知。
• Monitors：放在 monitors/monitors.json，后台监听日志、文件或外部状态。
• bin/：放可执行工具，给 Bash tool 增加命令。
• Output styles：放在 output-styles/，自定义 Claude 输出风格。
• Themes：放在 themes/，自定义界面主题。
• Default settings：放在 settings.json，插件启用时应用默认设置。

你不需要每个插件都塞满。一个好插件往往只围绕一个工作流打包。

为什么 Plugin 是"容器"不是"功能"：Skills / Hooks / MCP 各自独立时是单点能力，但真实工作流里它们经常联动——比如"PR 审查" 这一件事 = Skill（流程）+ SubAgent definition（安全审查员角色）+ MCP server（GitHub 数据）+ Hook（提交前最后一道检查）。如果只能单独装这几样，团队成员要手动装 4 处、4 个版本各自维护——很快失控。Plugin 把这几样作为一组打包 + 一起更新 + 一起卸载，解决"散装能力的版本一致性" 问题。这跟 npm 包的设计哲学一样——不是创造新能力，是给已有能力提供分发包装。

比如“PR 审查插件”可以包含：

• skills/review-pr/：审查流程。
• agents/security-reviewer.md：安全审查子代理。
• .mcp.json：GitHub MCP server。
• hooks/hooks.json：审查结束前检查是否输出风险清单。

4. 目录结构：只有 manifest 进 .claude-plugin/

Plugin 最容易写错的是目录。

官方 reference 反复强调：.claude-plugin/ 目录里放 manifest；其他组件放在插件根目录，不要塞进 .claude-plugin/ 里面。

一个标准结构大概这样：

team-review-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── review-pr/
│       └── SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/
│   └── hooks.json
├── bin/
│   └── review-helper
├── .mcp.json
├── .lsp.json
└── settings.json

错误写法是这样：

team-review-plugin/
└── .claude-plugin/
    ├── plugin.json
    ├── skills/
    ├── agents/
    └── hooks/

第二种会导致组件加载不到。

5. plugin.json：正式分发时别省

.claude-plugin/plugin.json 是插件 manifest。官方 reference 里有一个细节：manifest 可以省略；如果省略，Claude Code 会按默认位置自动发现组件，并从目录名推导插件名。

但教程里不建议你省。

正式分发时，至少写清：

{
  "name": "team-review-plugin",
  "description": "Team code review workflows for Claude Code",
  "version": "1.0.0",
  "author": {
    "name": "Your Team"
  }
}

字段怎么理解：

版本字段要特别小心。

如果你写了 version，用户只有在你 bump 版本号后才会更新。如果你没写 version，并且通过 git 分发，Claude Code 会用 commit SHA 判断版本，每次 commit 都会被视为新版本。

6. 命名空间：插件生态能长大的关键

假设你装了两个插件：

• commit-commands
• release-commands

它们都提供一个 publish Skill。如果没有命名空间，/publish 会冲突。

Plugin 的处理方式是：用插件名做前缀。

/commit-commands:publish
/release-commands:publish

这就是为什么 plugin.json 里的 name 不只是展示名。它会进入命令标识符、Skill 名称和用户调用习惯。

7. LSP 插件：给 Claude 精确代码感知

LSP（Language Server Protocol）就是 VS Code 那套“跳转定义、找引用、看类型错误”的底层协议。

Claude Code 的官方 marketplace 里已经有常见语言的 LSP 插件，比如 TypeScript、Python、Rust、Go、Java 等。安装后，如果本机有对应 language server binary，Claude 就能在编辑后更快看到诊断、类型错误、缺失 import。

这不是让 Claude “更聪明”，而是让 Claude 少靠猜：

• 没有 LSP 时，它要靠搜索和上下文推断函数定义；有 LSP 后，可以跳转定义。
• 没有 LSP 时，类型错误常常要等测试或编译才暴露；有 LSP 后，编辑后就能收到诊断。
• 没有 LSP 时，大项目里容易漏引用；有 LSP 后，可以查 references。
• 没有 LSP 时，对动态生成代码更吃力；有 LSP 后，能拿到语言服务器的结构化信息。

自己写 LSP 插件时，用 .lsp.json：

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

8. Marketplace：先加市场，再装插件

Plugin 是包，Marketplace 是目录。

官方 Discover plugins 文档里，marketplace 的流程是两步：

1. 先添加 marketplace，让 Claude Code 知道有哪些插件可浏览。
2. 再从 marketplace 里安装某个具体 plugin。

官方 Anthropic marketplace claude-plugins-official 现在会自动可用。你可以在 Claude Code 里运行：

/plugin

进入 Discover tab 浏览，也可以直接装：

/plugin install github@claude-plugins-official

如果要加一个自定义 marketplace：

/plugin marketplace add anthropics/claude-code
/plugin marketplace add https://gitlab.com/company/plugins.git
/plugin marketplace add ./my-marketplace

安装插件：

/plugin install plugin-name@marketplace-name

安装后当前会话里要重新加载：

/reload-plugins

9. 安装作用域：个人、项目、本地、管理员

同一个插件装在哪里，影响完全不同：

• User：影响你所有项目，适合个人常用插件。
• Project：影响这个仓库的所有协作者，适合团队统一工具链。
• Local：只影响你在这个仓库的本机配置，适合临时实验。
• Managed：由管理员下发，适合企业强制插件。

命令行默认装到 user scope：

/plugin install plugin-name@marketplace-name

项目级安装会写入 .claude/settings.json 的 enabledPlugins，所以 clone 这个仓库的人会看到同样的插件要求：

claude plugin install formatter@your-org --scope project

团队 marketplace 也可以写进 .claude/settings.json：

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

10. 安全：Plugin 是高信任组件

插件不是普通文档。

官方安全提示很直接：Plugins 和 marketplaces 是 high-trust components，可以用你的用户权限在机器上执行任意代码。Anthropic 不会替你验证第三方插件里的 MCP server、脚本、文件和外部软件是否可信。

所以安装前至少看四件事：

• 来源：marketplace 和 plugin repo 是谁维护的。
• 代码：hooks/、bin/、.mcp.json 有没有危险命令或外部连接。
• 权限：插件是否要求过宽能力。
• 更新：是否自动更新，版本是否可追踪。

尤其要看 bin/ 和 hooks。因为 bin/ 会被加到 Bash tool 的 PATH 里，hooks 又会在事件点自动运行。它们很方便，也最需要信任。

新手最常见的两类失控：

1. 看 marketplace 像 App Store 装一堆：marketplace 给的体验跟手机商店像，但底层完全不同——手机 App 跑在沙箱里，插件跑在你的 Claude Code session 权限里（继承你登录的 GitHub / Cloud / 数据库等所有访问能力）。修复方式：每装一个插件，至少看一下它的 bin/ 和 hooks/——这两类是真正能"代你执行"的代码。
2. 把 Plugin 当个人配置仓库：把所有 Skill、所有 Hook、个人主题、shell 别名全打进一个"my-claude-config" Plugin——结果别人装了反而被强制改成你的工作风格。修复方式：Plugin 应该围绕单一可复用工作流打包（"PR 审查"、"合规审计"），不是个人 dotfiles。个人偏好放 ~/.claude/ 不进 Plugin。

11. 缓存和路径：安装后不是原地运行

还有一个容易踩的工程细节：插件安装后会被复制到本地版本化 cache，位置在 ~/.claude/plugins/cache。

这带来两个后果。

第一，插件不能随便用 ../shared-utils 引用目录外文件。安装时只会复制插件目录本身，外面的文件不会跟着走。

第二，如果你真的需要共享外部工具，可以在插件目录内放 symlink。官方 reference 说 symlink 会保留，并在运行时指向目标。

12. 把 12 篇串起来

现在可以回看整组 Claude Code 理解篇。

flowchart TB
    Local["01 位置<br/>AI 在你的电脑里"]
    Context["02 上下文<br/>AI 当前能看到什么"]
    Memory["03 记忆<br/>跨会话保留什么"]
    Commands["04 命令<br/>你怎么发起动作"]
    Thinking["05 思考<br/>问题要想多深"]
    Skills["06 Skills<br/>复用任务能力"]
    Subagents["07 SubAgents<br/>隔离旁支任务"]
    Teams["08 Agent Teams<br/>多会话协作"]
    MCP["09 MCP<br/>连接外部系统"]
    Hooks["10 Hooks<br/>确定性检查点"]
    Permissions["11 Permissions<br/>访问边界"]
    Plugins["12 Plugins<br/>打包和分发"]

    Local --> Context --> Memory
    Memory --> Commands --> Thinking
    Thinking --> Skills
    Skills --> Subagents --> Teams
    Skills --> MCP
    MCP --> Hooks
    Hooks --> Permissions
    Permissions --> Plugins
    Skills --> Plugins
    Subagents --> Plugins
    MCP --> Plugins
    Hooks --> Plugins

    style Plugins fill:#fef3c7,stroke:#f59e0b,stroke-width:2px

这 12 篇不是功能清单，而是一条生长线：

• 运行位置，01：Claude Code 为什么能碰你的项目。
• 感知，02-03：它当前看见什么，长期记住什么。
• 交互，04-05：你怎么给任务，它怎么决定想多深。
• 能力，06-09：任务流程、分身、团队、外部系统怎么接入。
• 保障，10-11：关键动作怎么自动检查，边界怎么管。
• 分发，12：好用的组合怎么传给别人。

13. 本章自检

试着用自己的话回答：

1. Standalone 配置和 Plugin 的分界线是什么？什么时候不该急着做插件？对应 §2。
2. 为什么 .claude-plugin/ 里只放 manifest，组件要放在插件根目录？对应 §4。
3. version 写在 plugin.json 里有什么更新后果？对应 §5。
4. Marketplace 为什么要分"添加市场"和"安装插件"两步？对应 §8。
5. 动手题 ⭐：列出你 ~/.claude/ 下当前所有 standalone 配置（Skills / Hooks / MCP servers）。判断：哪些只对你个人 / 单项目有用——留在 standalone；哪些会被另一个项目或同事复用——可以打成 Plugin。如果你只数出 0-1 条该 Plugin 的，证明你还在 standalone 阶段——别为了"看起来工程化"提前打包。对应 §2。

官方资料

• Plugins
• Plugin marketplaces

接下来去哪

如果只记一个判断：Plugin 的价值不是让 Claude Code 多一个孤立功能，而是把稳定、可复用、可审查的工作流变成别人也能安装和更新的能力包。