先聊点实在的。最近这个Agent圈子热得很快身边做开发的朋友聊来聊去最后都会落到一个问题上模型能力本身大家都在卷真正拉开差距的是Agent能调用什么样的技能。Skill也就是“技能”本质上就是一个可复用的能力包——把一段自然语言指令、一段执行代码和一个人类可读的描述封装成标准单元。会写技能的人不少但能把技能变成一个可以被检索、安装、被其他Agent消费的公开产物是另一回事。ClawHub就是解决这个分发问题的平台。你可以理解成“Agent技能的应用市场”开发者在本地把技能写好通过命令行工具打包推送上去审核通过后所有接入ClawHub的Agent都能直接发现并调用。这篇文章我会完整走一遍发布流程技能目录结构、清单文件怎么写、CLI怎么做本地校验和发布、上架后有哪些坑要避开。从零到可被公开调用5分钟基本够用。刚接触Agent开发的新手或者团队里负责积累Agent能力资产的同学都可以直接照抄这套流程。1. 先搞清楚ClawHub上的“Agent技能”到底是什么1.1 技能Skill与Agent的关系先说定义。Agent是“大脑手脚”的组合大脑负责推理和决策手脚负责真实动作。Skills就是手脚里的标准化工具。没有技能的大模型只能跟你聊天有了技能它才能查天气、算数学、调接口、整理文档甚至操作你本地的软件。这里要区分几个容易混淆的概念。插件Plugin通常强调和宿主系统的深度集成比如浏览器插件、编辑器插件往往带UI或特定宿主API。工具Tool则更偏向单一函数封装比如“给定城市名返回天气”。而技能Skill是一个更高层的概念它不仅有执行代码还有触发说明、参数定义、调用示例Agent读到技能描述之后能自己决定什么场景用这个技能、怎么传参数。换句话说技能是给Agent自己看的“使用说明书工具包”。一个合格的技能至少要回答三个问题这个技能干什么什么条件下用它调用它需要什么参数、返回什么结果ClawHub的审核机制也在倒逼开发者把这三件事写清楚这反而是好事——很多本地自用的技能往往只有代码没有文档Agent根本不知道怎么触发。1.2 为什么选择ClawHub而不是“丢个代码包出去”如果你只是写了一个脚本丢到代码托管平台别人拿到了也不知道怎么接进自己的Agent。ClawHub补齐了这中间的关键环节。第一它规定了标准的技能包格式。只要按它的SKILL.md规范写清单任何接入平台的Agent都可以自动解析、装配、调用。跨项目复用的成本一下子降下来了。第二它有版本和审核机制。技能迭代时会走语义化版本号Agent端可以锁定某个版本调用不会今天能跑明天崩掉。第三它提供了沙箱运行环境。你发布前可以本地跑、平台跑双重验证避免“代码在我电脑上是好的”这种经典问题。最后它还有发现和统计。用户通过关键词搜索技能、查看调用次数、看评价优质技能能获得更多曝光这会形成正向循环。如果你只是一个人自用完全可以用本地文件夹管理技能。但只要你想让其他人、其他Agent用上ClawHub这种带标准格式和分发通道的平台会省掉非常多沟通成本。1.3 一个技能包的基本构成一个最小可用的技能包通常是这个结构text-summarizer/ ├── SKILL.md # 技能声明文件核心 ├── script.py # 技能逻辑代码 ├── requirements.txt # 第三方依赖可选 └── examples/ # 示例输入输出强烈建议 ├── demo-input.json └── demo-output.jsonSKILL.md是灵魂它告诉ClawHub和Agent这个技能是什么、如何调用。script.py是实际执行的逻辑示例目录则是给审核和调试人员看的“演示用例”。别小看examples目录审核通过率一半靠它。你光说“本技能可以做摘要”不如放两个真实的输入输出对审核员和上游Agent都能一眼看懂。2. 5分钟倒计时发布前的准备环节2.1 账号、环境和工具链打算动手之前先确认三件事ClawHub账号、CLI工具、本地Python环境。账号在平台官网用邮箱注册就行审核是人工的建议别用临时邮箱后续技能维护、找回密钥都麻烦。CLI工具是发布技能的必备工具名字在不同版本里可能有差异一般安装方式是这样# 安装 ClawHub 官方命令行工具 pip install claw-cli # 验证是否安装成功 claw-cli --version如果你不太熟悉命令行也别紧张操作路径非常短。整个发布流程只依赖四条命令init初始化、validate校验、run沙箱运行、publish发布。记住这四条命令就够了。2.2 本地目录结构与文件规范建议在电脑上建一个专门的目录存放所有技能项目别散落在“下载”文件夹里。比如mkdir -p ~/clawhub-skills cd ~/clawhub-skills然后通过CLI初始化第一个技能项目claw-cli init text-summarizer这个命令会自动生成标准的目录骨架避免你手工建目录时漏掉必要文件。执行完之后目录里会多一个text-summarizer文件夹里面已经有一个SKILL.md模板。2.3 技能选题第一个技能做什么最合适很多人一到这一步就卡住翻来覆去想做什么“惊世骇俗”的技能。我的建议是不要搞复杂第一个技能的核心目的是打通整个发布链路。选择一个你两小时内能写明白的小功能比如文本摘要、JSON格式化、正则匹配测试都是很好的起步选择。以“文本摘要技能”为例它够简单、语义清晰、人人都能用。下面所有流程我都会拿这个技能做示范。如果你有自己更想做的方向替换成对应的代码和描述就行流程完全一致。3. 手把手走一遍发布流程从本地到ClawHub3.1 编写SKILL.md声明文件技能的核心入口初始化之后打开SKILL.md我最建议新手直接复制下面这份完整模板把字段值改成自己的信息name: text-summarizer version: 1.0.0 description: | 接收一段长文本输出简洁摘要。 适用于会议纪要、文章速读、新闻提炼、长邮件快速阅读。 当用户需要快速了解一篇长文的核心信息时优先使用本技能。 author: your-alias license: MIT tags: - 文本处理 - 摘要 - 效率工具 runtime: python:3.11 entrypoint: script.py timeout: 30 parameters: max_length: type: integer default: 200 description: 摘要最大字数默认200字逐行拆解一下关键字段。name技能的唯一标识。只允许小写字母、数字、中划线。这个字段发布后不能再改所以初始化时想清楚。description这个字段最值钱。Agent全靠读description判断“什么时候用这个技能”。我的写法是“接收什么 输出什么 适用场景 触发条件”尽量避免泛泛的“这是一个摘要工具”。runtime告诉ClawHub运行环境示例里用的是Python 3.11。官方支持的运行时版本你可以在文档里查到选最接近你本地环境的。entrypoint入口文件对应你的主逻辑脚本。这里写script.py。parameters声明技能可接受的参数。Agent会根据这个字段生成调用参数所以务必写清楚类型、默认值和含义。3.2 实现技能逻辑代码写一个能跑的Python脚本。下面这个实现不依赖任何第三方库用了最朴素的关键句提取逻辑好处是任何环境都能直接跑通如果你要接大模型API替换成对应的接口调用即可import sys import json def load_text(raw): 从不同输入结构里提取需要处理的文本。 if isinstance(raw, dict): return raw.get(text, ) return str(raw) def extract_sentences(text): 将文本切分为句子。这里用中文标点做简单切分。 chunks text.replace(\n, ).split(。) return [c.strip() 。 for c in chunks if len(c.strip()) 0] def summarize(text, max_length): sentences extract_sentences(text) result for s in sentences: if len(result) len(s) max_length: break result s if len(result) 0: return text[:max_length] …… return result if __name__ __main__: payload json.loads(sys.stdin.read()) raw_input payload.get(input, payload) max_length payload.get(max_length, 200) text load_text(raw_input) summary summarize(text, max_length) print(json.dumps({summary: summary}, ensure_asciiFalse))这个脚本的设计要点有一处值得展开说它从标准输入读取JSON再从JSON里取input字段。这是ClawHub技能运行时的通用约定——宿主会把调用参数以JSON的形式通过stdin传给脚本脚本再把结果以JSON形式通过stdout输出。这就保证了技能与宿主之间的协议简单、语言无关。你不需要搞HTTP服务、不需要WebSocket一个能读stdin写stdout的脚本就够了。3.3 声明依赖这一步别偷懒如果你的技能不需要第三方库requirements.txt可以留空但文件必须存在因为平台构建时会尝试读取它。我一般在文件里写一行注释# 本技能无第三方依赖 # 如需要引入依赖请在此文件中填写例如 # requests2.31.0需要提一下版本锁定的原因。默认情况下不要写“requests”这类不带版本号的裸依赖因为依赖没有锁定版本平台构建时可能拉到新版本接口变了技能跑出截然不同的结果反之写死“requests2.31.0”虽然保守但可以保证构建可复现。中间有依赖冲突时优先锁定主依赖的版本。3.4 本地校验与沙箱调试写完代码和清单文件先别急着发布。CLI提供了本地校验和沙箱运行功能这是你要养成的好习惯。# 进入项目目录 cd text-summarizer # 校验 SKILL.md 格式和字段完整性 claw-cli validate SKILL.md # 输出示例Skill manifest is valid ✓ # 沙箱运行模拟Agent调用 claw-cli run ./SKILL.md --input {text: 人工智能技术正在快速发展。大语言模型的推理能力持续增强。多模态模型也开始进入实际应用场景。, max_length: 50}如果一切正常你会看到stdout输出一个JSON对象里面包含summary字段和摘要结果。这里我强烈建议你在examples目录下保存一个示例输入输出对mkdir examples # 将上述输入保存为 examples/demo-input.json # 将对应输出保存为 examples/demo-output.json示例文件的价值我在前面提过审核员会看Agent的开发者也会看。有真实示例的技能包显得更成熟也更可信。3.5 推送到ClawHub并提交上架本地校验通过之后发布就很快了。# 登录 ClawHub 账号首次会在浏览器中完成授权 claw-cli login # 发布技能包 claw-cli publish ./SKILL.md发布之后技能会进入平台侧审核队列。审核时间段通常从几分钟到一两天取决于当前积压数量。状态变化会通过邮件和CLI通知# 查看技能状态 claw-cli status text-summarizer审核通过后你的技能就会出现在ClawHub的公开技能列表里任何接入平台的Agent都可以检索并调用它。到这里5分钟流程走完了。4. 发布后的那些坑常见问题与排查实录4.1 清单文件校验失败的三种原因validate这一步拦截了大量低级错误新手最常见的有三种。第一种是YAML缩进问题。SKILL.md本质是YAML而YAML对缩进极其敏感。description下面多级文本尤其容易出错多行文本块用“|”符号下面的内容必须统一缩进空格和Tab不能混用。我建议所有编辑操作都在显式显示空格的编辑器里进行能省很多事。第二种是必填字段缺失。不同版本的ClawHub对必填字段要求不一样老版本可能允许不写license新版本会直接拒绝。遇到校验报错先把报错信息从头读到尾它一般会精确指出第几行有问题。第三种是entrypoint指定的文件不存在。很多人在SKILL.md里写了script.py但实际文件叫main.py或在子目录里。保持entrypoint和实际文件名一致即可。4.2 技能调用超时或完全没有响应技能在沙箱里跑得好好的一上平台就超时这是常见现象。原因一般出在三个地方一是timeout设置太短。SKILL.md里timeout: 30表示30秒如果你的脚本需要下载模型、访问外部API30秒不一定够。建议第一个版本将timeout设到60秒跑通了再往下调。二是脚本依赖外部网络。平台沙箱对出网有限制有些域名通、有些不通。你的技能如果必须访问外部API尽早确认域名在白名单内或者在description里写明“需要联网访问api.xxx.com”审核时也会有人工检查。三是脚本没有写flush。Python的print输出默认带缓冲如果脚本中途异常退出输出可能丢失。在print之后加一句sys.stdout.flush()可以避免很多莫名其妙的问题。4.3 依赖安装失败与兼容性冲突requirements.txt写得不对会让审核流程在构建阶段直接失败。常见情形是本地Python 3.10跑得好好的平台是3.11某个依赖编译不过或者A库依赖B库的1.x版本你锁了2.x冲突了。我的建议是第一明确运行时版本之后本地用完全相同的版本做验证最稳妥的方式是用虚拟环境建一个干净环境重新安装。第二优先选择有预编译包的依赖尽量减少包含C扩展的库因为不同平台的编译链差异很大。第三如果依赖实在太多就考虑拆技能——让一个技能专注做一件事少依赖自然少冲突。4.4 审核被拒绝的常见原因ClawHub审核不是走流程它真的会看内容。我见过被拒绝的案例大致有四类一是“空壳技能”——代码是抄来的模板根本没有实现description里声称的功能二是“危险操作”——技能尝试执行任意系统命令、读取环境变量里的密钥、操作文件系统越权路径这类直接拒绝三是“内容侵权”——打包了别人的付费数据或未经授权的内容四是“低质重复”——平台已有大量同类型技能你的又没有明显差异化。想一次通过审核在提交前自查三件事代码实现是否真的完成了描述里的承诺是否存在可能被判定为“越权”的操作examples目录有没有清晰的输入输出示例。做到这三点通过率会非常高。4.5 技能列表、关键实操速查表这里整理一份速查表供复查时对照。检查项操作常见问题SKILL.md格式执行claw-cli validateYAML缩进错误、字段缺失依赖声明锁定版本号依赖版本冲突、构建失败沙箱运行执行claw-cli run超时、外部网络不通示例文件检查examples目录无示例、示例与实现不符安全审查自查代码危险命令、密钥硬编码、越权路径发布状态执行claw-cli status审核中、被拒绝、已上架5. 让技能被更多人用到上架后的体验优化与迭代5.1 学会用“动词对象场景”结构写描述技能上线只是开始真正让Agent“愿意”用你的技能靠的是description写得好不好。Agent读取SKILL.md时description就是它的“决策依据”。实践下来我强烈建议用“动词对象场景”结构来描述比如“接收一段长文本输出简洁摘要适用于会议纪要、文章速读、新闻提炼”。这里“接收”“输出”“适用于”都是高频触发词Agent读到这类动词会更容易将用户意图映射到你的技能上。反例就是“一个文本摘要工具”这样一句话描述信息量太少。Agent不知道什么时候调用、怎么调用你的技能就一直躺在列表里无人问津。5.2 版本更新策略语义化版本号的重要性技能上架后你大概率会发现新问题、想加新功能。更新时不能只是把代码改了再传一遍要紧跟语义化版本号的规则修Bug、微调描述递增补丁版本1.0.0到1.0.1新增参数或功能递增次版本1.0.0到1.1.0破坏性变更比如改函数入口、删参数递增主版本1.0.0到2.0.0。为什么这么做因为Agent端可能会有大量上游服务锁定了你的版本。你发布一个破坏性更新所有锁定旧版本的上游会受影响。别人会感谢你反向也会让自己的技能更受欢迎。5.3 认真对待调用统计与用户反馈ClawHub后台能看到技能的调用次数、成功率、平均响应时间以及用户提交的反馈。建议每隔一段时间做一次数据复盘。调用次数高但成功率的优先查日志里失败的原因调用次数低的大概率问题出在description不够清晰或者同类技能竞争太强。这时候就要做差异化更新要么加新功能要么优化描述。技能发布这件事从来不是“上线即结束”而是一个持续迭代的过程。6. 最后再分享一点个人体会流程走完一遍之后你会发现“5分钟发布技能”是真的前提是你把技能本身想清楚了。我自己第一次发布的时候花最多时间的不是写代码而是反复纠结“我的技能到底和别人的有什么不同”。其实没必要先发一个最小可用版本跑通流程建立反馈闭环比憋大招有用得多。还有一个对我帮助很大的习惯每次发布前都在沙箱里模拟一遍“Agent视角的调用”直接用一段接近用户真实口语的输入去测试而不是总用自己写好的标准JSON。这个动作帮我拦住了非常多“看起来没问题但Agent就是不会触发”的问题。另外把所有技能包统一放在一个目录里并按项目管理等到技能数量多了以后你会感谢当初这个习惯。后续如果你想让技能更强大可以往多模态输入、多技能组合编排、订阅式技能这几个方向扩展。第一步永远是先把一个最小技能干净利落地发上去。