最近在ClawHub上折腾Agent技能，发现身边不少朋友有个共同误区：一说“发布技能”，就觉得得先写一堆复杂的Python代码，甚至想先微调个模型。其实真不用。ClawHub做的事情，往简单了说，就是给Agent技能准备的仓库平台，你只要把希望Agent掌握的“干活步骤”整理清楚，写明白触发条件，上传上去，别人安装了就能直接用。我花5分钟发布过一个很不起眼的小技能，后来打开后台一看，被装了几十次，虽然不是多大的成就，但足够说明一个事实：发布Agent技能这件事，门槛比大多数人想象的低得多。
这篇文章我会完整拆一遍从0到1的流程。不绕弯子，不讲空理论，就是实际操作：技能该放在什么目录结构里、SKILL.md怎么写才能在ClawHub上被正确解析、提交之后怎么验证、遇到解析失败或Agent不触发这类的坑该怎么办。适合人群很明确：已经用过ChatGPT这类工具、偶尔写点脚本，但还没正经发布过一个Agent技能的人。如果你已经在ClawHub上发过技能了，可以直接跳到第5节看问题排查，那里有几个在文档里翻不到的细节。
1. 项目拆解：ClawHub和Agent技能到底是什么
1.1 光从标题能读出哪些关键信息
“5分钟在ClawHub发布你的第一个Agent技能”这句话，信息密度比看起来高得多，我们先把几个关键词拆开。
第一个是“5分钟”。它暗示了这件事的核心不是写代码，而是配置和定义。如果技能需要大量自定义逻辑、需要跑复杂的依赖环境，5分钟肯定不够；但如果只是把一个已经想清楚的流程模板化，那5分钟确实可以完成。这个时间限定倒逼我们把思路调整到“标准化技能包”的节奏上来，而不是“开发一个应用”。
第二个是“ClawHub”。平台类产品通常有一套固定的提交流程，核心是仓库、分支、版本。你不需要去理解整个平台的所有功能，只需要走通“创建仓库、推送文件、校验发布”这一条主链路就行。
第三个是“Agent技能”。这是发布物。它本质上不是一段Prompt，而是一份结构化的“能力说明+执行指引”，让Agent在匹配到对应场景时，能照着这份说明一步步执行。
把三个词连起来看，整件事就变成了：准备一个标准格式的技能包，里面有一份清单文件，通过平台发布，让其他Agent可以搜索到并安装使用。核心是格式和流程，不是算法和模型。
1.2 Agent技能的本质：从“会对话”到“会干活”
很多刚接触Agent的人把技能和Prompt混为一谈，这是最大的认知偏差。Prompt是你和模型之间的一次性对话指令，用完就没了，依赖上下文窗口，换个会话就得重新说一遍。技能不一样，它是固化下来的能力单元，相当于Agent的“长期操作手册”，一旦安装，Agent就能在相关场景里自动唤醒它。
拿现实里的场景类比一下。Prompt像你临时告诉实习生：“帮我把这几段文字整理一下，按工作进展、问题风险、下周计划排一下。”实习生听完照做，下次你还得再交代一遍。技能则像是你给实习生一本SOP手册，上面写清楚了“当用户给你一堆杂乱的工作记录时，你应该按哪四个板块来归类，输出格式长什么样”，他下次不用问你，直接翻手册干活。ClawHub就是分发手册的公共平台，任何Agent装上你的技能，就等于领到了一份带有完整流程的执行纲领。
技术落地层面，一个技能包通常包含三个部分：清单文件负责定义“我是谁、什么时候该用我”；核心内容负责告诉Agent“具体怎么做”；可选依赖负责提供“做这件事需要的脚本、模板或数据”。三部分各有各的规范，但也有大量现成模板可以直接套。理解了这三层，整个发布流程就顺理成章了：建目录、写清单、填内容、推平台。
1.3 为什么选择ClawHub作为首发平台
平台那么多，为什么盯着ClawHub？最先打动我的是它在Agent技能上的格式标准化。ClawHub对技能包有统一的Schema校验，也就是说你提交上去的每个技能，平台都会自动检查清单文件格式是不是合法、字段是不是完整、引用路径是不是存在。这个机制对新手特别友好：写错了，平台直接告诉你哪里有问题，不用自己瞎猜。
其次是安装量和评价体系比较透明。每个技能页面都会展示安装次数、用户反馈和版本历史，这既是给别人选择参考，也是给作者的正向激励。我那个小技能装了几十次，在排行榜上自然排不上号，但看到有人真的在用，就会愿意持续更新。
还有一点是它把“仓库-版本-安装”串得很顺。ClawHub的仓库名有统一的命名约定，格式形如skill-name.skill，平台页面一键创建，本地git推上去以后，平台自动解析SKILL.md并生成版本记录，使用者按版本安装。整个链路没有多余的中间环节，这就是能把发布时间压到5分钟的基础。
2. 发布前的准备：想清楚再动手
2.1 5分钟的时间如何分配
说是5分钟，其实动手之前最需要花时间的是“想清楚你的技能边界”。这一步在脑子里完成，不算在5分钟里，但如果你跳过了，后面大概率要返工。
我的分配方式是这样的：60秒想清楚技能适用的场景和触发词，60秒写SKILL.md的元信息，90秒写技能的核心执行步骤，90秒完成Git提交并在ClawHub上校验发布。前两步决定了一个技能包能不能被正确索引，第三步决定了Agent执行得好不好，第四步就是走流程。
举一个最典型的失败案例。某位开发者朋友第一次发布技能，给Agent写“整理周报”步骤，写了三千字的长篇Prompt式说明，结果Agent每次输出的格式都不一样。问题出在哪？他把“技能的指引”写成了“给模型的话”，里面充满了“你可以这样”“最好这样”这类模糊表达。Agent技能内容需要的是确定性的步骤指令：先做什么，再做什么，遇到情况A怎么处理，遇到情况B怎么处理，输出格式固定成什么。发布之前一定要把这个思路切换过来，否则一步错步步错。
在动手创建仓库之前，先把下面这几个问题的答案写在一张便签上：技能叫什么名字、解决什么问题、在什么场景下触发、有哪些明确的输入输出边界。就四句话，写不出来的话说明你的技能还没有想清楚，不值得发布。
2.2 技能内容的核心载体：SKILL.md清单文件
SKILL.md是整个技能包的入口文件，也是ClawHub会不会认你这个技能的决定性因素。它在技能包里的地位，约等于项目里的README加配置文件加启动入口，三者合一。
文件头部是标准YAML格式的元信息块，用三条短横线包裹。比较关键的字段有这么几个：
- name：技能的唯一标识，建议全小写加短横线，和仓库名保持一致；
- description：一段能让Agent理解“什么时候该用这个技能”的描述，最好直接写清楚触发场景；
- version：语义化版本号；
- author和license：这两个字段虽然不参与执行逻辑，但ClawHub的策略是缺失任何一个字段都可能被判定为格式不完整，宁可填满也不要留空。
元信息下面就是技能正文。正文的组织方式没有强制的Schema，但有一个隐含约定：用Markdown的标题层级把“适用场景、执行步骤、输出规范”三个板块写清楚，Agent在执行时会顺着这个结构往下读。不要用花哨的排版，不要加无关内容，Agent的解析器对信息的抓取按语义走，你的结构越直白，它跑得越准。
我第一次写SKILL.md的时候犯过一个低级错误：在YAML的description里写了英文冒号后面直接跟中文内容，导致字段解析中断。这类冒号和缩进的坑实际非常常见，后面第5节我会专门列一张排查表。
2.3 技能内容目录的推荐结构
ClawHub上做得好的技能包都有一个共同点：目录结构清晰得让任何一个人扫一眼就知道功能模块在哪里。推荐用下面这个结构：
weekly-report.skill/ ├── SKILL.md ├── skills/ │ └── core.md ├── scripts/ │ └── split_sections.py └── references/ └── template.mdSKILL.md放在根目录，这是平台约定的固定位置，不要挪。skills目录存放技能的核心执行逻辑，通常拆成一个或多个Markdown文件。scripts目录放Python、Shell这类辅助脚本，比如周报整理技能里把用户输入拆成段落的脚本。references目录放可选的参考模板和示例输出。
有些刚上手的同学图省事，把所有内容全塞进SKILL.md，一个文件五六百行。这样平台能识别，但Agent执行时容易在大段落里忽略关键指令。合理拆分让每个文件的职责单一，Agent按路径检索也更高效。
依赖关系和路径引用要做到“相对路径优先”。凡是SKILL.md里需要引用其他文件的地方，一律写相对路径，不要写绝对路径。原因很简单：技能包装到别的Agent环境里，绝对路径百分之百失效。这条规则是我在几个失败案例里总结出来的。
3. 实操过程：5分钟完整流程
3.1 第一步：初始化技能目录（60秒）
先打开ClawHub页面，点击创建新技能仓库。平台会给一个命名格式，形如my-skill.skill，前面是你的技能名，后缀固定是.skill。注意这个后缀不是装饰，它是平台识别技能包类型的关键标记，命名不合规会直接在创建环节被拦下来。
我用周报整理技能举例子，仓库名就是weekly-report.skill。创建完成后，把它克隆到本地。如果你本地已经有这个目录，也可以直接初始化Git仓库然后关联远程地址，效果一样。
然后创建我们刚才说的目录骨架：
mkdir weekly-report.skill cd weekly-report.skill mkdir skills scripts references touch SKILL.md这四条命令就够了，整个初始化过程基本一分钟内完成。不建议在这个阶段花时间手写所有文件内容，先把骨架拉起来，后面逐个填充才是高效路径。
3.2 第二步：编写SKILL.md元信息（60秒）
打开SKILL.md，把YAML元信息块写上。这是整个文件里唯一有强格式要求的部分，一个缩进错误都会让平台解析失败。我用一个实际可行的模板：
--- name: weekly-report-organizer description: 将零散的工作记录、聊天摘录或短句流水账整理为结构化周报。当用户说“帮我整理周报”“把这一周的工作整理一下”等相近表述时使用。 version: 1.0.0 author: example-dev license: MIT tags: [report, weekly, productivity] domain: office ---这里最容易出问题的的是description字段。它不仅是给人看的，更是给Agent做意图匹配时最关键的参考文本。要写得“像用户可能说出来的话”，尽量把触发词和场景包含进去，但又不要堆砌关键词。比如光写“整理周报”四个字，Agent在用户说“帮我总结一下这周干的事”时就不一定能匹配上；而上面模板里那种写法，匹配命中率明显更高。
关于version字段，第一次发布统一写1.0.0，不要写0.0.1这种起始版。一方面平台上默认按正式版展示，另一方面一旦后续更新，从1开头的语义版本递进更直观。
3.3 第三步：撰写技能核心步骤（90秒）
90秒写核心步骤，前提是你已经想好了流程。拿周报整理技能来说，核心其实就四步：
第一步，接收用户提供的原始工作流水； 第二步，过滤掉和真实工作无关的内容（比如闲聊、情绪化吐槽、临时无后续的念头）； 第三步，按四个板块归位：本周主要工作、关键进展与结果、问题与风险、下周计划； 第四步，按固定模板输出。
在skills/core.md里把这些步骤写清楚。注意语气，技能文件的指令是给Agent执行的，不是给人阅读的，用明确祈使句，不要用试探性表达。模糊的句子在Agent执行时会被忽略或自行发挥，而发挥的结果通常不是你想要的。
一个决定成败的细节是：给出格式模板。模板越具体，输出越稳定。周报技能里我直接规定输出结构是一个四级小标题下的四段式，每个板块不超过五行，用短句。给出“写成什么样”比解释“要写得怎么样”有效得多。
3.4 第四步：提交到ClawHub并验证（90秒）
文件写完，提交命令是标准的Git流程：
git add . git commit -m "feat: 初始化周报整理技能 v1.0.0" git push origin main推送之后，ClawHub会自动触发技能解析和Schema校验。回到仓库页面查看校验状态，如果通过，平台会把SKILL.md解析成结构化的技能详情页，并生成一个1.0.0版本记录；如果有问题，平台会在校验日志里标注具体字段，按提示改完重新推送即可。
校验通过后我要多做一步手动验证：在ClawHub的技能详情页点击“试用”，平台会模拟一次Agent调用。把真实的工作流水粘贴进去，看输出格式是否按照SKILL.md里的模板。这一步强烈建议不要省，很多技能写的时候感觉没问题，实际跑一遍才发现输出完全不受控。
给技能打上版本标签，让用户能按Tag安装：
git tag v1.0.0 git push origin v1.0.03.5 本地验证与效果展示
除了平台试用，我建议在本地Agent环境里再做一次完整验证。方法很简单：把本地技能目录路径配置到Agent的技能加载器里，然后直接对话。如果Agent没有自动触发，多半是description的意图匹配没覆盖到你的提问方式；如果触发了但输出结构不对，问题在core.md的执行步骤写得不够强制。
我把某次真实测试结果记录在这里，供参考。我在本地Agent输入：“这周我做了三件事，第一个是搭了一个数据看板的原型，第二个是去了两趟客户现场收集需求，第三个是跟后端联调接口，中途发现环境配置有坑，耽误了一天。下周打算把看板正式上线，顺便把联调环境的问题写个复盘文档。”Agent输出结构如下：
本周主要工作：三项——数据看板原型搭建、客户现场需求收集、接口联调。 关键进展与结果：看板原型完成，需求收集结束，接口联调接近尾声。 问题与风险：联调环境存在配置不一致问题，导致进度延迟一天。 下周计划：看板正式上线，输出环境问题复盘文档。
整个过程没有额外干预，效果基本符合预期。这里面的核心原因，是description匹配到了“这一周”这个触发信号。
4. 实战案例：一个给Agent用的“周报整理”技能
4.1 技能目标描述
我用真实发布过的“周报整理”技能来复盘整个设计思路，供读者参考。这个技能的目标非常窄：输入是零散的工作记录，输出是固定结构周报。边界也必须窄，它不负责分析KPI，不负责自动生成数据图表，不负责预测下周风险，只做一件事——整理归类。
技能边界窄有什么好处？第一，Agent的意图匹配会更准确；第二，执行步骤更简单，容错率更高；第三，用户预期更容易管理。我见过不少技能作者恨不得一个技能解决所有问题，把目标写成一个功能清单，结果Agent触发后经常做着做着就偏离了方向。
我在SKILL.md里的description这样写：“将用户提供的零散工作记录、聊天摘录或短句流水账整理为结构化周报。当用户说‘帮我整理周报’‘把这一周的工作整理一下’‘总结一下这周干了啥’等相近表述时使用。”故意把各种口语化的问法都列上，因为Agent意图匹配的底层逻辑靠语义近似，多写几种问法就是在帮它扩大命中面。
4.2 完整技能内容示例
下面是一份可以直接用的技能包内容。SKILL.md的元信息部分和核心执行部分，我按照ClawHub上的流行规范整理出来：
--- name: weekly-report-organizer description: 将零散的工作记录整理为结构化周报，输出固定四段式模板。当用户提供多段工作流水并表达整理、周报、总结意图时使用。 version: 1.0.0 author: example-dev license: MIT tags: [report, weekly, productivity] domain: office ---核心执行文件skills/core.md：
# 周报整理核心流程 ## 适用场景 接收用户提供的一段或多段工作流水。流水来源可能是语音转文字、日记片段、聊天记录，或直接输入的杂项清单。 ## 执行步骤 1. 将用户输入拆分为独立工作项，拆分依据是内容主题切换或时间切换。 2. 过滤工作项，移除与工作无关的内容： - 纯情绪表达不保留； - 没有后续行动的脑暴内容不保留； - 与当前业务无关的生活记录不保留。 3. 按四个板块归类： - 本周主要工作：本周实际推进的事项； - 关键进展与结果：有明确产出、结论或里程碑的内容； - 问题与风险：遇到的阻塞、风险或未解决问题； - 下周计划：明确的下一步安排。 4. 按固定模板输出，格式如下： ## 本周主要工作 （每条工作一行，短句，最多五行） ## 关键进展与结果 （每条结果一行，不超过三行） ## 问题与风险 （每条一行，不超过三行） ## 下周计划 （每条一行，不超过五行）## 输出规范 - 全篇使用简体中文； - 不添加模板之外的任何总结性语句； - 如果用户输入过少（少于两条有效工作项），直接输出原内容并提示信息不足，不强行编造。4.3 发布后在Agent中调用效果
技能上线后，在ClawHub的安装量在几周内爬到了几十。让我觉得有意思的是用户的真实调用习惯和触发意图匹配之间的互动。有人在技能评论区反馈，本来以为这个技能只能处理中文周报，后来发现他把英文的会议记录贴进去，Agent也能整理成对应的中文结构周报。这是因为大语言模型本身的多语言能力在起作用，技能只要把结构定清楚，模型会自行适配语言。
这给我一个很重要的启发：技能包的定位不是“教模型做事”，而是“给模型限定产出结构”。模型的理解和生成能力已经足够强，它缺的往往不是能力，而是明确的约束。技能的价值就在于用一行行指令把输出框进一个可控范围，让Agent从“自由发挥”变成“按规范执行”。规范写得好，Agent的发挥就有确定性；规范写得模糊，Agent的输出就各不一样，这也是同一份日志模板在不同技能作者手里效果天差地别的根本原因。
5. 常见问题与排查技巧实录
5.1 常见问题排查速查表
实操过程中遇到的坑，很难在官方文档里找全，我把高频问题整理成一张排查表，遇到现象直接对照定位。
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| 推送后ClawHub校验失败 | YAML元信息缩进或冒号格式错误 | 检查description和tags字段；缩进统一用两个空格；中文冒号改英文冒号 |
| 平台提示缺少必填字段 | author或license未填写 | 补全元信息字段，License建议统一写成MIT |
| Agent一直不触发技能 | description里的触发词覆盖不够 | 重写description，加入与用户口语表述相近的触发短语 |
| 触发了但输出和模板不一致 | 核心步骤里给出了过多自由裁量空间 | 改写执行步骤为强制祈使句，在输出规范里逐条限定格式 |
| 技能安装后提示找不到文件 | 相对路径写错或文件被忽略提交 | 检查SKILL.md内引用路径与仓库文件大小写是否一致 |
| 版本更新后使用者仍拿到旧版 | 没打新的Tag或未推送Tag | 执行git tag v1.0.x并推送，同时确认平台版本记录已刷新 |
这里面最值得展开的是YAML解析失败的坑。有一次我在description字段里写了一个带英文冒号的句子，因为输入法没切换，冒号用了中文全角，平台校验日志直接报“无法解析元信息”。我查了半小时，最后发现只是冒号字符问题。这类问题在中文写作场景里极易出现，写YAML时尽量保持输入法状态一致，并留意编辑器里是否开启了自动纠错。
5.2 更复杂的技能场景
一个被反复追问的问题是：“我的技能需要执行多步工具调用，还能用5分钟流程套用吗？”能，但前提是工具调用逻辑要记录下来，初始模板仍然适用。区别在于，skills目录下不能再只有一个core.md，而是要为每个工具步骤单独拆分一个子技能，并写入清晰的依赖关系。
举个例子，如果周报整理技能需要自动从某个项目管理工具拉取任务，你可以做成这样的目录结构：
project-report.skill/ ├── SKILL.md ├── skills/ │ ├── fetch_tasks.md │ ├── organize_report.md │ └── risk_detection.md └── scripts/ └── fetch_from_api.py在SKILL.md的元信息里增加一个dependencies字段，列出需要配合使用的子技能名称。ClawHub的解析器会按依赖关系加载，Agent执行时能自动串联这些步骤。这里的启动时间和5分钟版的区别主要在依赖安装上，只要各个子技能单独测试过，整体发布流程并不比简单技能多绕多少路。
5.3 跨Agent兼容性的现实考量
ClawHub生态内的Agent对技能包格式的兼容性基本一致，但如果你打算把同一个技能包复制到其他Agent框架里使用，就需要提前确认几件事。
第一是YAML元信息字段是否通用。有的Agent把触发描述放在description里，有的要求单独提供trigger字段，格式不兼容时直接迁移会导致技能无法识别。第二是依赖和脚本的运行时差异，有些Agent环境是纯容器化运行，没有完整Python依赖；有些则限定网络访问，外部API调用直接失败。第三是执行权限模型，部分Agent对技能读取用户文件有额外授权要求，不同框架要求完全不同。
一个现实的做法是：先以ClawHub作为主发布渠道，拿平台自带的试用环境做兼容验证，再按需要为其他框架写适配层。适配层本质上就是把同一个核心逻辑用目标框架的技能语言重写一遍，而不是指望一个包处处通用。跨平台兼容这件事，要放在技能稳定运行之后再考虑，不要一开始就追求“一次编写到处运行”，那是理想，不是现实。
6. 发布后的维护与迭代
6.1 版本更新策略
观察发现，很多第一次发布技能的同学都有个共同心态：技能发布出去就结束了，之后完全不管。这是最可惜的。Agent技能和开源软件一样，不是“发完即焚”，而是“发完才是开始”。
版本更新的关键节点就这么几个：用户提了高频需求而你的技能没覆盖到；你换了工作流方式而技能执行方式还是旧的；发现说明文档里描述的场景和实际表现不一致。每遇到一种，就该发一个小版本更新。
版本号调整了以后，记得做两件事：一是更新CHANGELOG，写明这次变化，即使只是加了几行说明也值得记录；二是在ClawHub的技能详情页把更新摘要写清楚。这里有个容易忽略的细节：修改SKILL.md后不更新version字段的话，平台会按同一版本处理，用户旧缓存不会刷新。每次推送前检查一下version是否递增，这个动作虽然不起眼，但能有效减少“为什么我更新了用户还看到旧版”的困惑。
6.2 让技能可复用的细节
想让技能被更多人安装使用，单靠功能本身还不够，可复用性同样是关键。有些技能包把使用者的技术栈或偏好写死在了脚本里，比如数据文件路径指向了作者的本地目录，这类技能对别人来说基本不可用。
我在写周报整理技能时做过两个专门提升可复用性的改造。第一个是把过滤规则写成独立的references，而不是写在core.md里；这样使用者不需要改核心逻辑，只需要在references里调整关键词就能适配自己的业务场景。第二个是约定好输入格式和输出格式的边界，在SKILL.md顶部用一段话声明“本技能不读取任何外部文件，不支持第三方系统集成，仅处理用户直接输入的内容”，把使用预期锁死。很多人看到边界说明反而更敢用，因为它在消除不确定性。
还有一个小技巧：技能名称和文件命名尽量用英文小写加短横线，不要用中文或大小写混合。这不仅是ClawHub命名的强制约定，也是到其他系统里避免编码问题的好习惯。中文路径在部分Agent的文件加载器里会出现编码错乱，这属于踩过一次就很难忘的坑。
6.3 在团队中协作与技能复用
如果你在团队里负责Agent技能建设，可以考虑在ClawHub上建立一个组织账号，把技能仓库统一放在组织下管理。好处不只在于集中管理，还能顺带形成内部的技能审核机制。任何成员修改技能后，提交Pull Request，由一个人审核代码和SKILL.md格式，审核通过后再合并发布。这是把个人技能变成团队资产最顺滑的路径。
我参与过的某家公司内部团队就是这样运作的。团队里几个人各自负责不同领域的技能，比如日报汇总、代码审查、数据分析，全部放在一个组织仓库里。因为仓库之间可以引用，他们甚至把“日报汇总”技能作为基础能力，让其他技能在依赖里直接引用，避免了重复维护。这种组织方式对个人开发者也有启发：你把不同技能做成互相独立的包，各自迭代，比把所有功能堆在一个技能包里好维护得多。
关于更新频率，个人实测下来的建议是：高频使用的工作流技能，保持每月一次的小版本迭代；低频工具类技能，只在出问题时才更新，不要为了更新而更新。稳定压倒一切，一个频繁变动但行为不稳定的技能，会让使用者逐渐失去信任。
最后再分享一个体会。刚开始接触ClawHub的时候，我也想过要做一个一鸣惊人的复杂技能，绞尽脑汁设计了半个月，最后因为边界太宽写不下去，搁置了一个多月。反而是那个只用5分钟随手发出来的周报整理技能，真正被别人安装和使用了起来。回顾这个经历，我觉得对绝大多数初次尝试发布Agent技能的人来说，最有效的策略就是：先找一个小而具体的工作流程，用模板走通一遍发布链路，再在真实反馈里逐步完善。技能发布这件事的价值不在技能本身多宏大，而在你通过它理解了一套标准化的能力分发逻辑，这套逻辑搬到任何场景里都能用。
