从零开发OpenClaw Skill并发布到ClawHub的实战指南

最近我把团队里一堆重复的、需要人工判断的杂活，陆陆续续搬到了OpenClaw上跑。实话讲，一开始我只是把它当成一个能对话的Agent壳子，用久了才发现，真正决定这个Agent上限的，是你能给它配多少好用的OpenClaw Skills。Skills这套机制，本质上是把"一段精准的提示词+处理脚本+资源文件"打包成一个标准化的技能单元，让Agent在合适场景自动调用；而ClawHub就是这些技能包的上架和分发平台。

这篇文章写的是我从零写第一个Skill、发布到ClawHub的完整过程。我会从最基础的SKILL.md结构讲起，实际带大家写一个能用的"会议纪要转任务清单"Skill，最后聊一聊上架审核和后续维护中那些文档里不会明说的坑。适合正在用OpenClaw、又觉得默认能力不够用的朋友，也适合想了解Agent Skills这类机制到底怎么设计的开发者。

1. 先搞清楚OpenClaw Skills到底是个啥

1.1 它不是一句提示词，而是一套"技能包"

我见过不少朋友对Skills的理解是"把提示词存起来"。这个理解没错，但太浅了。一个真正意义上的Skill，通常是一个目录，里面至少包含三样东西：

• SKILL.md：技能说明书，也是Agent判断"什么时候该用、该怎么用"的唯一依据。
• 可执行脚本（scripts/）：真正干活的逻辑，常见的是Python脚本，也可以放Shell、Node.js脚本。
• 资源文件（assets/）：模板、样例数据、配置文件等辅助材料。

你可以把它想成手机App和快捷指令的区别：快捷指令把一系列动作串起来，而App是一整个可以独立运行的程序。Skill更接近前者——它不取代Agent，而是给Agent增加一项专项能力。设计上，这套思路和Claude Code的Skills、Codex的Skills非常像，核心都是"让模型通过一份Markdown文档理解一个子任务，再通过脚本执行确定性操作"。

为什么这么设计？道理很简单：模型擅长理解意图、组织语言，但不擅长确定性计算和稳定格式输出。需要精确处理的环节交给脚本，需要灵活判断的环节交给模型，各干各的强项，整体可靠性能提高一大截。我最初写Skill时犯过很多次"让模型自己做格式化"的错，后来发现同一个格式Ask五次有五个版本，把格式交给脚本后，问题彻底消失。

1.2 ClawHub是技能分发市场

如果Skills是手机App，ClawHub就是应用商店。你写好一个Skill，不能总靠别人去GitHub克隆你的仓库，再把目录手动放到指定位置。ClawHub提供一个统一的上架、检索、安装入口，使用者一条命令就能装上，你后续更新版本，对方也能一键升级。

更重要的是，上架带来的约束会反向推高Skill的质量。因为发布出去的东西会被别人看到、会被提Issue，你自然会注意SKILL.md的措辞、脚本的健壮性和跨平台兼容性。我个人感觉，哪怕你暂时不打算分享，也值得走一遍"包好、校验、登记版本"的流程——这会让你的Skill从"能跑"变成"规范"。

ClawHub这种机制，相当于把Agent的能力管理从"随缘攒提示词"提升到了"工程化治理"的程度。这也是我为什么专门花时间研究它，而不是继续在对话里反复粘提示词的原因。

2. 动手之前，这些准备工作不能省

2.1 把OpenClaw跑起来

开始之前先确认环境。OpenClaw目前安装方式比较多，常见的三种：

• 一键脚本安装：适合Linux和macOS，终端执行官方脚本下载二进制和运行时依赖。
• Docker部署：适合不想污染本机环境的人，尤其是macOS用户。在Docker里跑一个OpenClaw容器，把数据目录挂载出来，升级时直接换镜像版本。
• Windows PowerShell安装：官方提供了PowerShell安装脚本，但注意需要提前装好Node.js运行时，否则启动时会报类似"Node runtime not found"的错误。

这一步踩过的坑主要集中在环境变量和运行时缺依赖上。我见过最多的是Windows上装完提示找不到Node运行时，原因往往是没装Node.js或者装了但没把路径写进PATH；还有人的Control UI起不来，多半是端口被占用，改一下配置里的端口就行。

装完之后先别急着写Skill，确认三件事：Agent能正常对话，模型能正确加载；配置文件里的模型名和本地或远程模型服务完全一致；调试模式开启，方便看Agent调用Skill时的完整日志。这里特别提醒，模型名一定要仔细核对，如果填了一个服务端不存在的模型标识，Agent启动后第一次回复就会直接失败，连技能测试都做不了。

2.2 读一遍SKILL.md规范

Skill的核心文件是SKILL.md，它就是一个带YAML头部的Markdown文档。头部字段决定技能元信息，正文决定Agent的执行逻辑。常用字段：

• name：技能名，全小写加短横线，比如meeting-to-tasks。
• description：一句话说明技能能干什么、什么时候该用。这个字段最重要，Agent就是靠它来判断是否调用。
• version：语义化版本号，如1.0.0。
• allowed-tools：允许技能调用的外部工具列表，比如HTTP请求、文件读写等。

yaml复制---
name: meeting-to-tasks
description: 将会议纪要转换为任务清单。当用户提供会议记录或行动项文本且希望得到待办清单时使用。
version: 1.0.0
allowed-tools: []
---

正文怎么写呢？我的建议是不要写流程文学，直接写步骤式指令。模型是按指令执行而不是按散文执行的，把"第一步做什么、第二步做什么、什么情况输出什么"写清楚，比写一大段背景说明有效得多。

注意：description是Agent决定是否调用Skill的唯一依据，别在里边堆形容词，要把"用户会怎么表达需求"原样写进去。

2.3 选一个值得做的场景

不是所有事情都适合做成Skill。我的筛选标准有三个：第一，重复发生，每周或每天都会用；第二，有明确输入输出，不需要太多来回讨论；第三，中间有确定性处理环节，比如提取、转换、格式化。用这三个条件筛一遍，大部分灵光一闪的想法都会被淘汰，剩下的才是值得投入时间的。

比如"帮我想个标题"这种就不适合，太依赖模型自由发挥，做成Skill反而限制灵感。而"把会议纪要转成任务清单"就非常适合：输入很明确，输出格式很明确，中间涉及按规则提取负责人和截止时间，脚本可以处理大半，模型只需要补足语义理解。

我在这一轮选的就是这个例子。后面整篇文章都会围绕它展开。

3. 实战：写一个"会议纪要转任务清单"的Skill

3.1 先定义清楚输入输出

动手写代码之前，先把需求定义写清楚。我这里要处理的是：给定一段会议纪要文本，输出一份Markdown任务清单，每条任务包含待办事项、负责人、截止时间三项信息；如果原文没有明确负责人，标记为"待确认"；没有截止时间，留"待定"不编造。

为什么要先定义清楚？因为脚本和SKILL.md都要围绕这个契约写。输入不明确，脚本没法解析；输出不明确，模型就会自由发挥，格式一会儿一个样。我习惯把样例输入和期望输出直接写进测试用例，后面改代码时随时回归。

示例输入：

code复制会议主题：新版App登录流程优化
参会人：张三、李四、王五

讨论结论：现有登录流程步骤太多，用户流失严重，决定简化。

行动项：
- 张三 在 5月20日前 完成登录页原型设计
- 李四 负责 后端验证码接口改造，时间待定
- 王五 尽快 输出埋点方案

期望输出：

code复制- [ ] 完成登录页原型设计（负责人：@张三，截止：5月20日）
- [ ] 后端验证码接口改造（负责人：@李四，截止：待定）
- [ ] 输出埋点方案（负责人：@王五，截止：待定）

3.2 搭好目录骨架

打开终端，创建目录结构。OpenClaw通常约定Skills目录下每个Skill一个文件夹。我创建一个新技能目录：

bash复制# 进入OpenClaw的技能目录（以本地默认配置为例）
cd ~/.openclaw/skills
mkdir -p meeting-to-tasks/scripts
touch meeting-to-tasks/SKILL.md
touch meeting-to-tasks/scripts/convert.py

目录名就是技能名，统一使用小写加短横线。scripts目录放Python脚本。assets目录暂时用不上，先不建，后面需要再加。如果发现~/.openclaw/skills不存在，可以用openclaw skills list命令让程序自动创建默认目录，再进去操作，免得手写目录路径和配置对不上。

3.3 写SKILL.md配置

编辑SKILL.md：

markdown复制---
name: meeting-to-tasks
description: 将会议纪要转换为任务清单。当用户提供会议记录或行动项文本且希望得到待办清单时使用。输入为原始笔记文本，输出为Markdown格式任务列表。
version: 1.0.0
allowed-tools: []
---

你是一个会议纪要转任务清单的处理器。用户会输入一段会议记录，请调用 scripts/convert.py 处理文本，并仅输出脚本生成的Markdown任务列表。

处理规则：
1. 将用户输入的原始会议纪要原样传递给脚本，不要自行改写内容。
2. 脚本输出即为最终回答，不要额外添加解释、问候或总结。
3. 如果用户输入明显不是会议纪要，直接说明"请提供会议纪要文本"，不再调用脚本。

为什么body不展开写"怎么提取负责人"这些细节？因为那是脚本的职责，不是模型的职责。你写得越细，模型越容易在传参时做手脚，不如让它老老实实把原文丢给脚本。另外allowed-tools留空数组，表示不需要额外外部工具，如果后续要调API就得在这里声明权限。

3.4 写核心处理脚本

接着写scripts/convert.py。这个脚本要做的事情：读stdin，按行解析，提取行动项、负责人和截止时间，输出Markdown任务列表。

python复制#!/usr/bin/env python3
"""Convert meeting notes to a task list via stdin/stdout."""
import sys
import re

def parse_owner(line: str) -> str:
    """Try to extract an owner's name from a line."""
    for kw in ["由", "@", "负责人"]:
        if kw in line:
            after = line.split(kw, 1)[1].strip()
            match = re.match(r"([\u4e00-\u9fa5A-Za-z0-9_]+)", after)
            if match:
                return match.group(1)
    return "待确认"

def parse_due(line: str) -> str:
    """Try to extract a due date from a line."""
    match = re.search(r"(\d{1,2}月\d{1,2}日|今天|明天|本周内|尽快|待定)", line)
    if match:
        return match.group(1)
    return "待定"

def parse_line(line: str):
    desc = line.strip()
    if not desc:
        return None
    owner = parse_owner(desc)
    due = parse_due(desc)
    # Remove owner/due fragments from description if possible
    desc = re.sub(r"(由|@|负责人)[^，。；;]*", "", desc).strip(" ，；;、-")
    desc = re.sub(r"(\d{1,2}月\d{1,2}日|今天|明天|本周内|尽快|待定)", "", desc).strip(" ，；;、-")
    return {"desc": desc, "owner": owner, "due": due}

def main():
    raw = sys.stdin.read()
    if not raw.strip():
        print("请提供会议纪要文本")
        return
    tasks = []
    # Only process lines that look like action items
    for line in raw.splitlines():
        stripped = line.strip()
        if stripped.startswith(("-", "·", "*")):
            task = parse_line(stripped.lstrip("-·* "))
            if task:
                tasks.append(task)
    # fallback: process non-empty lines if no action markers found
    if not tasks:
        for line in raw.splitlines():
            if line.strip():
                task = parse_line(line)
                if task:
                    tasks.append(task)
    for t in tasks:
        print(f"- [ ] {t['desc']}（负责人：@{t['owner']}，截止：{t['due']}）")

if __name__ == "__main__":
    main()

这段代码有几个设计要点。第一，只依赖Python标准库，不引入第三方包，任何环境都能跑。第二，输入输出都走stdin/stdout，不读写文件，这是Agent调用脚本最通用、最不容易出错的交互方式。第三，解析规则故意写得很朴素，宁可漏掉也不乱猜，因为模型会在调用前先做语义理解，脚本只负责执行格式化。第四，中文处理在Python3下默认utf-8，避免Windows终端编码问题。

如果你要接外部API，比如把任务同步到飞书或者钉钉，就在脚本里用requests或者标准库urllib发HTTP请求，同时要在SKILL.md的allowed-tools里声明网络权限。这个后面可以扩展。

3.5 本地测试与效果验证

测试命令怎么跑？我先在终端模拟Agent的调用方式，把示例输入管道给脚本：

bash复制cat sample_meeting.txt | python3 scripts/convert.py

用一个样例文件测试。如果输出符合预期，再进OpenClaw里做端到端验证：

bash复制openclaw skills test meeting-to-tasks

或者直接在对话里说"把这段会议纪要转成任务清单"，看Agent会不会主动调用这个Skill。测试时重点观察三件事：第一，description是否能触发调用；第二，脚本输出是否原样返回；第三，对明显不是会议纪要的输入，Agent会不会拒绝调用。

我这边第一次测的时候，发现Agent压根没调用Skill，后来检查是description写得太泛，没写"会议记录""行动项"这些触发词。改完之后马上就能命中。这一步不要跳过，本地不测好，上架之后被用户骂是小事，自己排查起来更费劲。

4. 发布到ClawHub

4.1 上架前的自检清单

在上架之前，一定要先把本地版本确认好。一个标准的Skill目录应该是这样的：

code复制meeting-to-tasks/
├── SKILL.md
├── README.md
└── scripts/
    └── convert.py

多出来的README.md是给使用者看的使用说明。自检清单如下：

这里有一个容易忽略的点：上架前最好在全新的默认环境跑一遍，因为本地装了很多依赖可能掩盖问题。我至少有两次Skill在本地能跑，换环境就挂，都是因为隐式依赖了本机才有的环境变量。

4.2 发布操作

确认完自检项后，登录ClawHub账号。打开终端，在Skill目录下执行发布命令：

bash复制# 先本地构建一个标准包
openclaw skills build meeting-to-tasks

# 登录ClawHub（首次需要输入token）
openclaw clawhub login

# 发布
openclaw clawhub publish meeting-to-tasks

发布成功后ClawHub会给一个页面链接，别人可以一键安装。安装方的命令一般是openclaw skills install meeting-to-tasks，这和使用者本地有没有装Docker、用的是什么模型都没关系，ClawHub会把Skill文件拉到本地技能目录，然后由OpenClaw在对话中决定何时调用。

这里有一个非常实际的建议：注册ClawHub账号时，用户名最好和你的GitHub或常用社区ID保持一致。因为后面维护时，Issue和更新记录都会挂在这个ID下，名字统一可以减少很多信任成本。

另外，发布以后版本号不能重复，更新代码必须同时升版本，否则提交会被拒。我习惯用一个简单的规则：功能或文档有实质变化就升patch版本，比如1.0.0到1.0.1；行为变化不兼容时升minor版本，比如1.0.1到1.1.0；核心接口全部重做才动major版本。

4.3 上架后的维护

发布不是结束。很快Issue会来。别人在Windows上装了你的Skill跑不通，你在macOS上测得好好的——大概率是脚本里的路径分隔符或编码问题。这时候再怎么吵也没用，直接按跨平台标准改脚本，重新发布一个版本。还有要同步更新SKILL.md里的示例，保持文档与行为一致。

我建议上架后至少做三件事：每周看一次ClawHub上的反馈；新版本发布前在全新环境测试一遍；README里写明已知限制，比如"当前只支持中文会议纪要，英文输入可能输出异常"。写清楚限制，反而会减少很多无效Issue。

另一个维护心得是：不要每个Issue都急着发版本。把同类问题攒一攒，集中修复后发布一个版本，比一天发三个版本更省心，ClawHub的更新通知也会更少打扰到用户。Skill这种东西，稳定性比功能数量重要。

5. 常见问题与排查实录

5.1 快速排查速查表

这里整理一张速查表，覆盖我在开发、测试、上架过程中遇到的高频问题，直接对着查就行：

如果你遇到的现象不在表里，先开Debug模式看日志，日志里会打印Agent决策时"是否调用Skill""传入参数是什么""脚本返回什么"。熟练掌握这套排查逻辑，比死记问题答案管用得多。

5.2 几个我踩过、别人大概率也会踩的坑

第一个坑：description写得太文艺。"帮助用户高效地把会议记录转化为可执行的行动项"这种描述看着挺好，但Agent在实际场景里不会因为"高效"就触发。它需要看到"会议纪要""任务清单""行动项"这种和用户原始输入直接对应的词。改成"将会议纪要转换为任务清单。当用户提供会议记录或行动项文本且希望得到待办清单时使用"，命中率立刻上来了。

第二个坑：脚本对Windows不友好。第一版脚本里我用了os.path.join拼接路径，在Windows上跑没问题，但放到Linux容器里就出岔子。后来所有路径操作都改用pathlib.Path，分隔符问题再也不存在。跨平台不是锦上添花，是发布Skill的基本门槛，尤其是ClawHub天然跨平台，随时可能有人在奇奇怪怪的环境里装你的东西。

第三个坑：忘了处理空输入。如果用户只发了一个"帮我"，脚本读到的stdin是空的，页面直接卡死。后来我加了空输入检查，输出一句"请提供会议纪要文本"再退出。看似不起眼，但很多真实用户真的会这么用。类似的还有"输入的是英文怎么办""输入的是乱码怎么办"，脚本能兜底就兜底，不能兜底就给一句清晰的错误提示。

第四个坑：测试只测了成功路径。我一开始就测了一次标准输入，看起来很顺。后来模仿用户随手贴了一段无关文本，马上暴露了误解析问题——把正常讨论内容当成行动项提取了。现在我的测试清单里固定有一条"无关输入测试"，专门喂一些不相关的文本确认不会误触发。这个习惯帮我在后面几个Skill里拦下了不少低级bug。

这个Skill发布到ClawHub之后，团队里几个人都装上了。现在开会的人只需要把纪要原文贴给Agent，任务清单几秒钟就出来。虽然这个技能本身很简单，但走完一整套"需求拆解、开发、测试、上架、维护"流程，我对OpenClaw的Skills机制算是摸透了。我现在看到重复性工作，第一反应不是"再让Agent跑一遍"，而是"这个东西能不能沉淀成一个Skill"。据我观察，这是使用Agent类工具的一个分水岭：在Skills出现之前，你用Agent靠临场发挥；在Skills出现之后，你的Agent能力是靠积累的。

最后再分享一个小技巧：给Skill起名和写description时，先想一想"用户会怎么在聊天框里表达这个需求"，然后把你想到的那句话原样塞进description里。这比任何抽象的优化建议都管用。