Claude Code 插件市场开发及注意事项：从 marketplace.json 到 plugin.json 的配置骨架与 git-subdir 验证

1. 从零搭一个 Claude Code 插件市场先搞清楚它到底在解决什么问题Claude Code 的插件市场marketplace本质上是一个 Git 仓库里面放着一份marketplace.json作为索引再按约定把每个插件塞进独立子目录。用户通过/plugin marketplace add把这个仓库挂进来再用/plugin install 插件名市场名安装具体插件。它解决的问题很直接团队内部想共享 hooks、skills、脚本又不想让每个人手动拷贝目录、改配置那就用一个仓库统一分发。适合谁如果你正在做团队级 Claude Code 能力沉淀比如统一代码规范检查 hook、共享某个业务领域的 skill、把常用脚本打包成插件这套结构就是为你准备的。我试过把一个仓库拆成三个插件分别维护最后发现配置骨架没搭对安装时一直报找不到插件所以这篇把marketplace.json、plugin.json、git-subdir三件事一次讲透。核心检索词先摆出来Claude Code 插件市场、marketplace.json、plugin.json、git-subdir。这四个词贯穿全文你跟着目录结构和配置片段走一遍本地就能跑通加载与校验。2. TaoToken 前置把模型接入和插件调试串起来插件市场本身是本地 Git 仓库的事但插件里的 hooks、skills 最终要调用模型能力调试阶段你大概率需要一个稳定的 API 入口。TaoToken 在这里的角色是提供模型调用通道让你在验证插件行为时不用来回切换配置。官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址https://taotoken.net/api这个不加 UTM直接用于配置如果你只是想让插件里的脚本能调通模型先去控制台拿一个 API Key控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite拿到 Key 之后插件里的脚本或 hook 就可以通过https://taotoken.net/api这个 base URL 发起请求。注意插件市场配置和模型接入是两条线不要混在一起市场配置管的是「插件从哪来」模型接入管的是「插件跑起来调谁」。把这两件事分开排障时思路会清晰很多。如果你后续要做长期编码或 Agent 类插件可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite想先验证模型对话行为用模型对话页快速试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite接入文档在这里配置参数以文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite3. 可复制配置目录结构、marketplace.json 与 plugin.json 骨架3.1 目录结构长什么样一个 Git 仓库可以包含多个插件每个插件放在plugins/下的独立子目录。推荐结构如下marketplace-repo/ ├── .claude-plugin/ │ └── marketplace.json # 市场定义唯一必需的索引文件 ├── plugins/ │ ├── plugin-a/ │ │ ├── .claude-plugin/ │ │ │ └── plugin.json # 插件 A 的元信息 │ │ ├── hooks/ │ │ ├── scripts/ │ │ └── skills/ │ ├── plugin-b/ │ │ ├── .claude-plugin/ │ │ │ └── plugin.json │ │ └── skills/ │ └── plugin-c/ │ ├── .claude-plugin/ │ │ └── plugin.json │ └── scripts/ └── dist/ # 打包输出目录可选关键点.claude-plugin/marketplace.json在仓库根目录每个插件的.claude-plugin/plugin.json在各自子目录里。两层.claude-plugin不要搞混这是最常见的目录层级错误。3.2 marketplace.json 怎么写市场只需要一个配置文件放在仓库根的.claude-plugin/marketplace.json{ name: my-marketplace, plugins: [ { name: plugin-a, source: ./plugins/plugin-a, description: 插件 A统一代码规范检查, version: 0.0.1 }, { name: plugin-b, source: ./plugins/plugin-b, description: 插件 B业务领域 skill 集合, version: 0.0.1 } ] }source用相对路径即可无论本地安装还是远程安装都适用。不需要额外创建marketplace-remote.jsonClaude Code 会先 clone 仓库再基于 clone 后的本地目录解析相对路径。3.3 plugin.json 怎么写每个插件必须有.claude-plugin/plugin.json定义插件元信息{ name: plugin-a, version: 0.0.1, description: 统一代码规范检查插件, author: your-team, hooks: ./hooks, skills: ./skills }name要和marketplace.json里注册的名字一致否则安装时会报找不到。hooks、skills指向插件内的相对目录按你实际结构填。3.4 安装与本地调试命令用户安装是两步# 1. 添加市场源一次性 /plugin marketplace add gityour-git-server.com:org/marketplace-repo.git # 2. 安装具体插件 /plugin install plugin-amy-marketplace本地开发调试时直接把路径指过去/plugin marketplace add /path/to/local/marketplace-repo /plugin install plugin-amy-marketplace本地路径方式适合改完配置立刻验证不用 push 到远程。4. git-subdir 机制与验证请求确认插件真的被正确提取4.1 git-subdir 到底做了什么当用户通过 Git URL 添加市场后安装插件时 Claude Code 使用 git-subdir 机制流程是clone 整个仓库到本地缓存定位到插件子目录比如plugins/plugin-a提取该子目录作为插件内容安装这就是「一个仓库、多个插件」能工作的原因。你不需要为每个插件单独建仓库source的相对路径就是子目录定位依据。4.2 验证插件是否加载成功添加市场后先确认市场被识别/plugin marketplace list应该能看到my-marketplace。然后安装插件/plugin install plugin-amy-marketplace安装完成后检查插件目录是否被正确提取。本地调试时可以直接看缓存目录确认plugin.json被读取、hooks和skills目录存在。如果插件里有 hook 脚本触发一次对应操作观察脚本是否执行。4.3 SSH 与 HTTPS 的踩坑与 insteadOf 修复这是最容易卡住的地方。现象对照协议marketplace addplugin installHTTPS认证失败内网 Git 平台不支持匿名 HTTPS-SSH成功报错地址被转换为错误的 HTTP URL根因是 Claude Code 在处理 git-subdir 源时会内部将 SSH 地址转换为 HTTP 地址进行 clone。如果内网 Git 平台的 HTTP 服务返回重定向或格式不兼容clone 就失败。转换链路大致是gitserver.com:org/repo.git ↓ Claude Code 内部 SSH→HTTP 转换 http://server.com/org/repo.git ↓ 平台 HTTP 重定向 http://other-domain.com/path/org/repo.git ← 不可用解决方案是用 Git 的insteadOfURL 重写机制把错误的 HTTP 地址拦截并替换回 SSHgit config --global url.gityour-git-server.com:.insteadOf http://redirected-domain.com/path/原理是 Git 在发起网络请求前先检查 URL 是否匹配insteadOf规则匹配则做前缀替换输入: http://redirected-domain.com/path/org/repo.git 匹配: http://redirected-domain.com/path/ 替换为: gityour-git-server.com: 结果: gityour-git-server.com:org/repo.git ← 走 SSH正常工作注意三点这条规则每个团队成员都要配置一次建议写进 README 的前置配置步骤只做前缀替换后面的路径部分原样保留。5. 本篇常见错排查5.1 marketplace.json 和 marketplace-remote.json 都需要吗不需要。只保留marketplace.json即可。Claude Code 通过 Git URL 添加市场时会先 clone 仓库然后读取marketplace.json其中的相对路径基于 clone 后的本地目录解析。多建一个 remote 文件反而容易造成索引混乱。5.2 安装时报找不到插件先查三处marketplace.json里plugins数组是否注册了该插件source相对路径是否指向真实存在的子目录插件子目录下是否有.claude-plugin/plugin.json。这三处任一缺失都会导致安装失败。5.3 HTTPS 认证失败怎么办如果内网 Git 平台不支持匿名 HTTPS clone直接用 SSH 地址加insteadOf配置方案。不要试图在 HTTPS 上反复试认证方向不对。5.4 更新插件后用户怎么拿最新版把代码 push 到 Git 仓库后用户重新执行/plugin install即可拉取最新版本。如果用户本地有缓存确认缓存刷新后再安装。5.5 发布前 Checklist插件目录下有.claude-plugin/plugin.jsonmarketplace.json中已注册该插件代码已 push 到远程 Git 仓库README 中包含前置配置说明如需要insteadOf团队成员已配置 Git URL 重写规则6. 继续把插件跑通模型接入与文档入口插件骨架搭好、本地加载验证通过之后下一步就是让插件里的 hooks 和 skills 真正调通模型。这时候你需要一个稳定的 API 入口把 base URL 配成https://taotoken.net/apiKey 从 API Keys 页面拿https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite配置参数和接入细节以官方文档为准遇到请求格式、鉴权头、模型名这类问题先翻文档再动手改https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你要验证插件里某个 skill 的对话行为是否符合预期用模型对话页快速试一轮比在插件里反复触发要快https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite长期做编码类或 Agent 类插件Coding Plan 的额度模型更适合持续调试https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite最后提醒一句insteadOf规则只做前缀替换路径部分原样保留配错前缀会导致所有 Git 请求被错误重写。配完先用git ls-remote验证一次再让团队铺开。