最近在帮团队整理内部沉淀的Claude Code技能库发现一个特别常见的场景Skill文件写了一堆自己用起来很顺手但真要分发给同事或者开源社区就卡住了。有人把整个项目仓库甩给对方有人手动复制.claude/skills目录还有人干脆放弃了分享。其实Claude Code早就提供了一条标准路径——把Skill打包成Plugin再通过Marketplace分发。这篇文章我就用自己的实操过程把这条路径完整走一遍包括目录结构、清单文件、本地验证、GitHub发布和后续维护尽量让新手也能照着做下来。先说明白一个前提本文默认你已经知道Skill是什么并且写过至少一个能跑通的SKILL.md。如果你连Skill怎么创建都没概念建议先到官方文档把.claude/skills目录的基础用法过一遍再回来读这篇。1. 先理清概念Skill是内容Plugin是容器Marketplace是货架1.1 Skill的真实形态很多刚接触Claude Code Skill的人会把它想象成一段特殊代码或者某种插件文件其实没那么玄。Skill的实体就是一个目录加一个Markdown文件放在项目里的.claude/skills/skill-name/SKILL.md。SKILL.md头部用YAML frontmatter声明技能的名字和描述正文就是一份用自然语言写的操作手册模型读完这份文档就会在对应场景里按文档规定的方式工作。举个例子一个简单的代码评审Skill长这样--- name: code-review description: 当用户要求进行代码评审、找bug、检查pull request时使用。 --- # Code Review Skill 本技能用于对代码变更进行结构化评审。 ## 执行步骤 1. 获取diff范围使用 git diff。 2. 按模块整理审查点逻辑错误、边界条件、性能隐患、安全隐患。 3. 输出格式按严重级别列出附修改建议和对应行号。 4. 对于每个问题给出可运行的修复示例。这个文件虽然简单但它的价值全在细节里。最关键的是description字段——模型对用户指令做意图判断时会把你所有Skill的description和用户当前请求做语义相似度匹配然后决定触发哪个Skill。所以description写的不是这是什么而是什么时候该用我。我见过不少人的Skill不好用根因从来不是正文不够详细而是description写得像论文摘要比如本技能用于提升代码质量。模型完全不知道该在什么时机匹配这段话。正确的写法要覆盖触发动词评审、查找、检查、审查和具体场景提交、合并、重构给足匹配信号。但讲到底SKILL.md只是内容。它放在自己的项目目录下别人没法按需安装也没法做版本管理。这时候就需要Plugin出场了。1.2 为什么必须Plugin化有人会说我的Skill已经能正常触发了不搞Plugin这套概念行不行。如果你永远只在自己电脑上用答案是可以。但只要你动了让更多人用上的念头问题立刻冒出来队友不知道Skill应该放哪个目录手动拷贝多了之后版本乱成一锅粥一个完整工作流往往不是单个Skill能覆盖的还有Slash Command、Agent、Hook这些入口散落各处很难管理你本地更新了技能别人本地还是旧版本出了问题会直接归咎于AI不好用想向社区开源的时候没有一种体面的安装方式别人试用成本太高传播自然起不来。Plugin在Claude Code里的定位就是标准的分发容器。它把Skills、Commands、Agents、Hooks这些能力入口统一收拢再通过一份清单文件告诉Claude Code我包含什么、入口在哪个目录。用户安装时只需要执行claude plugin install剩下的路径解析、内容加载全部由CLI完成。1.3 Marketplace是货架不是商店本身这个点特别容易混淆。我第一次听到Marketplace第一反应是Anthropic官方搞了个应用商店进去可以浏览各种各样的插件。实际不是这样。Claude Code的Marketplace本质上是一个插件索引某个Git仓库里放一份marketplace.json列出若干插件的名称、仓库地址、版本号。你执行claude plugin marketplace add owner/repo时CLI拉取这个仓库、读取marketplace.json然后看到货架上有什么可装。所以分发链路其实是三层结构角色载体作用Skill.claude/skills/skill-name/SKILL.md单个可复用的能力定义Plugin包含.claude-plugin/plugin.json的Git仓库把多个入口点打包成可安装单元Marketplace包含marketplace.json的Git仓库索引多个插件提供统一安装入口想通这三者的关系后面搭工程的时候就不会迷茫了。我自己最初就是没搞懂Marketplace和Plugin的边界结果把plugin.json和marketplace.json的角色搞混浪费了不少时间。2. 搭建Plugin工程从空目录到可安装结构2.1 目录骨架一个规范Plugin仓库核心是.claude-plugin/plugin.json外加若干entrypoints指向的目录。我建议你直接按下面的骨架来建my-plugin/ ├── .claude-plugin/ │ ├── plugin.json │ └── marketplace.json ├── .claude/ │ ├── commands/ │ │ └── review.md │ ├── skills/ │ │ └── code-review/ │ │ ├── SKILL.md │ │ └── scripts/ │ │ └── analyze.sh │ ├── agents/ │ │ └── reviewer.md │ └── hooks/ │ └── pre-commit.md ├── README.md └── .gitignore有人可能会问marketplace.json为什么放在.claude-plugin目录下因为当CLI把整个仓库当作Marketplace源读取时它默认会到.claude-plugin目录下找配置文件这和使用plugin.json识别Plugin的逻辑是一致的。两个文件各管各的事plugin.json回答我是谁、我包含什么marketplace.json回答我这个货架上有哪些插件。如果你的仓库只打算发布一个插件最简单的做法是把两个文件放同一个仓库这个仓库既是Plugin也是Marketplace。如果你打算以后维护多个插件我建议一开始就按独立市场仓库独立插件仓库来设计。市场仓库只放marketplace.json和README插件仓库才是具体功能代码所在。这样每个插件可以独立迭代版本市场仓库只负责索引更新。2.2 plugin.json逐字段拆解plugin.json是整个Plugin的门面排错时第一眼检查的就是它。下面是完整示例{ name: dev-workflow, description: 包含代码评审、测试生成和提交信息规范的开发工作流插件, version: 1.0.0, author: { name: Your Name, email: youremail.com }, repository: https://github.com/yourname/dev-workflow, entrypoints: { skills: [.claude/skills], commands: [.claude/commands], agents: [.claude/agents], hooks: [.claude/hooks] } }有几个字段要重点说。name是用户执行claude plugin install dev-workflow时使用的名字必须和Marketplace索引里登记的name完全一致大小写敏感。我踩过一次坑插件名叫dev-workflowMarketplace里手滑写成了Dev-Workflow结果plugin install直接报找不到。version建议严格遵守语义化版本规范x.y.z格式。后面更新插件时版本号是用户感知有新版本的关键信号。如果版本号不变哪怕代码改出花来用户侧升级时也会被告知已是最新版本。entrypoints声明各能力入口对应的相对路径。这里有个细节路径指向的目录不存在时CLI会静默忽略并继续加载其他部分不报严重错误。这就会导致一个迷惑现象——插件装成功了列表里也有但Skill一个都没有。所以本地验证阶段一定要把目录结构和命名固定下来不要今天用skills明天改成skill。repository字段虽然非强制但强烈建议写上。出现问题时用户可以顺着地址直接开Issue这是成本最低的反馈闭环。2.3 marketplace.json的写法与多插件管理marketplace.json决定了别人能不能在货架上看到你的插件。最小可用写法如下{ name: my-plugins, description: 我个人的Claude Code插件集合, plugins: [ { name: dev-workflow, description: 包含代码评审、测试生成与提交规范的开发工作流插件, repository: https://github.com/yourname/dev-workflow, version: 1.0.0 } ] }这里的插件的name和version必须和插件仓库中plugin.json保持一致。如果不一致常见的表现是marketplace add成功但plugin install时找不到版本号或者装下来一堆入口点都是空的。如果你维护多个插件就在plugins数组里依次追加。每次有插件发布新版本记得同步更新这里的version。我见过有人忘了这一步用户侧永远停留在旧版本还以为是插件没更新——其实索引压根没变。清单文件字段不一致的常见表现最可能的根因plugin install报找不到marketplace.json里的name或version和插件仓库不一致marketplace add成功但列表为空marketplace.json格式错误或plugins数组为空装完没有Skill/Commandentrypoints路径写错或目录命名不规范3. Skill迁移把零散技能改造成合规入口3.1 SKILL.md的frontmatter与正文规范化把已有Skill搬进Plugin不是简单拖目录。因为别人安装你的插件后你的Skill会和其他技能共存在同一个环境里冲突和误触发都会被放大。迁移时最重要的动作就是重新审视SKILL.md的元信息。frontmatter至少需要name和description。name要全局唯一尽量带前缀比如我用devworkflow-code-review而不是简单叫review。description则要承担触发决策的功能写法好坏直接影响触发准确率。这里放一个对比你们感受一下# 不好的写法 --- name: review description: 用于代码审查的技能 --- # 更好的写法 --- name: devworkflow-code-review description: 当用户要求评审代码质量、查找bug、检查安全性、审查Pull Request时使用。在代码提交、合并请求和大型重构场景下都应该考虑触发。 ---第一种写法太宽泛模型在你问这段代码有没有问题时可能触发在你问帮我把这个函数优化一下时也可能触发时机全靠运气。第二种写法给了明确的触发动词和场景约束模型更容易做精确匹配。正文部分我建议固定使用五段式结构何时使用、核心原则、执行步骤、输出格式、注意事项。体例统一之后插件里即使有七八个技能维护者也好管理模型执行时也更容易保持一致的行为模式。3.2 带脚本的技能如何组织很多实用Skill不只是一份Markdown还需要辅助脚本。比如代码评审时要拉取最近变更、统计改动行数、跑静态检查。脚本放哪、怎么被调用都是有讲究的。推荐结构是这样code-review/ ├── SKILL.md └── scripts/ └── analyze.shSKILL.md正文中要明确告诉模型脚本路径和执行方式。比如--- name: devworkflow-code-review description: 当用户要求评审代码质量、查找bug、检查安全性、审查Pull Request时使用。 --- # 代码评审 使用辅助脚本分析当前分支最近N个提交的变更内容。 ## 执行步骤 1. 运行 bash skill-dir/scripts/analyze.sh commit-count 获取变更概览。 2. 根据概览结果逐文件审查。 3. 输出问题清单按错误、警告、建议分级。对应的脚本可以是#!/usr/bin/env bash set -euo pipefail N${1:-10} git log -n $N --stat --oneline这里有个关键设计脚本路径写法必须是相对定位不能假设用户固定从某个目录启动Claude Code。我在SKILL.md里用的是skill-dir这种语义化占位实际项目中可以写成$(dirname $0)/analyze.sh这类动态解析路径的方式确保从任何工作目录都能正确执行。跨平台问题也要提前想。给Shell脚本加上执行权限chmod x在SKILL.md里写清前置依赖。我遇到过的典型翻车是Windows用户跑Shell脚本直接失败后来在文档里补了一句Windows环境请使用Git Bash或WSL运行才算消停。3.3 顺带把Slash Command和Agent也收进来Plugin的价值在于入口点不止一个。如果工作流里已经有了一些固定Prompt可以直接写成Slash Command放在.claude/commands/--- name: review-pull-request description: 对当前分支的PR进行结构化评审 --- 运行代码评审技能重点关注 1. 边界条件与空指针风险 2. 并发安全问题 3. 性能与资源泄漏 4. P0/P1问题必须给出修复代码用户安装插件后输入/review-pull-request就能触发这条命令不用重复打一大段Prompt。Agent入口的思路类似.claude/agents/agent-name.md里定义专属角色Hook则是在生命周期节点上挂自动任务比如文件写入前自动格式化。我的建议是第一版Plugin先只上Skills和Commands跑稳定了再加入Agents和Hooks。功能一多排错复杂度是指数增长的别一上来就把工程做成全家桶。4. 发布前必须完成的本地验证流程4.1 把本地目录当Marketplace挂载这是整个流程里最容易被跳过的一步。很多人写完配置直接推到GitHub结果用户装不上来回浪费好几天。其实CLI支持把本地路径当作Marketplace源完全可以在推到远程前完成全链路验证。在插件仓库根目录也就是包含.claude-plugin的目录执行claude plugin marketplace add . claude plugin install dev-workflow如果市场索引文件在子目录路径跟着写就行。marketplace add之后可以用claude plugin marketplace list确认是否挂载成功再执行plugin install验证安装。这一步跑通基本说明plugin.json、marketplace.json的格式和路径解析没有问题。具体命令名称和参数在不同版本可能略有差异以你本机claude plugin --help输出为准。整体思路是不变的先用本地路径模拟远程仓库把解析链路打通。4.2 从三个角度做冒烟测试装完之后重启Claude Code会话然后按三个层次做验证列表可见用claude plugin list确认插件状态是installed相关Skill、Command已加载。描述触发直接输入一个贴近Skill场景意图的请求比如帮我审查一下当前分支最近三个提交重点找安全问题看模型是否自动调用对应Skill。如果没反应回头检查SKILL.md里的description多半是触发信号写得不明确。脚本执行故意触发需要辅助脚本的技能确认脚本能拿到正确路径和参数输出符合预期。这三个测试对应三层解析链路插件加载层、Frontmatter匹配层、脚本执行层。任何一个环节出问题都能把范围缩小到具体文件而不是靠猜。4.3 这个阶段我见过的三个高频坑第一个坑是路径层级错位。entrypoints里的路径是相对插件仓库根目录的我见过有人写了绝对路径也有人把路径指向了不存在的目录装完一片寂静。第二个坑是版本不一致。本地测试时两个文件都写1.0.0看着没问题推到远程后忘了同步更新索引用户侧永远装不上新功能。第三个坑更隐蔽Skill的description触发范围过宽。模型在无关场景下频繁触发技能会给用户一种这个插件很啰嗦的观感。我后来用了一个笨办法把description写完后故意用几个不相关请求测试如果仍然触发就继续收窄边界。宁可少触发不要乱触发。5. 推到GitHub做正式分发5.1 仓库组织不止是代码托管分发到公网第一步是决定仓库组织方式。如果只有一个插件且Marketplace和Plugin共用仓库推上去就行用户侧只需要两条命令claude plugin marketplace add yourname/dev-workflow claude plugin install dev-workflow如果打算后续维护多个插件建议单独开一个市场仓库例如yourname/claude-plugins-marketplace里面只放marketplace.json和README。每个插件放各自仓库独立迭代版本市场仓库只负责索引。README要好好写。至少包含插件装完有什么能力、每个Skill/Command的触发方式、依赖环境Node、Python、Git Bash等、卸载方式。开源场景下README是你和用户之间的第一份契约写不清楚会让可信度大打折扣。另外一个细节.gitignore里果断把临时脚本输出、日志文件、node_modules之类的东西拒之门外。插件仓库体积越小用户安装越快潜在的冲突也越少。5.2 版本更新与用户侧体验推广后最常遇到的问题是用户装了老版本不更新。我建议每次改动都严格执行这套流程修改插件代码或Skill文件在插件仓库的.claude-plugin/plugin.json中递增version如果Marketplace仓库独立存在同步更新marketplace.json对应插件的version给插件仓库打Git tagtag名和版本号保持一致在Release说明里写清变更点。用户侧发现新版本后用claude plugin update name完成升级。如果你更新时忘了改版本号用户升级时看到已经是最新版本但实际功能没变这就是最典型的假更新问题——根本原因不是CLI不工作而是索引没更新。5.3 命名统一与可发现性最后提一个容易被忽视的点名字本身就是用户搜索你的入口。插件名、市场名、仓库名三处最好统一。我见过一个市场叫awesome-dev-tools里面插件叫wizard仓库又叫my-tools-public用户要花很大力气才搞明白三者关系。统一命名后无论用户通过搜索结果、README还是别人转发的链接进来都能一眼定位到该下载什么。命名上尽量用能表达核心作用的组合比如devworkflow-code-review而不是review-tool-final-v2这种。这看起来是小事却是真实降低用户心智负担的关键设计。6. 真实分发后的维护与体会6.1 建立反馈闭环插件分发出去了不等于事情结束。你最大的收益来自真实用户的使用反馈。我通常会在README里留一个Issue模板让用户反馈时带上版本号、平台、复现步骤。定位问题时先让对方跑一遍claude plugin list确认版本再逐步排查。还有一个实用技巧在SKILL.md正文里预埋环境自查要求让模型在脚本执行失败时自动输出当前操作系统、Shell类型和脚本路径。这样用户报Issue时你能直接拿到环境差异不需要来回追问十轮。6.2 拆分的思路一个插件只做好一件事插件做得久了人会忍不住把所有技能往里塞。我建议克制。拆分的判断标准很简单这些入口点是不是大概率会被同一批用户一起使用是放同一个插件不是拆成两个。比如代码评审和数据库迁移检查用户群体和场景差别很大硬塞在一起只会让体积变大、描述变长、误触发概率上升。我自己就走过这个弯路。早期一个插件里塞了8个Skill结果模型在无关场景频繁误触发用户的负面反馈相当直接。后来拆成两个插件误触发问题立刻消失维护体验也好了很多。6.3 给还不想动手的人一点建议如果你现在只有一两个Skill也没有明确的分享需求确实可以不急着打包。但哪怕不为分发我也建议你把目录结构按Plugin规范摆好。这样做的最大好处是等某天想把技能分享给同事时不需要推倒重来补上.claude-plugin/plugin.json就能变成正式插件。迁移成本低到可以忽略但收益是长期的——所有入口点都有固定位置找东西不再靠记忆。我自己的体会是把这套流程完整跑通之后最大的收获不是分发本身而是被迫把所有技能重新梳理了一遍。那些写得不明不白的描述、埋着绝对路径的脚本、命名混乱的目录全都在打包过程中暴露了出来。如果你也想把自己手上的Skill梳理成能拿得出手的状态这条路值得亲自走一遍。