Claude Code 插件与 marketplace 是什么？完全指南

随着对 Claude Code 的深入使用，你会积累起属于自己的斜杠命令、常用的子代理、MCP 服务器以及钩子。plugin（插件）正是把它们打包成一个整体，让你能够进行版本管理，并在团队与项目之间共享、复用的机制，而 marketplace（应用市场）则是它们的分发场所（插件于 2025 年 10 月以公开测试版亮相，2026 年又新增了官方目录以及 /plugin 的搜索与列表功能）。

本文基于官方文档，梳理什么是插件、它的结构、如何使用、marketplace、自制与发布，以及分发范围与安全性。先讲三个要点。（1）插件就是把"技能 / 命令 / 子代理 / 钩子 / MCP 服务器"打包在一起的一个目录，.claude-plugin/plugin.json 即清单文件。（2）用 /plugin 添加 marketplace，用 install 安装插件。（3）自制也很简单——放入一个 plugin.json 和一个 SKILL.md，用 claude --plugin-dir 测试，再通过 git 发布即可。

1. 什么是 Claude Code 插件

按官方定义，插件是"一个自包含的目录，它把 Claude Code 的自定义功能打包在一起，以便进行版本管理、共享与复用"。单个插件可以任意组合包含以下内容：

简而言之，插件就是"把 Claude Code 的扩展装箱成可分发的形态"。原本零散配置的各项自定义内容，可以汇集进一个仓库，让整个团队复现同一套环境。你也可以加入 LSP 服务器、后台监控以及可执行文件（bin/），但先掌握上面这六项就足够起步了。

2. 插件的结构

关于目录布局有一条重要规则：.claude-plugin/ 里只放 plugin.json。commands/、agents/、skills/、hooks/ 这些目录要放在插件根目录下（而不是放进 .claude-plugin/ 里）。

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 清单文件——只有这个文件放在这里
├── skills/
│   └── code-review/SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/hooks.json
├── .mcp.json
└── README.md

一个最小的 plugin.json 清单：

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

name 既是标识符，也是技能的命名空间（技能会以 /my-first-plugin:hello 这样的形式被调用）。version 是可选的：若设置了，则只有当你提升它时，用户才会收到更新。若在通过 git 分发时省略 version，则 commit SHA 会充当版本号（每次提交都是一个新版本）。

3. 使用方法——/plugin 与 marketplace

通过 /plugin 进行安装，它会打开一个分页式管理界面（Discover / Installed / Marketplaces / Errors）。核心命令如下：

# 添加一个 marketplace（分发目录）
/plugin marketplace add anthropics/claude-code        # GitHub 的 owner/repo
/plugin marketplace add ./my-marketplace              # 本地路径
/plugin marketplace add https://example.com/marketplace.json

# 安装 / 管理插件（默认为用户范围）
/plugin install plugin-name@marketplace-name
/plugin enable  plugin-name@marketplace-name
/plugin disable plugin-name@marketplace-name
/plugin uninstall plugin-name@marketplace-name

# 列出（用 --enabled / --disabled 筛选）。/plugin 内也有搜索栏
/plugin list
/plugin list --enabled

# 无需重启即可应用更改
/reload-plugins

"添加 marketplace"＝"注册一个目录"，仅此一步并不会安装任何插件——你先添加目录，然后再逐个 install 插件。对于脚本用途，也提供了 claude plugin install … 这类非交互式的 CLI 命令。另外，如果插件内置的 MCP 服务器无法连接，请参阅 MCP 连接错误的处理方法。

4. 什么是 marketplace

marketplace 是一个带有 .claude-plugin/marketplace.json 的目录，该文件列出了各个插件以及每个插件的获取来源（git 仓库、本地路径或托管文件）。它既有官方提供的，也有面向社区的。

也就是说，如果只是想"用一用"，官方市场马上就能用。社区目录或公司内部的自有目录，则按需添加即可。

5. 自制并发布

自制起来出乎意料地简单。先从放入清单与技能，然后在本地测试开始。

# 1) 搭建脚手架
mkdir -p my-first-plugin/.claude-plugin my-first-plugin/skills/hello
# write .claude-plugin/plugin.json and skills/hello/SKILL.md

# 2) 不安装即测试（.zip 也可以）
claude --plugin-dir ./my-first-plugin

要发布，只需在一个 git 仓库的根目录放上一个 .claude-plugin/marketplace.json 即可。用户用 /plugin marketplace add owner/repo 来添加它。

{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Adds a quick code-review skill"
    }
  ]
}

版本管理按以下顺序解析：plugin.json 中的 version →（否则）marketplace 条目中的 version →（再否则）commit SHA。如果你固定了 version，就要在每次发布时提升它（一旦忘了，用户就收不到更新）。发布前用 claude plugin validate . 进行验证。要被收录进官方社区目录，需通过投稿表单申请（须满足 Team/Enterprise 等条件）。

6. 分发范围与安全性

安装有范围（scope）之分：user（默认，所有项目）/ project（仓库的全体协作者，记录在 .claude/settings.json 中）/ local（仅你自己，仅此仓库）/ managed（由管理员分发，用户不可修改）。对于团队分发，在项目的 .claude/settings.json 中写入 extraKnownMarketplaces 与 enabledPlugins，当成员信任该文件夹时，就会被提示进行安装。

总结

Claude Code 插件把技能、斜杠命令、子代理、钩子和 MCP 服务器打包进一个目录，让你能进行版本管理、共享与复用（清单文件是 .claude-plugin/plugin.json，commands/ 等放在根目录）。它们通过 marketplace 分发，而官方市场（claude.com/plugins）开箱即用。安装流程是 /plugin marketplace add → /plugin install →（按需）/plugin list、搜索、/reload-plugins。

自制也是一条短路径：放入一个 plugin.json 和一个 SKILL.md，用 claude --plugin-dir 测试，然后在 git 仓库里放上一个 marketplace.json 来发布。范围分为 user / project / local / managed，团队分发通过 .claude/settings.json 实现。但插件可以执行任意代码，所以只安装来自可信发行方的插件，并在组织中用 strictKnownMarketplaces 限制来源。插件还可以打包钩子，它们会在生命周期的各个节点自动运行——其工作原理详见深入解析。相关：Claude Agent Skills、MCP、Claude Code Artifacts。

FAQ

Q. 插件和技能有什么区别？
A. 技能是插件内部的组成要素之一。插件是一个分发单元（目录），它在技能之外还打包了斜杠命令、子代理、钩子和 MCP 服务器。当你想把常用的技能和命令打包后分发给团队时，那个"箱子"就是插件；而箱子里的某一份"操作说明书"就是技能。

Q. 我该如何安装插件？
A. 先用 /plugin marketplace add owner/repo 添加一个 marketplace（目录），再用 /plugin install plugin-name@marketplace-name 逐个安装。官方市场（claude-plugins-official）从首次启动起便自动可用，你可以在 claude.com/plugins 或通过 /plugin 的 Discover 浏览。用 /plugin enable|disable 切换启用状态，用 /plugin list 查看列表。

Q. 我能自制并分发自己的插件吗？
A. 可以。放入一个 .claude-plugin/plugin.json（清单文件）和一个 skills/…/SKILL.md，然后用 claude --plugin-dir ./your-plugin 不安装即测试。要发布，只需在一个 git 仓库的根目录放上 .claude-plugin/marketplace.json；用户用 /plugin marketplace add owner/repo 添加。请记住：.claude-plugin/ 里只放 plugin.json——skills/ 等放在根目录。

Q. 版本管理是怎么运作的？
A. 按以下顺序解析：plugin.json 中的 version →（否则）marketplace 条目中的 version →（再否则）git commit SHA。如果你设置了 version，那么只有当你提升它时更新才会送达用户，因此要每次发布都提升它（否则用户会停留在旧版本）。省略 version，则每次提交都是一个新版本。发布前用 claude plugin validate . 进行验证。

Q. 第三方插件安全吗？
A. 并非无条件安全。官方文档指出，插件"可以你的权限执行任意代码"，并且 Anthropic 不会验证第三方插件或其内置的 MCP。只安装来自可信发行方的插件，若不确定就审查其代码。组织可以用 strictKnownMarketplaces 限制允许的来源（设为 [] 可完全锁定）。