你有没有遇到过这种情况：在 Claude Code 里配好了一堆 Slash Command、Skill、Hook，换台机器就得重新来一遍？新项目开张，又得从头搭建工作流？想跟团队分享一套好用的配置，只能靠「手动复制 → 粘贴 → 祈祷不要漏文件」？

如果你点头了，那你需要的就是 Plugin（插件）。

在这之前，我们用一系列文章聊过怎么用 CLAUDE.md 给项目设定上下文、用 Slash Command 和 Skill 把重复任务变成可靠工作流、用 Hook 在关键执行节点卡住行为边界。这些能力单拎出来都很强——像钢铁侠、蜘蛛侠、雷神，各自能打。但拯救世界需要的是复仇者联盟。Plugin 就是那个把各路英雄集结在一起的机制。

本文会从插件的基本概念、安装使用、开发调试，到它的局限性、竞品对比和未来走向，一口气讲清楚。

---

01 什么是 Plugin？

Claude Code 官方对 Plugin 的定义很清晰：

Plugin 是一种轻量级的方式，可以将 Slash Command、Subagent、MCP Server、Hook 的任意组合打包和分享。

官方文档还特别强调：

Plugin 将是我们打包和分享 Claude Code 自定义功能的标准方式，随着更多扩展点的加入，这个格式会持续演进。

说白了，Plugin 就是给 Claude Code 装上一个「应用商店」机制。它不创造新能力，而是把已有的能力——命令、技能、子代理、钩子——打包成一个有名字、有版本号、结构清晰的可分发单元。

为什么需要 Plugin？

核心原因是复用。

场景	没有 Plugin	有 Plugin
换机器工作	手动复制 .claude/ 目录，容易漏	一条命令安装，版本一致
新项目启动	重新配置一遍，痛苦	/plugin install 搞定
团队协作	靠口头或文档传配置	项目级安装，继承进仓库
更新能力	不知道谁用的是哪个版本	manifest 里的版本号一目了然
避免冲突	两个团队都定义了 /review 命令	命令自动带上命名空间

更关键的是命名空间机制。 每个 Plugin 都用自身名称作为组件的前缀。比如某个插件里的命令是 /team-plugin:hello 而不是 /hello，即使多个来源的插件有同名的组件，也不会打架。

想象一下，如果你的 .claude/ 目录里有两个同名 Skill 会发生什么——混乱。Plugin 的命名空间机制从根上解决了这个问题。

---

02 安装和使用 Plugin

要理解安装流程，先得分清两个概念：Marketplace（市场） 和 Plugin（插件）。

简单来说，Marketplace 是目录，Plugin 是应用。一个 Marketplace 本身不包含任何能力，它只是告诉 Claude Code「这里有这些插件可以装」。就像手机里的应用商店——你先打开商店，再选 App 下载。

安装步骤

第一步：添加 Marketplace（如果需要）

Anthropic 的官方市场 claude-plugins-official 在 Claude Code 启动时就自动可用了，不需要手动添加。

对于第三方市场，你得先告诉 Claude Code 去哪儿找。最常见的方式是用 GitHub 仓库地址：

/plugin marketplace add OthmanAdi/planning-with-files

也支持各种其他来源：

# 任何 Git 仓库（GitLab、Bitbucket、自建仓库都可以）/plugin marketplace add https://gitlab.com/my-team/ai-plugins.git# 指定分支或标签/plugin marketplace add https://gitlab.com/my-team/ai-plugins.git#dev/plugin marketplace add https://gitlab.com/my-team/ai-plugins.git#v1.0.0# 本地目录/plugin marketplace add /Users/jimmy/work/ai-plugin-marketplace# 远程 marketplace.json/plugin marketplace add https://example.com/marketplace.json

所有仓库源的共同要求是：必须包含 .claude-plugin/marketplace.json 文件。

第二步：安装插件

# 官方市场插件（市场名自动可用）
/plugin install frontend-design@claude-plugins-official

# 第三方市场插件
/plugin install planning-with-files@planning-with-files

安装后记得运行 /reload-plugins 激活。

安装范围

安装时你可以选择作用域：

• user 范围：对你所有项目都有效（默认）

• project 范围：写入 .claude/settings.json，可随仓库分享给协作者

• local 范围：只对你在当前仓库生效

# 从终端安装
claude plugin install planning-with-files@planning-with-files

# 指定作用域
claude plugin install planning-with-files@planning-with-files --scope project

两种管理方式

方式一：在 Claude Code 内部使用 /plugin 命令会打开一个交互式界面，四个 Tab 页，适合浏览和选择。

方式二：在终端使用 claude plugin CLI 命令适合脚本和批量操作，不用进交互界面。

加载本地插件

开发调试时，可以直接用 --plugin-dir 加载本地目录：

claude --plugin-dir /Users/jimmy/work/dev-helper# 也支持直接加载 .zip 压缩包claude --plugin-dir /Users/jimmy/work/dev-helper.zip

当 --plugin-dir 加载的插件与已安装的插件重名时，当前会话优先使用本地版本——方便在不卸载已安装版本的情况下测试修改。

日常管理

# 启用/禁用后记得重载
/plugin disable <plugin-name>
/plugin uninstall <plugin-name>
/reload-plugins     # 应用更改

⚠️ 一个重要警告：删除 Marketplace 会同时卸载从该市场安装的所有插件。

---

03 开发 Plugin

开发 Plugin 的门槛比你想象的低。最小的插件只需要一个目录，里面放一个清单文件。

最小插件结构

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # 唯一允许放在此目录的文件

plugin.json 的内容：

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

各字段的含义：

• name：既是唯一标识符，也是执行命令时使用的命名空间

• version：使用语义化版本号管理发布

• description：在插件管理器中显示

添加能力

有了身份之后，就可以往插件里加料了。能力放在特定目录下：

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/            # Slash Command
├── skills/              # Skill
├── agents/              # Subagent
├── hooks/
│   └── hooks.json       # Hook 配置
└── .mcp.json            # MCP 服务器配置

如果需要代码智能，还可以加 .lsp.json。

💡 最容易踩的坑：除了 plugin.json 在 .claude-plugin/ 里面，其他目录和文件都必须放在插件根目录，不能放进 .claude-plugin/ 目录下，否则 Claude Code 不会加载。

什么是 LSP？

LSP（Language Server Protocol）代码智能连上语言服务器后，可以提供跨文件的项目级代码理解：跳转到定义、查找引用、类型信息、符号分析。这能帮 Claude Code 更准确地读写代码。

开发中的重要变量

插件安装后会被复制到缓存目录。如果你的 Hook 脚本需要引用插件自带的文件，不能硬编码路径。必须用 ${CLAUDE_PLUGIN_ROOT} 来定位插件根目录：

"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd"

这样无论在什么机器、什么缓存路径下安装，脚本都能被正确找到。

调试最佳实践

写完后怎么调试？最简单的方式是 --plugin-dir：

claude --plugin-dir ./my-plugin

加载多个就这样：

claude --plugin-dir ./my-plugin --plugin-dir ./another-plugin

发现 bug 修完代码后，在 Claude Code 里运行 /reload-plugins 就能重载改动，不用来回重启。

从已有配置迁移

如果你已经在 .claude/ 下有了命令和 Skill，迁移成 Plugin 也很直接：

1. 创建插件目录，写好 plugin.json

2. 把 .claude/commands/、.claude/agents/、.claude/skills/ 的内容复制进去

3. 把 settings.json 里的 hooks 对象移到 hooks/hooks.json（格式不变）

这样就完成了从零散配置到插件的迁移。稳定之后加上 marketplace.json 放到市场仓库里，别人就能安装了。

---

04 Plugin 的局限和不足

Plugin 作为分发机制虽然方便，但它还是个相对早期的能力。一旦用于团队协作和复杂工作流，几个明显的问题就暴露出来了。

插件内 Subagent 能力受限

这是最需要注意的一点。即使 Subagent 的 frontmatter 里写了 hooks、mcpServers、permissionMode，插件里的 Subagent 运行时会忽略这些字段。

原因也不难理解：Subagent 本身就是更受限的执行单元。如果允许它在插件里注册 Hook、附加 MCP 服务器或修改权限模式，等于让一个低权限角色能修改执行流程的控制规则——这从根本上突破了安全边界。

所以虽然是合理的限制，但插件开发者需要提前知道：插件里的 Subagent 能力不等于本地的 Subagent。受影响的功能逻辑要用其他方式实现。

市场缺乏分类，插件内容不透明

发现难。 当前的市场就像一张扁平的插件列表，没有分类、标签、筛选。浏览主要靠插件名字和描述。插件少的时候还能凑合，等生态长大了，类似功能的插件一多，找对的就越来越难了。

信任难。 安装插件意味着在你的机器上引入了一段可以任意执行的代码——它的 Hook 能跑 Shell 命令，MCP Server 能建立外部连接，命令能给上下文注入提示。但在安装之前，你很难看清这个包里到底装了些什么。

官方文档明确说：Anthropic 不控制也无法验证插件里的 MCP 服务器、文件或其他软件。安装之前，确保你信任这个来源。

插件粒度问题

看看现在已有的插件，你会发现一个有趣的现象：有些插件极度轻量，可能就包含一个 Skill。一个组件占据整个插件，却要走完整的 plugin.json、目录结构、版本管理的流程。好比用集装箱运一个信封。

实际上，业界已经有更轻的方式安装 Skill：

npx skills add <package>

这是 Vercel Labs 的开源 CLI 工具，定位是 Skill 的包管理器——就像 npm 管理 JavaScript 包一样，它管理 AI Agent 的 Skill 包。最关键是它是跨 Agent 的：同一个 Skill 可以被 Claude Code、Codex、Cursor、Gemini CLI 用，不绑定任何工具。

两者的本质区别在于工作层面不同：

维度	Skills（npx skills）	Plugin
本质	内容：SKILL.md + 脚本/资源	容器：Skill + Hook + Subagent + MCP
粒度	单一技能	完整协作约定包
跨 Agent	是，不绑定	否，绑定 Claude Code
适合场景	独立 Skill	整套工作流规范

所以什么时候该用哪个？只有独立 Skill，npx skills 就够了。需要分发一整套协作规范，选 Plugin。

---

05 与其他 Coding Agent 插件系统对比

进入 2026 年后，几乎所有主流 Coding Agent 都在往插件方向走。Claude Code 起步相对早，而 2026 年上半年，Codex、Cursor、Gemini CLI 也都加上了对应机制。插件已经从 Claude Code 的特色，变成了这代 Coding Agent 的标配能力。

维度	Claude Code Plugin	Codex Plugin	Cursor Plugin	Gemini CLI Extension
发布时间	较早	2026 年 3 月	2026 年 2 月（v2.5）	2026 年
核心概念	能力打包分发单元	技能+应用+MCP打包	编辑器深度集成的开发流程包	围绕 MCP 扩展 CLI
清单文件	plugin.json	manifest.json	plugin.json	extension.json
能力结构	skills/, hooks/, .mcp.json	skills/, apps/, .mcp.json	skills/, hooks/, .mcp.json	hooks/, .mcp.json
产品定位	终端 Agent 编码+团队工作流复用	应用连接+跨服务自动化	端到端产品开发（Linear→Figma→代码→部署）	Google Cloud 生态+开箱即用工具

虽然功能架构差不多，但不能直接互换使用。最典型的例子是 Hook：

• Claude Code 的事件名：UserPromptSubmit、PostToolUse、Stop

• Gemini CLI 的事件名：BeforeAgent、AfterTool、SessionEnd

名字都完全不同。换句话说，即使把一个插件目录原样复制过去，大概率跑不起来。

---

06 插件会重复 GPTs 的轨迹吗？

2023 年底，OpenAI 发布了 GPTs——愿景和今天的 Plugin 如出一辙：任何人都能创建定制 AI 助手，通过 Store 分发甚至变现。但后来大家也看到了：大量 GPTs 只是套了壳的提示词，Store 缺乏有效的质量筛选和发现机制，创作者没有可持续的收入模式。GPTs 至今还在，但远没成为曾经畅想的新生态。

Plugin 身上也有类似的警示信号：

• 内容同质化风险：大量依赖提示词驱动的 Skill 和 Command

• 市场发现和审核机制薄弱

• 开发者缺乏激励：大部分靠社区贡献，没有明确商业化路径

但 Plugin 和 GPTs 有一个本质区别：

GPTs 面向的是写文案、做图、查信息这类通用需求。用户试一下就走了，粘性不高。Plugin 面向的是开发团队的刚需：统一编码规范、沉淀领域知识、自动化工作流。一个已经嵌入 CI/CD 管线的代码审查插件，不会因为热度褪去就被抛弃。

所以哪怕长尾热度消退，头部的高价值工作流插件依然有坚实的基础持续使用。

问题最终还是取决于 Anthropic 的态度： 他们是真的打算在发现机制、质量标准、开发者激励上持续投入，还是只把 Plugin 当做功能清单上的一个勾？

目前来看，底层的 Plugin 机制是扎实的，但生态基建还有很长的路要走。

---

总结

Plugin 解决的核心问题，是把 Claude Code 零散的自定义能力变成可管理、可分发的单元。

回顾这个系列，我们走通了 Claude Code 各组件的使用和分发。Plugin 的安装、版本管理、市场分发、组件组织已经有了比较完整的设计。

但往更大的 Coding Agent 生态去看，要把一个插件直接复用到另一个 Agent 里，目前还不太可行。真正的跨工具互通，距离落地还很远。

---

📚 参考资料

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

• Create plugins — Claude Code Docs

• Create and distribute a plugin marketplace — Claude Code Docs

• Claude Code settings — Claude Code Docs

• Plugins reference — Claude Code Docs

• Plugins — OpenAI Codex Docs

• Plugins — Cursor Docs

• Gemini CLI extensions

---

💬 聊一聊

你用 Claude Code 开发过插件吗？或者你对 Coding Agent 的插件生态有什么看法？欢迎留言讨论～