Claude Code 自己写一个插件并发布到 marketplace：plugin.json、marketplace.json、validate 到团队安装的完整流程

本文根据 Claude Code 官方文档《Create a Claude Code plugin》《Publish a plugin》《Create a marketplace》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。本站（bigolab.com）不是 Anthropic 官方网站。

适用于谁

• 已经有自己的 Skill、子智能体或 Hook，想打包后让团队一条命令装上的人；
• 想知道「插件」「marketplace」到底是什么关系、怎么自己建一个的人。

怎么安装别人的插件，站内已有 /guides/claude-code-plugins-marketplace；本文讲自己做、自己发。

结论先说

1. 插件 = 一个目录 + 一份清单。 官方定义：插件是一组 Skill、子智能体、Hook、MCP 服务器的目录，外加 .claude-plugin/plugin.json（清单），Claude Code 把它当作一个整体加载。
2. 什么时候值得做成插件。 官方说，只给自己或一个项目用，保留 .claude/ 里的独立配置就行；想与团队共享、装进多个项目或发布带版本的发行版，再做插件。
3. 插件里的 Skill 命令带前缀。 例如 /my-first-plugin:hello，所以两个插件都有 hello 也不会冲突。
4. marketplace 就是一个 Git 仓库里的 .claude-plugin/marketplace.json。 官方说文件进了仓库，插件就算发布了，没有提交表单；仓库私有，市场就是私有的。
5. 改了代码但没改 version，用户收不到更新。 这是官方特别提醒的坑。

图：本站根据 Claude Code 官方文档：Create a plugin 整理的示意图

一、目录结构和 plugin.json

下面用一个演示插件 db-guard，里面装站内另一篇讲过的 migration-review Skill（见 /guides/claude-code-write-own-skill-auto-trigger）。官方规定每类组件放在固定位置：

text
db-guard/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── migration-review/
│       ├── SKILL.md
│       └── scripts/check.sh
├── agents/            # 可选：子智能体，每个一个 .md
├── hooks/hooks.json   # 可选：Hook 配置
└── .mcp.json          # 可选：MCP 服务器

官方特别强调：.claude-plugin/ 里只放 plugin.json，把 Skill 放进去不会加载；插件根目录是它自己的目录，不是 ~/.claude/。

bash
mkdir -p db-guard/.claude-plugin db-guard/skills

db-guard/.claude-plugin/plugin.json（字段来自官方示例）：

json
{
  "name": "db-guard",
  "description": "数据库迁移检查：Skill 与检查脚本",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

官方对字段的说明：name 必填，会成为插件里每个 Skill 和子智能体的前缀，不要有空格；description 是用户在 /plugin 里看到的文字；version 可选，设置后用户停留在该版本，直到你改它；author.name 必填（若写了 author）。

二、把已有配置搬进插件

如果你已经有 .claude/ 下的配置，官方的迁移做法是复制：

bash
cp -r .claude/skills db-guard/
cp -r .claude/agents db-guard/      # 没有就跳过
cp -r .claude/commands db-guard/    # 没有就跳过

Hook 要把 .claude/settings.json 里的 hooks 对象复制进 hooks/hooks.json，格式相同，外面包一层顶层 "hooks" 键。官方提醒两点：

• 迁移期间原来的 .claude/ 还在，Skill 和子智能体因为带前缀不会冲突，但 Hook 没有前缀，两处都有会各跑一次；确认插件好用后，删掉原件并从设置里移除 hooks。
• 脚本路径在 Hook 命令和 MCP 配置里要写成 ${CLAUDE_PLUGIN_ROOT}/...，官方说 validate 会报告不是 ./ 开头的组件路径。

三、验证和本地试跑

官方在发布前建议的三步：

bash
claude plugin validate ./db-guard
claude --plugin-dir ./db-guard

第一条会检查清单和 Skill 的 frontmatter，通过时最后一行是 ✔ Validation passed；失败时每条消息会指出要改的字段。第二条只在这次会话里加载插件，不写入你的设置。进去后运行带前缀的命令：

text
/db-guard:migration-review

边改边测时，官方说在会话里运行 /reload-plugins 加载改动。发布前再用 claude plugin validate --strict ./db-guard，它会把「未知字段」「缺少 version」之类的警告也当失败（退出码 1），适合放进 CI。

四、写 marketplace.json 并推到 Git

官方给了最省事的发布方式：插件自己的仓库里就放一份市场文件，位置在 .claude-plugin/marketplace.json，source 写 "./" 表示仓库根：

json
{
  "name": "acme-tools",
  "owner": { "name": "Your Name" },
  "plugins": [
    { "name": "db-guard", "source": "./" }
  ]
}

规则（来自官方）：

• 市场的 name 要起得别人不容易重名，因为一个用户不能装两个同名市场；
• 条目的 name 要和 plugin.json 里的 name 一致，否则按清单名安装会报 Plugin "<manifest-name>" not found in marketplace；
• 相对路径从市场根目录写，不要用 ..；
• 官方保留了一批名字（例如 claude-plugins-official），添加叫这个名字的市场会被拒绝。

如果一个仓库里放多个插件，官方的目录是 my-marketplace/plugins/<插件名>/，条目 source 写 ./plugins/<插件名>。

先在本机走通一遍再推送，官方的本地回路是：

bash
claude plugin validate .
claude plugin marketplace add ./
claude plugin install db-guard@acme-tools
claude plugin list

install 的 id 是「条目名 + @ + 市场名」；list 里应看到 db-guard@acme-tools 且状态为 enabled。想从头再来，用 claude plugin marketplace remove acme-tools，它会移除市场并卸载其中的插件。然后 git push 到你的 GitHub 或其他 Git 仓库即可，官方说谁能克隆仓库谁就能安装，所以私有仓库就是私有市场。

图：本站根据官方文档整理的示意图

五、同事怎么装

官方给的几种写法，把来源和名字换成你的：

bash
claude plugin marketplace add your-org/acme-tools
claude plugin install db-guard@acme-tools

会话里也可以一条命令完成：/plugin install db-guard --marketplace your-org/acme-tools（官方标注需要 v2.1.275 或更高）；在 shell 里一步完成的写法需要 v2.1.292 或更高。安装前请同事先看看你的仓库里放了什么，原因见 /guides/agent-skills-security-audit-before-install。

六、发新版本

官方的规则是二选一：

• 每次发布都递增 plugin.json 里的 version。 如果你设了 version，之后只推提交不改版本，用户运行 claude plugin update 会看到 is already at the latest version，仍然用旧的；
• 或者在 Git 托管的市场里干脆不写 version，这时 Claude Code 用提交的 SHA 当版本。此时 --strict 会因缺少 version 报警，官方说那就去掉 --strict。

用户拿更新有两条路：自己运行 claude plugin update db-guard@acme-tools；或者为你的市场开自动更新，官方说默认是关的，由用户一侧设置。

七、要发给更多人怎么办

按官方「Publish a plugin」的对比：

提交到 Anthropic 目录需要一个 GitHub 仓库和付费的 claude.ai 方案，在开发者门户提交；官方还说本地 validate 通过不保证门户一定通过，门户有额外规则。官方的 claude-plugins-official 市场不接受通过这个门户提交。这部分流程以 claude.com 官方页面为准，本文不展开。

常见问题

Q：只想给自己用，需要 marketplace 吗？

不需要。官方说可以用 --plugin-dir，或者把带 .claude-plugin/plugin.json 的目录放到 ~/.claude/skills/ 下，之后每次启动自动加载（除非管理员禁用了）。目录优先级见 /guides/claude-code-skills-directory-location-priority。

Q：claude plugin validate 过了，安装还是失败？

官方说两者查的东西不同：validate 只读市场目录内的文件。条目的 source 指向不存在的目录时 validate 会通过，但安装时报 Source path does not exist；github、git-subdir 这类远程来源写错，也只会在安装时暴露。

Q：装好了没看到我的 Skill？

先 claude plugin details <插件名> 看 Component inventory 里有没有列出；再对照第一节的目录结构，确认 Skill 在 skills/<名字>/SKILL.md，而不是放进了 .claude-plugin/（官方说放在那里的组件不会加载）。

订阅和额度

插件里的 Skill 和子智能体运行时用的是你自己的 Claude Code 额度。订阅选择见 /chongzhi/claude-code，价格和额度以官方页面当前显示为准。

相关教程

• /guides/claude-code-plugins-marketplace：怎么安装插件、加 marketplace
• /guides/claude-code-custom-skill-slash-command-example：先写好 Skill 再打包
• /guides/claude-code-install-superpowers-plugin：一个第三方插件的安装实例

参考资料

• Claude Code 文档：Create a Claude Code plugin — https://code.claude.com/docs/en/plugins/create
• Claude Code 文档：Publish a plugin — https://code.claude.com/docs/en/plugins/publish
• Claude Code 文档：Create a marketplace — https://code.claude.com/docs/en/plugin-marketplaces