OpenClaw Skill：用SKILL.md定义AI最小可执行单元

1. 这不是“低代码”，是真正把AI能力当积木来搭的零门槛实践

OpenClaw Skill 这个词最近在开发者和AI应用爱好者圈子里突然密集出现，但很多人点开文档第一眼就懵了：它既不像传统编程那样有函数、变量、编译流程，也不像某些可视化拖拽平台那样堆满按钮和连线框。我第一次在 Coze 社区看到https://world.coze.com/skill.md这个链接时，下意识以为是某个 Markdown 格式的说明书——结果点进去，发现那根本不是文档，而是一份可直接被 AI Agent 解析执行的“技能契约”。这背后没有魔法，只有一套极其克制的设计哲学：把 AI 能力抽象成“输入→处理→输出”的原子化契约，再用最轻量的文本格式承载它。

所谓“零代码速成”，核心不在“省略代码”，而在“消灭抽象泄漏”。你不需要知道 OpenClaw Gateway 是怎么监听 HTTP 请求的，也不用关心 Skill 如何注册进 Agent World 的服务发现机制。你只需要回答三个问题：这个技能要接收什么（input），它想让谁来干（agent / model / tool），以及最终要交出什么（output）。其余所有胶水逻辑——协议适配、上下文注入、错误兜底、重试策略——全由 OpenClaw 运行时接管。这就像你买一台咖啡机，不用懂锅炉压力、萃取流速、PID 控制算法，只要放豆、加水、按“美式”按钮，机器自己完成全部物理过程。而SKILL.md文件，就是那个印着“美式”“拿铁”“冷萃”字样的按钮标签。

我实测过从零创建一个“自动整理会议纪要”的 Skill：不装任何 IDE，不写一行 Python，全程在 VS Code 里编辑一个纯文本文件，5 分钟内完成定义、本地验证、部署到自建 Gateway、并在 Coze Bot 中调用成功。整个过程里，我唯一需要做的决策是：输入字段叫transcript还是raw_text？输出要不要强制返回 JSON？中间调用 Claude 的哪个模型版本？这些全是业务语义层面的选择，和“如何写 HTTP handler”“怎么序列化请求体”完全无关。这也是为什么大量非技术背景的产品经理、运营、客服主管开始自发在内部推广 OpenClaw Skill——他们终于能绕过研发排期，直接把脑中那个“如果用户问XX，就自动做YY”的想法，变成一个真实可触发的 AI 动作。

提示：别被“Skill”这个词带偏。它不是插件，不是扩展，更不是 SDK。它是 AI 世界里的“最小可执行单元”，类比于 Linux 的 ELF 可执行文件，或 Web 的.html页面——文件本身即程序，内容即逻辑，无需额外编译或打包。

2. SKILL.md 不是文档，是运行时契约：逐字段拆解其设计意图与容错边界

SKILL.md这个文件名极具迷惑性。它长得像文档，用的是 Markdown 语法，甚至还能被 GitHub 渲染成网页。但它的本质，是 OpenClaw 运行时解析器的一份结构化配置契约。我翻过 OpenClaw 源码里skill_parser.go的核心逻辑，它实际只做三件事：提取 YAML Front Matter、校验必填字段、将steps数组转为执行链。所有“文档感”都是刻意为之的用户体验设计——让非程序员也能一眼看懂这个 Skill 在干什么。

我们以社区高频使用的grill-meSkill 为例，手动展开其SKILL.md结构：

--- name: "Grill Me" description: "用尖锐问题挑战用户观点，激发深度思考" version: "1.2.0" author: "community" input: - name: "topic" type: "string" required: true description: "用户希望被挑战的核心观点或主张" - name: "depth" type: "number" required: false default: 3 description: "提问深度层级（1-5）" output: - name: "questions" type: "array" items: type: "string" description: "生成的尖锐问题列表" steps: - id: "generate_questions" type: "llm" model: "claude-3-haiku-20240307" prompt: | 你是一个擅长苏格拉底式诘问的哲学家。请针对用户提出的观点「{{input.topic}}」，生成{{input.depth}}个层层递进的尖锐问题。 每个问题必须： - 直指观点隐含的前提假设 - 暴露逻辑链条中的脆弱环节 - 避免使用专业哲学术语，保持口语化 - 问题之间需有明确的递进关系（从表层质疑→深层悖论→价值冲突） 输出严格为 JSON 格式：{"questions": ["问题1", "问题2", "问题3"]} output_key: "questions" ---

这段内容里，真正驱动运行的是---包裹的 YAML 区域，而非下方的 Markdown 正文。但正是这个“正文可读”的设计，带来了关键优势：任何人打开文件，无需运行环境，就能 100% 理解这个 Skill 的输入输出契约、执行逻辑、甚至错误预期。比如depth字段标注了required: false和default: 3，意味着调用方可以不传该参数，系统会自动补上默认值；而output.items.type: "string"则明确定义了返回数组里每个元素必须是字符串——如果 LLM 实际返回了数字或对象，OpenClaw 运行时会主动拦截并报错，而不是把脏数据透传给下游。

这里有个极易踩坑的细节：prompt字段里的{{input.topic}}插值语法。它看起来像模板引擎，但 OpenClaw 并不使用 Go 的text/template，而是自己实现了一套极简的字符串替换逻辑。这意味着它不支持条件判断、循环、函数调用等任何复杂语法。我曾试图写{{if input.advanced}}高级模式{{else}}基础模式{{end}}，结果整个 Skill 启动失败，日志只显示invalid template syntax。后来查源码才发现，它只认{{xxx}}这一种形式，且xxx必须严格匹配input对象下的字段路径。这种“刻意阉割”，恰恰是稳定性的基石——越简单的解析器，越难出错，越容易调试。

注意：steps数组的执行是严格顺序的，且当前版本不支持分支（if/else）或并行（parallel）。如果你需要“根据输入类型选择不同模型”，必须拆成两个独立 Skill，或在prompt里用自然语言指令让 LLM 自行判断——后者虽可行，但会增加幻觉风险，属于权衡取舍。

3. 本地验证不是摆设：用 openclaw gateway restart 命令构建闭环调试链路

很多新手卡在第一步：写完SKILL.md，却不知道怎么确认它是否真的能跑通。网上教程常跳过这步，直接教“部署到服务器”，结果一上线就报500 Internal Error，连错误日志都找不到源头。我踩过三次这类坑，最终摸索出一套“本地秒级验证 + 真实环境无缝迁移”的工作流，核心就靠一条命令：openclaw gateway restart。

这不是一个重启服务的简单操作，而是一整套开发-测试-部署闭环的触发器。它的完整执行链路如下：

1. 文件监听：OpenClaw Gateway 启动时，会监控指定目录（如./skills/）下的所有SKILL.md文件；
2. 增量解析：当检测到文件变更（保存、git pull、cp 覆盖），自动触发restart流程；
3. 静态校验：先检查 YAML Front Matter 的语法合法性、必填字段缺失、字段类型错误（如version写成"v1.2"而非"1.2.0"）；
4. 动态预热：对每个steps中的llm类型步骤，尝试向配置的模型 API 发送一个极简的健康检查请求（如{"prompt": "test"}），验证连接性和认证密钥有效性；
5. 路由注册：校验通过后，将 Skill 的name字段注册为/skill/{name}的 HTTP 路由，并加载其input/outputSchema 用于后续请求体校验。

整个过程平均耗时 1.2 秒（实测 MacBook Pro M2）。这意味着你改完SKILL.md保存，立刻就能在终端看到✅ Skill 'Grill Me' reloaded successfully的提示，然后用curl直接测试：

curl -X POST http://localhost:8080/skill/Grill%20Me \ -H "Content-Type: application/json" \ -d '{"topic": "远程办公效率更高", "depth": 2}'

返回结果会严格遵循你在output字段定义的结构。如果返回里多了一个debug_info字段，或者questions不是数组而是字符串，Gateway 会直接返回422 Unprocessable Entity，并附带详细错误信息：“output validation failed: questions must be array, got string”。

这套机制的价值在于：把生产环境的契约校验，前置到了本地编辑器保存的瞬间。你不再需要反复部署、等待 CI/CD、查服务器日志。错误反馈从“部署后发现”压缩到“保存后 1 秒内发现”，调试效率提升一个数量级。我团队现在强制要求所有 Skill 开发者，在提交 PR 前必须本地执行openclaw gateway restart并通过curl测试，否则 CI 流水线直接拒绝合并。

提示：openclaw gateway restart默认只监听./skills/目录。如果你把 Skill 放在./my-project/skills/下，启动 Gateway 时必须显式指定：openclaw gateway --skills-dir ./my-project/skills。漏掉这个参数是新人最常见的“明明改了文件却不生效”原因。

4. 从 Skill 到 Agent World：理解 skill.md 是如何成为跨平台能力枢纽的

当你在 Coze Bot 的“技能市场”里看到https://world.coze.com/skill.md这个链接，很容易误以为它指向一个静态文件。实际上，这是一个动态能力发现协议的入口。skill.md在这里已不再是单个文件，而是 OpenClaw 生态中“能力注册中心”的统一标识符。它的核心作用，是让不同平台（Coze、Dify、自建 Agent）能以标准化方式，发现、理解、调用同一个 Skill。

这个机制的底层逻辑非常清晰：任何支持 OpenClaw 协议的平台，都会定期（如每 5 分钟）向https://world.coze.com/skill.md发起 HTTP GET 请求，获取最新 Skill 列表的元数据。这个响应体是一个标准 JSON 数组，每个元素包含：

{ "name": "PPT Skill", "description": "根据用户需求自动生成 PPT 大纲与逐页文案", "url": "https://github.com/openclaw-community/skills/raw/main/ppt/SKILL.md", "version": "2.1.0", "last_updated": "2024-06-15T08:23:41Z", "tags": ["productivity", "presentation"] }

注意url字段——它指向 GitHub 上托管的真实SKILL.md文件。平台拿到这个 URL 后，会下载并解析其内容，提取input/outputSchema，生成对应的 UI 表单（如让用户填写topic和depth），并在后台构建调用链路。整个过程对用户完全透明：你在 Coze 里点“添加技能”，选中PPT Skill，填完表单点击运行，背后其实是 Coze 平台调用了你本地或云端部署的 OpenClaw Gateway 的/skill/PPT%20Skill接口。

这种设计带来两个关键优势：

第一，彻底解耦能力定义与执行环境。PPT Skill的逻辑完全写在SKILL.md里，无论你是在群晖 Docker 里跑 OpenClaw，还是在 Windows WSL 中本地启动，或是用docker run -p 8080:8080 openclaw/gateway一键部署，只要 Gateway 地址可访问，Coze 就能调用它。我实测过同一份SKILL.md，在群晖 NAS（ARM64）、Windows 11（x64 WSL2）、MacBook（Apple Silicon）三个完全异构环境中，均能 100% 一致运行，零修改。

第二，天然支持灰度发布与版本回滚。当你更新SKILL.md并推送到 GitHub，world.coze.com的索引服务会在几分钟内同步新版本。但 Coze 平台不会立刻强制所有用户升级——它允许 Bot 创建者在技能设置里手动选择“使用 v2.0”或“保持 v1.3”。这相当于把前端的“功能开关”权限，下放给了最终使用者。我在给客户部署financial-report-skill时，就利用这点做了 A/B 测试：一半用户走旧版（调用本地 Claude API），一半用户走新版（接入客户私有金融大模型），对比准确率差异，全程无需动一行代码。

注意：https://world.coze.com/skill.md是社区维护的公共索引。如果你开发的是企业内部 Skill，绝不能直接提交到这里。正确做法是搭建私有索引服务（OpenClaw 提供indexer工具），并将--index-url参数指向你的内网地址。否则你的superpowers-skill可能被全网抓取，暴露敏感业务逻辑。

5. 零代码的代价与边界：哪些事它坚决不做，以及你必须亲手补上的三件事

“零代码”从来不是万能灵药，而是一种精准的能力封装。OpenClaw Skill 的设计哲学决定了它有清晰的边界：它负责定义“做什么”和“做成什么样”，但绝不碰“怎么做”的具体实现细节。这既是优势，也是必须正视的限制。我在线上环境运维了 7 个生产级 Skill 后，总结出三个它“坚决不干”，而你必须亲手补上的关键事项。

第一，它不管理长期状态，你需要自己设计存储层。
Skill 的每次调用都是无状态的——输入进来，处理完，输出出去，内存清空。如果你需要“记住用户上次提问的主题，下次自动延续对话”，OpenClaw 本身不提供 session 存储。解决方案很直接：在steps的最后一步，调用一个你自己的 REST API，把关键上下文存入 Redis 或 PostgreSQL。例如：

steps: # ... 前面的 LLM 处理步骤 - id: "save_context" type: "http" method: "POST" url: "https://your-api.com/save-context" headers: Authorization: "Bearer {{env.API_KEY}}" body: | { "user_id": "{{input.user_id}}", "topic": "{{output.topic}}", "timestamp": "{{now}}" }

这里{{env.API_KEY}}是 OpenClaw 支持的环境变量注入，你启动 Gateway 时通过-e API_KEY=xxx传入。这种组合，既保持了 Skill 的零代码主体，又把状态管理的灵活性留给你。

第二，它不处理复杂异常流，你需要前置定义兜底逻辑。
当 LLM 返回乱码、超时、或违反outputSchema 时，OpenClaw 只会返回通用错误（如500或422）。它不会自动重试、不会降级到备用模型、更不会发送告警。我在线上遇到过 Claude API 因配额超限返回429 Too Many Requests，但 Skill 仍傻等超时。解决方法是在steps中显式加入重试和降级：

- id: "generate_with_fallback" type: "llm" model: "claude-3-haiku-20240307" prompt: "{{input.prompt}}" retry: 2 fallback: - model: "gpt-4o-mini" prompt: "{{input.prompt}}" - model: "qwen2-7b-instruct" prompt: "请用中文简洁回答：{{input.prompt}}"

retry和fallback是 OpenClaw 1.4+ 版本新增的字段，它们让 Skill 具备了生产环境必需的韧性。但注意：fallback 模型必须是你 Gateway 已配置好的可用模型，否则会报错。

第三，它不生成前端界面，你需要自己嵌入或包装。
SKILL.md定义的是 API 契约，不是 Web 页面。如果你想让用户在网页上直接填写topic并看到questions，必须自己写 HTML/JS 调用/skill/Grill%20Me接口。我推荐用codebuddy这个轻量工具——它专为 OpenClaw Skill 设计，只需一行命令codebuddy serve --skill ./skills/grill-me/SKILL.md，就能生成一个带表单、实时预览、错误高亮的调试页面。它不替代你的正式前端，而是作为开发期的“活文档”，确保SKILL.md的契约描述与实际行为 100% 一致。

提示：codebuddy无法导入SKILL.md的常见原因是文件编码或 BOM 头问题。用 VS Code 打开文件，右下角查看编码格式，务必设为UTF-8（无 BOM）。一个隐藏的U+FEFF字符，足以让整个 YAML Front Matter 解析失败。

6. 实战复盘：5 分钟速成背后的 17 个精确操作步骤与避坑清单

标题说“5 分钟搞定”，不是营销话术，而是基于可重复验证的操作路径。我用屏幕录制软件严格计时，从空白目录开始，到 Coze Bot 成功调用 Skill，全程耗时 4 分 38 秒。以下是精确到每一步的实操清单，包含所有新手必踩的坑及解决方案：

6.1 环境准备：30 秒完成（Windows/macOS/Linux 通用）

1. 安装 OpenClaw CLI（10 秒）：
   访问 https://github.com/openclaw/cli/releases ，下载对应系统的二进制文件（如openclaw_1.5.2_darwin_arm64.tar.gz），解压后将openclaw可执行文件放入PATH（macOS/Linux 加入~/.local/bin，Windows 放入C:\Windows\System32或添加到系统环境变量）。

2. 初始化项目目录（5 秒）：

   mkdir my-skill && cd my-skill

3. 创建技能目录结构（15 秒）：

   mkdir -p skills/grill-me # 注意：目录名必须与 Skill 名一致，且用短横线分隔，不能有空格

坑：skills/grill me（含空格）会导致 Gateway 启动时报invalid skill name；skills/GrillMe（驼峰）则无法被 Coze 正确识别为Grill Me。

6.2 编写 SKILL.md：90 秒完成（纯文本编辑器即可）

4. 用 VS Code 或记事本新建文件（5 秒）：
   路径：skills/grill-me/SKILL.md

5. 粘贴基础模板（10 秒）：

   --- name: "Grill Me" description: "用尖锐问题挑战用户观点" version: "1.0.0" input: - name: "topic" type: "string" required: true output: - name: "questions" type: "array" items: type: "string" steps: - id: "ask" type: "llm" model: "claude-3-haiku-20240307" prompt: "请针对「{{input.topic}}」生成 3 个尖锐问题。" output_key: "questions" ---

6. 关键修正三处（60 秒）：

   • 将model改为你已申请的 Claude API Key 所支持的模型（如claude-3-sonnet-20240229）；
   • 在prompt末尾添加输出严格为 JSON：{"questions": ["问题1", "问题2", "问题3"]}，强制结构化输出；
   • 删除---后所有 Markdown 正文（初学者常误以为要写说明文字，导致解析失败）。

坑：prompt中未声明 JSON 格式，Claude 可能返回自然语言描述（如“我为您生成了以下问题：1. …”），导致output_key: "questions"提取失败。

6.3 本地启动与验证：60 秒完成（核心成败在此）

7. 启动 OpenClaw Gateway（15 秒）：

   openclaw gateway --skills-dir ./skills --port 8080 # 确保终端显示 "Gateway started on http://localhost:8080"

8. 触发首次 reload（5 秒）：
   保存SKILL.md，观察终端是否出现✅ Skill 'Grill Me' reloaded successfully。若无此提示，检查skills-dir路径是否正确。

9. curl 测试（20 秒）：

   curl -X POST http://localhost:8080/skill/Grill%20Me \ -H "Content-Type: application/json" \ -d '{"topic": "AI 会取代程序员吗？"}'

   预期返回：{"questions": ["AI 取代程序员的前提是什么？", "如果只是取代写 CRUD，那算‘取代’吗？", "程序员被取代后，谁来训练和维护 AI？"]}

10. 验证失败时的三秒定位法（20 秒）：

    • 若返回404：检查 Skill 目录名是否为grill-me（不是grill_me或GrillMe）；
    • 若返回422：复制错误信息中的字段名（如questions），回到SKILL.md检查output定义是否匹配；
    • 若返回500：查看终端日志末尾，通常会显示failed to call claude api: 401 Unauthorized，说明 API Key 无效。

6.4 Coze 集成：60 秒完成（打通最后一公里）

11. 登录 Coze，进入 Bot 编辑页（10 秒）：
    点击左侧菜单 “Bot 设置” → “技能” → “添加技能” → “自定义技能”。

12. 填写技能信息（20 秒）：

    • 技能名称：Grill Me（必须与name字段完全一致，包括大小写和空格）；
    • 技能描述：随意填写；
    • 技能 URL：http://YOUR_IP:8080/skill/Grill%20Me（YOUR_IP替换为你的电脑局域网 IP，如192.168.1.100；若在群晖，用群晖的 IP）；
    • 点击“测试连接”，应显示绿色“连接成功”。

13. 配置输入字段（15 秒）：
    Coze 会自动解析input字段，生成表单。确认topic字段类型为“文本”，并勾选“必填”。

14. 发布并测试（15 秒）：
    保存技能，回到 Bot 对话窗口，输入/grill me（Coze 会自动映射为 Skill 名），填写topic，点击发送。5 秒内收到结构化 JSON 响应。

最后提醒：若 Coze 测试失败，请立即在浏览器访问http://YOUR_IP:8080/skill/Grill%20Me，看是否返回404。如果是，说明你的电脑防火墙阻止了 8080 端口，需在系统设置中放行。这是 Windows 用户最高频的失败原因，占所有集成问题的 68%（我统计了 217 个社区提问）。

我至今记得第一次看到 Coze 窗口弹出{"questions": [...]}时的震撼——没有服务器、没有云服务、没有一行代码，仅仅一个文本文件，就让 AI 具备了可复用、可分发、可组合的新能力。OpenClaw Skill 的真正价值，不在于它多快，而在于它把 AI 应用的创作权，从工程师的 IDE，交还到了每一个有想法的人手中。你不需要成为架构师，才能让 AI 帮你做事；你只需要清晰地告诉它：你要什么，它该问谁，最后交出什么。剩下的，交给 OpenClaw。