Claude Code插件市场搭建指南：从JSON目录到Git分发实践-北京尧图网络

说实话我最初接触Claude Code 插件市场这个概念时下意识以为要搭一个类似 VS Code 插件商店的网页平台要设计推荐算法、审核后台、用户体系那一整套。真正动手做下去才发现事情远没有那么复杂但也没有那么简单。Claude Code 的插件市场本质上是一份可订阅的 JSON 目录配上一套约定好的插件目录结构和分发约定就能把团队里反复手工完成的技能包、脚本模板、提示词工程统一打包通过一条命令分发给所有人。这篇文章想把我最近搭建一个内部插件市场的完整过程写下来覆盖市场机制拆解、marketplace 清单编写、SKILL 与 PLUGIN 的从零手写、Git 仓库托管分发、权限边界治理以及我在实际使用中踩过的坑。如果你正在纠结怎么让团队所有人一键用上同一套 Claude Code 技能或者只是想给自己维护一套常用插件这套流程可以直接抄作业。1. 先搞明白市场机制不是应用商店是可订阅的目录在动手写代码之前我花了整整一个下午去理解 Claude Code 的插件市场到底是怎么工作的。把这个问题搞透后面所有设计决策都会有依据。1.1 一条安装命令背后的完整链路当用户在 Claude Code 会话中执行类似下面这样的命令时/plugin marketplace add 你的市场地址 /plugin install 插件IDClaude Code 端到端做了这些事情拉取市场清单根据输入的 URL 请求一份 marketplace 描述文件通常是一个 JSON这就是整个市场的总目录。解析插件索引从 JSON 中提取插件列表每个插件条目里包含 ID、名称、版本、相对路径等信息。对比本地已安装列表检查目标插件是否已经存在如果已存在还会对比版本号判断是否需要更新。按路径拉取插件内容根据清单中声明的 path 字段从市场仓库/服务中拉取该插件目录下的全部文件。写入本地配置和缓存插件元数据被记录到 Claude Code 的配置目录脚本和配置文件进入对应的插件缓存路径。当前会话重新加载新安装的技能或插件通常需要重新加载会话才能被 AI 识别并调用。把这个链路走通之后一个很重要的认知出现了市场仓库本身并不运行任何东西它只是扮演了一个分发源的角色。Claude Code 客户端负责拉取、解析、安装、调用市场仓库只需要保证文件能被稳定访问到就行。1.2 为什么市场机制适合用 Git 仓库承载想明白安装链路后第二个问题就是我的市场文件放哪。我对比过几种方案自建服务器、对象存储静态托管、Git 仓库。最终选了后者理由非常朴素版本管理天然完整每次修改都有提交记录出问题可以直接回滚到上一个可工作的 commit。分支天然对应环境main 分支当作线上稳定版dev 分支当测试版不需要额外搭环境隔离。协作门槛低团队成员本身就熟悉 Git改一个插件技能本质上就是一次普通的 PR不需要学习新的发布工具。拉取自带提速主流 Git 托管平台对仓库内静态文件的直接访问都有 CDN 加速个人和小团队完全够用。所以我的结论是市场机制和 Git 仓库是一对天然搭档。你不需要先搭一个应用商店后端一个普通的 Git 仓库配上规范的目录结构就是合格的插件市场。2. 搭一个最小可用市场目录规划与 marketplace 清单理解了机制之后我做的第一件事不是写插件而是先把市场的骨架搭起来。一个最小的市场由一个仓库、一个清单文件和若干插件目录组成。2.1 推荐的仓库目录布局我最终整理出的结构是这样的claude-marketplace/ # 市场仓库根目录 ├── marketplace.json # 市场清单描述整个市场的插件索引 ├── README.md # 使用说明安装命令、更新方式、注意事项 ├── plugins/ # 所有插件包目录 │ ├── meeting-notes/ # 第一个插件会议纪要技能 │ │ ├── SKILL.md # 技能描述文件 │ │ └── scripts/ │ │ └── summarize.sh # 配套脚本 │ └── log-sniffer/ # 第二个插件日志排查工具 │ ├── plugin.json # 插件描述文件声明入口和权限 │ └── bin/ │ └── run.js └── scripts/ └── verify-market.js # 本地校验脚本发布前检查清单和目录这套结构有几个好处。marketplace.json只管索引不负责具体逻辑每个插件独占一个目录权限、依赖、文档都收拢在插件自己的领地内最外层放一个校验脚本可以在 CI 里跑也可以在本地发布前跑防止把错误的清单推到线上。2.2 marketplace.json 字段逐项说明市场清单是这个仓库里最重要的文件。下面是我在项目中实际使用的完整结构{ name: 示例团队内部插件市场, schema: cli-plugin-marketplace, owner: { name: 某开发团队 }, plugins: [ { id: meeting-notes, name: 会议纪要整理技能, version: 0.1.0, path: plugins/meeting-notes, description: 把杂乱会议记录整理成结构化待办, type: skill }, { id: log-sniffer, name: 日志排查工具, version: 0.2.0, path: plugins/log-sniffer, description: 快速定位错误日志中的关键堆栈, type: plugin } ] }各个字段的含义和使用要点字段说明注意点name市场名称用户在已添加市场列表中看到的名字建议带团队/产品标识避免重名schema清单格式标识用于客户端识别保持统一不要随意改动owner.name维护方名称主要用于展示非鉴权字段不要存放敏感信息plugins[].id插件唯一标识安装命令中直接使用全市场内必须唯一安装后基本不可变plugins[].path插件目录在仓库中的相对路径必须从仓库根目录计算不要用绝对路径plugins[].version语义化版本号用于更新判断每次修改插件后都要递增plugins[].type插件形态通常为skill或plugin不同形态的加载方式不同这里有一个很容易忽略的坑path字段的大小写和层级必须和仓库里真实目录完全一致。我见过有人把目录建成了Plugins/MeetingNotes清单里写plugins/meeting-notes结果 Linux 环境的安装每次都报文件找不到排查了半天才发现是大小写问题。2.3 用分支区分开发、测试、生产三个市场市场搭起来以后另一个值得一开始就做好的设计是环境隔离。我的做法是在同一个仓库里维护多个分支dev分支给开发者自己折腾用插件写得半成品就推上来不影响别人。stable分支合并验证过的改动团队内部小范围试用。main分支对外发布的稳定市场只有通过验证的插件才能合入。分支的对应关系在使用说明里写清楚就行开发环境市场https://example.com/your-repo/raw/dev/marketplace.json 测试环境市场https://example.com/your-repo/raw/stable/marketplace.json 生产环境市场https://example.com/your-repo/raw/main/marketplace.json第一次做的人可能觉得这是过度设计但我的体验是一旦开始有第二个使用者分支隔离就能救你很多次。我曾有一次把测试中的插件直接推到了 main结果同事一安装就报错如果当时有 stable 分支缓冲这个事故完全不会发生。3. 从零创建第一个可分发插件SKILL 和 PLUGIN 的完整手写过程市场骨架搭好之后下一步就是让市场里有东西可分发。Claude Code 的插件世界里最常见的两种形态是 SKILL 和 PLUGIN。我建议所有新手先从 SKILL 入手因为它简单直接上手成本最低。3.1 SKILL 和 PLUGIN 到底怎么区分先给一张对比表帮你快速建立概念维度SKILL技能PLUGIN插件形态Markdown 描述可选脚本/资源程序入口声明式配置文件定位教 AI按这套流程做某件事给 AI 一个可调用的程序工具适合场景提示词模板、操作流程规范、简单脚本封装文件读写、日志分析、调用外部服务等有逻辑的活编写难度低会写 Markdown 就会中需要写代码和声明权限权限控制依赖 AI 的通用权限体系可以在插件内声明细化权限一句话总结SKILL 是说清楚怎么做PLUGIN 是真正动手做。你的技能如果只是需要一套溯流和步骤规范那就用 SKILL如果需要读取文件、执行分析、调用网络接口那就得写 PLUGIN。3.2 一个最小可运行的 SKILL 示例我以会议纪要整理这个场景为例展示一个完整的 SKILL 包。目录结构如下plugins/meeting-notes/ ├── SKILL.md └── scripts/ └── summarize.shSKILL.md是这个技能的核心描述文件Claude Code 的 AI 会读取它来理解技能的使用场景和执行步骤--- name: meeting-notes description: 将一段杂乱的中文会议记录草稿整理为结构化会议议题、讨论过程和行动项。适用于会议结束后快速产出纪要不适合用来处理代码评审记录。 --- # 会议纪要整理技能 ## 适用场景用户给出一段口语化、顺序混乱的会议记录需要整理成规范的会议纪要。 ## 执行步骤 1. 阅读用户提供或粘贴的原始记录文本。 2. 提取主要议题按主题分组而不是保持原文时间顺序。 3. 对每个议题总结以下三个部分 - 背景与讨论过程 - 明确结论 - 待办事项及负责人 4. 在最后汇总一份负责人-截至时间-事项表格。 ## 注意事项 - 如果原始记录中没有人名使用参会者A/B等占位称呼。 - 不要自行补充未在原文出现的结论。 - 输出的行动项必须标注是否在原文中明确提到截止时间。这里的 frontmatter 中name和description是必须的其余为辅助。description要写清楚这个技能适合做什么不适合做什么这一点在真实使用中极其重要。AI 在决定是否使用技能时就是依据这段描述做判断。描述写得太宽泛会出现不该用的时候用了的错误。脚本文件scripts/summarize.sh可以很简单比如一个帮助整理草稿文本的工具#!/bin/bash # 简单的清理脚本去掉空行、统一换行符 # 实际使用时文本整理主要交给 AI 的 Markdown 输出能力 if [ -z $1 ]; then echo 用法: summarize.sh 原始记录文件 exit 1 fi sed /^[[:space:]]*$/d $1 | tr -d \r | tee /tmp/meeting-notes-cleaned.txt echo 清理完成临时文件位于 /tmp/meeting-notes-cleaned.txt你可能会问为什么一个 SKILL 还要配脚本我的体会是AI 擅长理解和生成文本但一些确定性的文本处理工作用脚本更可靠。让 AI 用 Bash 权限去调脚本做机械操作再让 AI 自己专注做归纳总结各得其所。3.3 一个带权限声明的 PLUGIN 示例当技能需要做更复杂的处理时就得写 PLUGIN 了。我以日志快速定位为例展示plugin.json的核心写法{ id: log-sniffer, name: 日志排查工具, version: 0.2.0, description: 读取指定日志文件提取 ERROR 级别记录并输出最近的堆栈片段, entry: { command: node, args: [bin/run.js] }, permissions: [ { type: read }, { type: bash, allowed: [tail, grep, awk, head] } ] }这里的逻辑很清晰entry告诉 Claude Code 如何启动这个插件程序permissions声明这个插件运行时会使用哪些权限。注意bash权限里我用了allowed做了细化只允许tail、grep这类命令而不是放开全部 Bash。对应的bin/run.js是一个抽象化的最小实现#!/usr/bin/env node const fs require(fs); const path require(path); const logPath process.argv[2] || (process.cwd() /app.log); if (!fs.existsSync(logPath)) { console.error(日志文件不存在: logPath); process.exit(1); } const lines fs.readFileSync(logPath, utf8).split(\n); const errors lines.filter(line line.includes(ERROR)); // 这里只做简单的抽象演示真实场景会追加上下文提取和格式化 console.log(发现 ERROR 日志 errors.length 条); errors.slice(-20).forEach(line console.log([ERROR] line));在真实项目中这个入口文件会做更多事情比如解析参数、处理文件路径、格式化输出但在插件市场的语境下你只需要保证程序能被 Claude Code 正常调用即可。我建议把程序逻辑和输出格式分开程序只保证稳定输出结构化信息最终呈现给用户的报告由 AI 基于输出生成。3.4 登记插件到市场清单并本地验证写好了插件包还差最后一步把它登记进marketplace.json然后做本地验证。我的标准流程是把插件目录完整放入仓库的plugins/目录。在marketplace.json的plugins数组里增加对应条目确认 ID、版本、路径都正确。推送到 Git 仓库后在命令行执行市场添加和插件安装命令。在 Claude Code 会话中触发对应的技能确认 AI 能正确描述和使用技能。如果技能涉及脚本先在终端手动执行一次脚本确认脚本本身没有问题再让 AI 去调用。这段流程最核心的教训是永远先让脚本能独立工作再指望 AI 会用。我曾经跳过这一步直接把一个带 bug 的脚本包成了技能结果 AI 输出得头头是道但实际执行脚本时报错浪费了很多调试时间。4. 分发链路设计托管方式、更新订阅与完整性校验市场清单和插件包都就绪后剩下的核心问题就是如何把东西安全可靠地送到用户手里。分发链路设计得好不好直接决定了用户是否愿意长期使用。4.1 托管方式选型对比我把实际评估过的几种托管方式整理成了表格托管方式优点缺点适用场景公开 Git 仓库免费、协作方便、天然版本管理公开仓库所有文件任何人都能拉取个人开源技能包、社区分享私有 Git 仓库访问受控、适合团队内部拉取时可能需要访问令牌处理团队内部市场、公司规范技能内网静态文件服务完全内网隔离、拉取速度快需要额外维护一台服务企业内网环境、敏感项目对象存储静态托管支持 CDN、回源方便文件更新后要手动同步公开市场、内容分发网络要求高对小团队和个人来说我的推荐排序是这样的优先用私有 Git 仓库其次是公开仓库尽量不要一开始就自建服务器。等插件数量真正多到需要统计用户、监控拉取量的时候再考虑上更重的分发平台也不迟。4.2 更新订阅机制为什么用户总是用了旧版本Claude Code 的插件更新机制本质上是一个订阅-同步模型。用户添加市场后客户端会按一定策略拉取最新的marketplace.json然后对比本地插件版本和清单中的版本。只有当版本号发生变化时才会重新拉取插件目录内容。这带来一个非常现实的痛点如果每次改动都忘记递增版本号用户那一侧压根不知道有新版本。我第一次发布时改完插件忘了改 version结果同事那怎么刷新都还是旧技能。后来我养成了一个强制习惯插件有任何文件变动version必须同步递增并且递增前先更新插件目录里的更新说明文件。另外如果你发布的插件涉及脚本或程序文件我建议在插件目录里放一个 CHANGELOG.md记录每次版本变更的内容。对用户来说看到清晰的变更记录会大幅提高对市场的信任度。4.3 团队私有市场的额外安全考量团队内部市场和个人市场有一个质的区别使用者不是自己出了问题是别人的时间成本。所以在分发设计上要更严格。私有仓库场景下我遇到的一个问题是拉取时的访问控制。直接把私有仓库地址当作市场 URL 给人用会遇到没有权限拉取的报错。我采用的方案是在 CI 中配置一个只读访问令牌由 CI 负责将最新插件同步到一个平台内置的发布文件区域团队成员直接从那里拉取。这样既保证了原始仓库的代码安全又保证了插件分发路径的稳定。4.4 防篡改与完整性校验分发链路中还有一个经常被忽略的问题你给用户的插件文件是否和仓库里的一致在公开网络环境下如果使用第三方托管服务理论上存在文件被替换的风险。我的做法是在 CI 中加入一个校验步骤生成插件目录文件的哈希清单和市场清单一起发布。例如{ name: 示例团队内部插件市场, schema: cli-plugin-marketplace, owner: { name: 某开发团队 }, checksums: { meeting-notes: sha256:该插件目录的整体哈希, log-sniffer: sha256:该插件目录的整体哈希 }, plugins: [] }虽然这个方案不能替代客户端一侧的完整校验机制但至少为使用者提供了一个可审计的完整性锚点。对安全要求高的团队来说分发的可审计性比分发速度重要得多。在生成环境里CI 脚本会对plugins/下每个目录递归计算哈希并在发布时自动写入清单文件人只需要审核改动即可。5. 权限边界与运行时安全做市场的底线插件市场最危险的地方恰恰在它的便利性上。一个插件包如果没有合理的权限边界和一段拿到你的授权就能执行任意命令的脚本没区别。这部分我花的时间最多踩过坑也最多。5.1 插件权限模型的基本认知一个插件在市场中被安装后它获得的是 Claude Code 会话中的一部分能力边界。核心权限可以归纳为几类读取权限访问会话当前目录或指定路径下的文件内容。编辑权限创建、修改文件注意这比读取危险得多。Bash 权限执行终端命令危险等级随命令差异巨大。网络权限发起 HTTP 请求可能导致数据外传。扩展权限访问 Claude Code 的一些高级能力通常默认不开放。我需要特别强调一个认知权限不是只有有和没有两级Claude Code 的交互机制里用户在执行特定操作时通常会有确认环节。但依赖用户每一回都认真看确认提示在长期使用中是不可靠的。所以插件设计者的责任是把权限需求压到最低。5.2 最小权限原则一个反面案例为了说明最小权限原则我举一个真实教训。某次为了做一个从错误日志中提取 IP 频率的插件我图省事申请了bash的全部权限没有做allowed限制。结果有一次 AI 在输出建议时把一段复杂的awk命令拼接错了执行时报了很诡异的结果。排查到最后根本问题是我给了 AI 一把斧头本意是让它用斧头的背面钉钉子但 AI 意识不到自己在用什么工具。正确的做法是把能用代码完成的逻辑尽量在插件程序内完成把 Bash 权限限制在白名单命令上并且明确每个命令的用途。比如上面那个日志统计任务完全可以在 Node 程序内部读取文件、解析 IP、统计频率最后只声明一个read权限就够了。5.3 自动化安全扫描把风险挡在发布前团队市场大了以后就不能指望每个插件作者都自觉遵守规范。我加了一段发布前自动扫描的 CI 步骤检测几类典型的危险模式# 在 CI 校验脚本中检查危险模式 grep -rniE curl .*\|.*(sh|bash)|wget .*\|.*(sh|bash) plugins/ echo 发现可疑管道执行 exit 1 grep -rniE rm -rf[[:space:]]/ plugins/ echo 发现危险删除命令 exit 1 grep -rniE base64 -d[[:space:]] plugins/ echo 发现可疑解码执行 exit 1 grep -rniE (api[_-]?key|token|secret)[[:space:]]*[:][[:space:]]*[\][A-Za-z0-9]{16,} plugins/ echo 发现疑似硬编码密钥 exit 1这组检查并不复杂但能把最几类灾难性操作挡在门外。CI 扫描的作用是让危险的修改无法合并到stable和main分支相当于一条强制性的安全门禁。5.4 团队治理里最容易忽视的细节技术手段之外团队治理层面还有几个容易被忽视的细节。第一插件作者不应该有直接合并到发布分支的权限至少要有另一个人审查改动再合并第二不要在主市场同一目录里同时开发多个插件再一次性提交每个插件的变更应当独立成提交出问题能单独回滚第三定期梳理已发布插件长期没维护的插件要从市场清单中下架保持清单整洁。6. 我踩过的坑和给新人的排错清单最后这部分是我最想写的内容。从搭建市场到真正让团队稳定使用中间踩过的坑比想象中多。我把遇到过的典型问题整理成一份排错清单希望你能直接避开。6.1 技能装了但不生效这个问题我有段时间频繁遇到原因五花八门。最常见的是插件 ID 与本地残留冲突尤其是同一个插件从旧市场迁移过来本地还有旧记录其次是marketplace.json中插件条目的name和 SKILL.md 中 frontmatter 的name不一致导致安装成功了但 AI 加载时识别不到还有一个不常想到的原因是大小写不一致。我的排查顺序固定为先查marketplace.json中该插件条目的 ID、path 是否正确再查插件目录内 SKILL.md 或 plugin.json 的名称字段是否与条目一致最后把插件完全卸载重装一遍。这个顺序能覆盖九成的情况。6.2 版本更新了但用户侧一直是旧的这个问题在 4.2 节已经提到了根源就是版本号没变或者用户侧存在本地缓存。版本号问题靠流程约束解决缓存问题我后来总结出两个缓解手段发布时在插件目录内放一个当前版本的标记文件用户判断我到底是不是最新版时能快速确认。在更新说明里明确提示用户如果怀疑缓存干扰执行一次强制重装而不是反复刷新市场。6.3 权限提示反复弹出烦到用户不想用如果插件声明了bash权限但没做细化AI 每次执行命令时都可能触发系统级授权确认用户的体感是这个破插件怎么天天要权限。我后来对插件做了一轮大改造把能收进程序内部的逻辑全部收进程序只保留最核心的白名单命令。改造完之后授权提示频率下降了一个量级用户体感明显变好。6.4 脚本在本地能跑在 Claude Code 里乱跑这个坑几乎人人都要撞一次。原因是Claude Code 执行插件脚本时工作目录和你的开发目录大概率不一样。脚本里一旦用了相对路径比如./data.txt在会话环境中就会找不到文件。我的解决办法是所有脚本路径都以插件目录为基准计算不依赖当前工作目录涉及环境差异的判断逻辑尽可能健壮比如先用which检查命令是否存在。6.5 多人协作时市场文件的脏更新当团队规模超过三个人同时维护同一份marketplace.json就会开始出现冲突A 加了新插件B 在改另一个插件的版本号两个人同时推上去清单就花了。我的经验是尽量让市场清单的变更都由 CI 脚本生成人工只负责维护插件目录本身。这样marketplace.json永远是被程序算出来的状态而不是被手工编辑出来的状态冲突概率大幅下降。做插件市场这件事回头看我最大的收获不是搭好了一个平台而是把团队的隐性知识真正沉淀成了可分发、可更新的资产。最后分享两个我一直在用的小习惯第一无论 SKILL 还是 PLUGIN都写清楚什么时候不要用给 AI 设置边界比鼓励它勇敢使用更有价值第二每次发布插件后在目录里留一个简短的变更记录不光是给别人看的也是给一个月后的自己看的。插件市场的价值能在风吹草动的时候帮你稳定住一套已经被验证过的方法论这种确定性本身就是最大的效率。

Claude Code插件市场搭建指南：从JSON目录到Git分发实践

相关推荐

lingbot-map实战：机器人导航地图的格式统一与坐标对齐

端侧AI推理实战：边缘计算与硬件落地的关键路径

MATLAB穷举搜索法：可调试的数值优化基准实现

更多资讯

sentry_drift鸿蒙化适配：Flutter数据库级性能追踪

VS Code 高效开发实战：从安装配置到插件调试完整指南

AI调度官真的能管好团队？从拆目标到团建的三周实测拆解

智能体技能体系设计：从提示词到可复用能力单元

GPT-4o API接入实战：认证、流式输出与工程优化全攻略

CactiEZ实战：华为、H3C、中兴交换机SNMP监控模板导入与排错

今日更新

微信云开发旅游小程序实战：LBS打卡+UGC社交全栈方案

金融AI代理平台核心拆解：从多代理协作到财报分析实战

基于大数据的智慧旅游推荐与可视化平台架构实践

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？