---
title: "12 · 怎么给 AI 装插件"
description: "Claude Code Plugin 不是单个新功能，而是把 Skills、Agents、Hooks、MCP、LSP、主题和监控打包成可安装、可更新、可分发的能力包。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-08"
---

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

> [!NOTE]
> **这一篇用 15 分钟换什么**：前 11 篇讲了 Claude Code 的位置、上下文、记忆、命令、思考、Skills、SubAgents、Agent Teams、MCP、Hooks 和 Permissions。最后这一篇讲 Plugins：怎么把这些能力装进一个包里，给自己、团队或社区复用。

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

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

你有：

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

然后同事问：

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

你会发现麻烦来了。

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

> [!IMPORTANT]
> **第一性原理**：Plugin 解决的不是“Claude Code 有没有某个能力”，而是“这些能力怎么被打包、安装、隔离、更新和分发”。

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

## 2. Standalone 和 Plugin 的分界线

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

| 你在做什么 | 更适合 |
|------|------|
| 给当前项目写一条规则 | `.claude/` 或 `CLAUDE.md` |
| 试验一个临时 Hook | `.claude/settings.local.json` |
| 写一个只给自己用的 Skill | standalone Skill |
| 同一套能力要给多个项目用 | Plugin |
| 要给同事一键安装 | Plugin |
| 要走 marketplace 分发和更新 | Plugin |

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

```mermaid
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
```

> [!TIP]
> **判断标准**：只给一个项目用，先别打包；要被第二个项目复用，就开始考虑 Plugin；要给别人安装，就必须考虑 Plugin。

## 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`：审查结束前检查是否输出风险清单。

> [!WARNING]
> **新手坑**：不要把所有个人偏好都打进一个“万能插件”。Plugin 应该围绕可复用任务组织，不是把你的整个电脑配置搬给别人。

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

Plugin 最容易写错的是目录。

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

一个标准结构大概这样：

```text
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
```

错误写法是这样：

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

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

> [!IMPORTANT]
> **一句话记住**：`.claude-plugin/` 是身份证夹，不是工具箱本体。工具本体放插件根目录。

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

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

但教程里不建议你省。

正式分发时，至少写清：

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

字段怎么理解：

| 字段 | 作用 |
|------|------|
| `name` | 插件唯一标识，也是 skill 命名空间前缀 |
| `description` | `/plugin` 管理界面里展示给用户看 |
| `version` | 控制用户什么时候收到更新 |
| `author` | 作者归属 |
| `homepage` / `repository` / `license` | 分发和信任信息 |

版本字段要特别小心。

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

> [!CAUTION]
> **发布坑**：不要在 `plugin.json` 和 marketplace entry 里同时维护两个版本号。官方说明里 `plugin.json` 的 version 会优先，旧 manifest 版本可能会让 marketplace 里的新版本失效。

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

假设你装了两个插件：

- `commit-commands`
- `release-commands`

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

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

```text
/commit-commands:publish
/release-commands:publish
```

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

> [!TIP]
> **命名原则**：插件名要短、稳定、可读。不要把版本、团队临时项目名、日期塞进 `name`。版本放 `version`，来源放 marketplace。

## 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`：

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

> [!IMPORTANT]
> **边界**：LSP 插件通常不自带 language server binary。用户机器上仍然要先装好 `gopls`、`pyright-langserver`、`rust-analyzer` 这类二进制，否则插件会报 `Executable not found in $PATH`。

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

Plugin 是包，Marketplace 是目录。

官方 [Discover plugins](https://code.claude.com/docs/en/discover-plugins) 文档里，marketplace 的流程是两步：

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

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

```text
/plugin
```

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

```text
/plugin install github@claude-plugins-official
```

如果要加一个自定义 marketplace：

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

安装插件：

```text
/plugin install plugin-name@marketplace-name
```

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

```text
/reload-plugins
```

> [!TIP]
> **别混淆**：添加 marketplace 不等于安装插件。添加只是把“应用商店”放进来，安装才是把具体 app 下载到本机。

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

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

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

命令行默认装到 user scope：

```text
/plugin install plugin-name@marketplace-name
```

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

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

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

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

> [!WARNING]
> **团队规则别放错**：团队必须共享的插件用 project scope；你个人喜欢的输出风格、主题和实验插件不要写进项目级配置。

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

插件不是普通文档。

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

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

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

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

> [!CAUTION]
> **不要把陌生插件当主题包装**：一个主题插件也可能带脚本，一个 LSP 插件也可能要求本机二进制。插件安装前要按代码资产审查，不是按 UI 插件审查。

**新手最常见的两类失控**：

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 会保留，并在运行时指向目标。

| 写法 | 结果 |
|------|------|
| `../shared-utils/script.sh` | 安装后大概率找不到 |
| `./scripts/helper.sh` | 正常，文件在插件目录内 |
| `./shared-utils -> /path/to/shared-utils` | 可用，但要确认目标机器也有该路径 |

> [!IMPORTANT]
> **分发原则**：插件应该尽量自包含。依赖外部文件越多，别人安装成功率越低。

## 12. 把 12 篇串起来

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

```mermaid
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**：好用的组合怎么传给别人。

> [!TIP]
> **一句话理解全系列**：Claude Code 不是单个“会写代码的聊天框”，而是一套把本机上下文、任务能力、外部工具、安全边界和团队分发组合起来的 Agent 运行环境。

## 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。

> [!IMPORTANT]
> **过关标准**：你能把一个已有 `.claude/` 配置拆成插件结构，并能解释哪些东西该打包，哪些东西应该留在本机 local scope。

<details id="glossary">
<summary><b>本篇术语速查表</b></summary>

- **Plugin**：插件，Claude Code 可安装、可更新、可分发的能力包。
- **Manifest**：清单文件，`.claude-plugin/plugin.json`，描述插件身份和元信息。
- **Marketplace**：插件市场，`.claude-plugin/marketplace.json` 描述的一组插件目录。
- **Skill namespace**：Skill 命名空间，`/plugin-name:skill-name` 这种防冲突前缀。
- **LSP**：语言服务器协议，给 Claude 提供跳转定义、引用、诊断等代码智能。
- **Monitor**：后台监控，插件里持续监听日志、文件或外部状态的配置。
- **Scope**：安装作用域，插件安装到 user、project、local 或 managed 层级。
- **Cache**：插件缓存，安装后复制到 `~/.claude/plugins/cache` 的本地副本。
- **`enabledPlugins`**：已启用插件，项目级 settings 中记录共享插件的配置项。
- **`extraKnownMarketplaces`**：额外市场，项目级 settings 中声明团队 marketplace 的配置项。

</details>

## 官方资料

- [Plugins](https://code.claude.com/docs/en/plugins)
- [Plugin marketplaces](https://code.claude.com/docs/en/plugin-marketplaces)

## 接下来去哪

<Cards>
  <Card href="/docs/claude-code" title="回到 Claude Code 教程总览" description="从总览页重新选择官方教程中文版或深度理解路径。" />
  <Card href="/docs/claude-code/understanding/11-permissions" title="11 · 该给 AI 多少权限（上一篇）" description="安装插件前先懂权限边界：插件是高信任组件，不要把陌生插件当普通配置。" />
  <Card href="/docs/claude-code/understanding/06-command-files" title="06 · 怎么复用技能" description="Plugin 最常打包的就是 Skills。分不清 Skill 和 Plugin 时，回到这一篇。" />
</Cards>

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