3. OpenClaw Skill 开发方法论：从 weather-bit 到 qrcode-gen

个人主页：
wengqidaifeng

✨ 永远在路上，永远向前走

个人专栏：
数据结构
 C语言
 嵌入式小白启动！
重要OJ算法题详解
 蓝桥杯备战
 C++从菜鸟到强手
 python启航
 AI大模型Agent：拥抱未来，赋能自己

文章目录

[OpenClaw Skill 开发方法论：从 weather-bit 到 qrcode-gen](#OpenClaw Skill 开发方法论：从 weather-bit 到 qrcode-gen)
- [一、Skill 到底是什么](#一、Skill 到底是什么)
- [二、一个 Skill 的最小结构长什么样](#二、一个 Skill 的最小结构长什么样)
- [三、为什么 `SKILL.md` 是整个机制的灵魂](#三、为什么 SKILL.md 是整个机制的灵魂)
- - [1. 元数据职责](#1. 元数据职责)
  - [2. 行为指令职责](#2. 行为指令职责)
- [四、渐进式披露机制，为什么是 Skill 设计的关键思想](#四、渐进式披露机制，为什么是 Skill 设计的关键思想)
- [五、说明型 Skill 与脚本型 Skill，不是对立关系](#五、说明型 Skill 与脚本型 Skill，不是对立关系)
- - [1. `weather-bit`：最典型的说明型 + 脚本调用](#1. weather-bit：最典型的说明型 + 脚本调用)
  - [2. `qrcode-gen`：从说明走向可交付工具](#2. qrcode-gen：从说明走向可交付工具)
- [六、写好一个 Skill，核心不是会编程，而是会定义任务边界](#六、写好一个 Skill，核心不是会编程，而是会定义任务边界)
- [七、一个优秀 `description` 应该怎么写](#七、一个优秀 description 应该怎么写)
- - [1. 功能是什么](#1. 功能是什么)
  - [2. 触发场景是什么](#2. 触发场景是什么)
  - [3. 结果会返回什么](#3. 结果会返回什么)
- [八、一个好 Skill 的正文通常要包含哪些部分](#八、一个好 Skill 的正文通常要包含哪些部分)
- [九、Skill 开发的推荐流程](#九、Skill 开发的推荐流程)
- - [1. 先写需求，不要先写代码](#1. 先写需求，不要先写代码)
  - [2. 先写 `SKILL.md` 的骨架](#2. 先写 SKILL.md 的骨架)
  - [3. 再决定是否需要脚本](#3. 再决定是否需要脚本)
  - [4. 脚本先单独跑通](#4. 脚本先单独跑通)
  - [5. 再接入 OpenClaw](#5. 再接入 OpenClaw)
  - [6. 用真实对话测试触发效果](#6. 用真实对话测试触发效果)
  - [7. 持续迭代描述与目录结构](#7. 持续迭代描述与目录结构)
- 十、从两个小案例能学到哪些通用原则
- - 原则一：小步起步
  - 原则二：面向结果设计
  - 原则三：把依赖写明白
  - 原则四：说明优先于炫技
- [十一、Skill 生态为什么会成为 OpenClaw 的护城河](#十一、Skill 生态为什么会成为 OpenClaw 的护城河)
- [十二、从 Anthropic Agent Skills 看 Skill 设计的共性](#十二、从 Anthropic Agent Skills 看 Skill 设计的共性)
- - [1. 用自然语言描述触发场景](#1. 用自然语言描述触发场景)
  - [2. 用文件系统组织能力](#2. 用文件系统组织能力)
  - [3. 用按需加载控制上下文](#3. 用按需加载控制上下文)
- [十三、`SKILL.md` 的质量，决定 Skill 的上限](#十三、SKILL.md 的质量，决定 Skill 的上限)
- - [1. `name` 要短、稳定、可识别](#1. name 要短、稳定、可识别)
  - [2. `description` 要写"触发条件"，不是写宣传语](#2. description 要写“触发条件”，不是写宣传语)
  - [3. 正文要写执行路径](#3. 正文要写执行路径)
- [十四、让 Agent 更容易选中 Skill 的写法](#十四、让 Agent 更容易选中 Skill 的写法)
- 何时使用这个技能
- [十五、脚本接口设计：Skill 稳不稳定，很多时候取决于命令行参数](#十五、脚本接口设计：Skill 稳不稳定，很多时候取决于命令行参数)
- [十六、输出设计：让 Skill 的结果能被下一步使用](#十六、输出设计：让 Skill 的结果能被下一步使用)
- - [1. 文本输出要简洁](#1. 文本输出要简洁)
  - [2. 文件输出要路径明确](#2. 文件输出要路径明确)
  - [3. 结构化输出适合复杂任务](#3. 结构化输出适合复杂任务)
  - [4. 失败输出要可解释](#4. 失败输出要可解释)
- [十七、依赖管理：从教学脚本走向可复用 Skill 的关键一步](#十七、依赖管理：从教学脚本走向可复用 Skill 的关键一步)
- [十八、Skill 的测试，不只是测试脚本](#十八、Skill 的测试，不只是测试脚本)
- - [1. 脚本单测](#1. 脚本单测)
  - [2. 文档检查](#2. 文档检查)
  - [3. 本地命令测试](#3. 本地命令测试)
  - [4. Agent 触发测试](#4. Agent 触发测试)
- [十九、Skill 版本迭代：别让小工具变成无主脚本](#十九、Skill 版本迭代：别让小工具变成无主脚本)
- 维护信息
- [二十、一个可复用的 Skill 开发检查清单](#二十、一个可复用的 Skill 开发检查清单)
- - `SKILL.md`
  - 脚本
  - 运行
  - 安全
- 二十一、参考资料
- [二十二、三种常见 Skill 类型的写法差异](#二十二、三种常见 Skill 类型的写法差异)
- - [1. 查询型 Skill](#1. 查询型 Skill)
  - [2. 生成型 Skill](#2. 生成型 Skill)
  - [3. 流程型 Skill](#3. 流程型 Skill)
- [二十三、Skill 文档的语气：写给 Agent，也写给未来维护者](#二十三、Skill 文档的语气：写给 Agent，也写给未来维护者)
- [二十四、从一个小 Skill 到一组 Skill：组合能力怎么设计](#二十四、从一个小 Skill 到一组 Skill：组合能力怎么设计)
- 二十五、结语

OpenClaw Skill 开发方法论：从 weather-bit 到 qrcode-gen

面向想亲手扩展 OpenClaw 能力的读者：这篇文章用两个轻量 Skill 做入口，讲清楚 SKILL.md、脚本、依赖、测试和可复用能力之间的关系。

OpenClaw 最迷人的地方，不是它内置了多少功能，而是它把"给 AI 增加新能力"这件事做成了一套开发者可以掌握、团队可以复用、项目可以沉淀的标准机制。这套机制就是 Skill。本文之所以把重点从平台介绍转向 Skill 规范，不是因为 Skill 只是"插件开发"，而是因为 Skill 决定了 OpenClaw 能否真正长出业务肌肉。
#mermaid-svg-CPpVQOQwhVlYdJJN{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-CPpVQOQwhVlYdJJN .error-icon{fill:#552222;}#mermaid-svg-CPpVQOQwhVlYdJJN .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-CPpVQOQwhVlYdJJN .marker{fill:#333333;stroke:#333333;}#mermaid-svg-CPpVQOQwhVlYdJJN .marker.cross{stroke:#333333;}#mermaid-svg-CPpVQOQwhVlYdJJN svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-CPpVQOQwhVlYdJJN p{margin:0;}#mermaid-svg-CPpVQOQwhVlYdJJN .edge{stroke-width:3;}#mermaid-svg-CPpVQOQwhVlYdJJN .section--1 rect,#mermaid-svg-CPpVQOQwhVlYdJJN .section--1 path,#mermaid-svg-CPpVQOQwhVlYdJJN .section--1 circle,#mermaid-svg-CPpVQOQwhVlYdJJN .section--1 polygon,#mermaid-svg-CPpVQOQwhVlYdJJN .section--1 path{fill:hsl(240, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .section--1 text{fill:#ffffff;}#mermaid-svg-CPpVQOQwhVlYdJJN .node-icon--1{font-size:40px;color:#ffffff;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-edge--1{stroke:hsl(240, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-depth--1{stroke-width:17;}#mermaid-svg-CPpVQOQwhVlYdJJN .section--1 line{stroke:hsl(60, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled circle,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:lightgray;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:#efefef;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-0 rect,#mermaid-svg-CPpVQOQwhVlYdJJN .section-0 path,#mermaid-svg-CPpVQOQwhVlYdJJN .section-0 circle,#mermaid-svg-CPpVQOQwhVlYdJJN .section-0 polygon,#mermaid-svg-CPpVQOQwhVlYdJJN .section-0 path{fill:hsl(60, 100%, 73.5294117647%);}#mermaid-svg-CPpVQOQwhVlYdJJN .section-0 text{fill:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .node-icon-0{font-size:40px;color:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-edge-0{stroke:hsl(60, 100%, 73.5294117647%);}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-depth-0{stroke-width:14;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-0 line{stroke:hsl(240, 100%, 83.5294117647%);stroke-width:3;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled circle,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:lightgray;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:#efefef;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-1 rect,#mermaid-svg-CPpVQOQwhVlYdJJN .section-1 path,#mermaid-svg-CPpVQOQwhVlYdJJN .section-1 circle,#mermaid-svg-CPpVQOQwhVlYdJJN .section-1 polygon,#mermaid-svg-CPpVQOQwhVlYdJJN .section-1 path{fill:hsl(80, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .section-1 text{fill:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .node-icon-1{font-size:40px;color:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-edge-1{stroke:hsl(80, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-depth-1{stroke-width:11;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-1 line{stroke:hsl(260, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled circle,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:lightgray;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:#efefef;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-2 rect,#mermaid-svg-CPpVQOQwhVlYdJJN .section-2 path,#mermaid-svg-CPpVQOQwhVlYdJJN .section-2 circle,#mermaid-svg-CPpVQOQwhVlYdJJN .section-2 polygon,#mermaid-svg-CPpVQOQwhVlYdJJN .section-2 path{fill:hsl(270, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .section-2 text{fill:#ffffff;}#mermaid-svg-CPpVQOQwhVlYdJJN .node-icon-2{font-size:40px;color:#ffffff;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-edge-2{stroke:hsl(270, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-depth-2{stroke-width:8;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-2 line{stroke:hsl(90, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled circle,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:lightgray;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:#efefef;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-3 rect,#mermaid-svg-CPpVQOQwhVlYdJJN .section-3 path,#mermaid-svg-CPpVQOQwhVlYdJJN .section-3 circle,#mermaid-svg-CPpVQOQwhVlYdJJN .section-3 polygon,#mermaid-svg-CPpVQOQwhVlYdJJN .section-3 path{fill:hsl(300, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .section-3 text{fill:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .node-icon-3{font-size:40px;color:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-edge-3{stroke:hsl(300, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-depth-3{stroke-width:5;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-3 line{stroke:hsl(120, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled circle,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:lightgray;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:#efefef;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-4 rect,#mermaid-svg-CPpVQOQwhVlYdJJN .section-4 path,#mermaid-svg-CPpVQOQwhVlYdJJN .section-4 circle,#mermaid-svg-CPpVQOQwhVlYdJJN .section-4 polygon,#mermaid-svg-CPpVQOQwhVlYdJJN .section-4 path{fill:hsl(330, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .section-4 text{fill:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .node-icon-4{font-size:40px;color:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-edge-4{stroke:hsl(330, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-depth-4{stroke-width:2;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-4 line{stroke:hsl(150, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled circle,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:lightgray;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:#efefef;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-5 rect,#mermaid-svg-CPpVQOQwhVlYdJJN .section-5 path,#mermaid-svg-CPpVQOQwhVlYdJJN .section-5 circle,#mermaid-svg-CPpVQOQwhVlYdJJN .section-5 polygon,#mermaid-svg-CPpVQOQwhVlYdJJN .section-5 path{fill:hsl(0, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .section-5 text{fill:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .node-icon-5{font-size:40px;color:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-edge-5{stroke:hsl(0, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-depth-5{stroke-width:-1;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-5 line{stroke:hsl(180, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled circle,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:lightgray;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:#efefef;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-6 rect,#mermaid-svg-CPpVQOQwhVlYdJJN .section-6 path,#mermaid-svg-CPpVQOQwhVlYdJJN .section-6 circle,#mermaid-svg-CPpVQOQwhVlYdJJN .section-6 polygon,#mermaid-svg-CPpVQOQwhVlYdJJN .section-6 path{fill:hsl(30, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .section-6 text{fill:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .node-icon-6{font-size:40px;color:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-edge-6{stroke:hsl(30, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-depth-6{stroke-width:-4;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-6 line{stroke:hsl(210, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled circle,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:lightgray;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:#efefef;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-7 rect,#mermaid-svg-CPpVQOQwhVlYdJJN .section-7 path,#mermaid-svg-CPpVQOQwhVlYdJJN .section-7 circle,#mermaid-svg-CPpVQOQwhVlYdJJN .section-7 polygon,#mermaid-svg-CPpVQOQwhVlYdJJN .section-7 path{fill:hsl(90, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .section-7 text{fill:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .node-icon-7{font-size:40px;color:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-edge-7{stroke:hsl(90, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-depth-7{stroke-width:-7;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-7 line{stroke:hsl(270, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled circle,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:lightgray;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:#efefef;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-8 rect,#mermaid-svg-CPpVQOQwhVlYdJJN .section-8 path,#mermaid-svg-CPpVQOQwhVlYdJJN .section-8 circle,#mermaid-svg-CPpVQOQwhVlYdJJN .section-8 polygon,#mermaid-svg-CPpVQOQwhVlYdJJN .section-8 path{fill:hsl(150, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .section-8 text{fill:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .node-icon-8{font-size:40px;color:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-edge-8{stroke:hsl(150, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-depth-8{stroke-width:-10;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-8 line{stroke:hsl(330, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled circle,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:lightgray;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:#efefef;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-9 rect,#mermaid-svg-CPpVQOQwhVlYdJJN .section-9 path,#mermaid-svg-CPpVQOQwhVlYdJJN .section-9 circle,#mermaid-svg-CPpVQOQwhVlYdJJN .section-9 polygon,#mermaid-svg-CPpVQOQwhVlYdJJN .section-9 path{fill:hsl(180, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .section-9 text{fill:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .node-icon-9{font-size:40px;color:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-edge-9{stroke:hsl(180, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-depth-9{stroke-width:-13;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-9 line{stroke:hsl(0, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled circle,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:lightgray;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:#efefef;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-10 rect,#mermaid-svg-CPpVQOQwhVlYdJJN .section-10 path,#mermaid-svg-CPpVQOQwhVlYdJJN .section-10 circle,#mermaid-svg-CPpVQOQwhVlYdJJN .section-10 polygon,#mermaid-svg-CPpVQOQwhVlYdJJN .section-10 path{fill:hsl(210, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .section-10 text{fill:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .node-icon-10{font-size:40px;color:black;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-edge-10{stroke:hsl(210, 100%, 76.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .edge-depth-10{stroke-width:-16;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-10 line{stroke:hsl(30, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled circle,#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:lightgray;}#mermaid-svg-CPpVQOQwhVlYdJJN .disabled text{fill:#efefef;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-root rect,#mermaid-svg-CPpVQOQwhVlYdJJN .section-root path,#mermaid-svg-CPpVQOQwhVlYdJJN .section-root circle,#mermaid-svg-CPpVQOQwhVlYdJJN .section-root polygon{fill:hsl(240, 100%, 46.2745098039%);}#mermaid-svg-CPpVQOQwhVlYdJJN .section-root text{fill:#ffffff;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-root span{color:#ffffff;}#mermaid-svg-CPpVQOQwhVlYdJJN .section-2 span{color:#ffffff;}#mermaid-svg-CPpVQOQwhVlYdJJN .icon-container{height:100%;display:flex;justify-content:center;align-items:center;}#mermaid-svg-CPpVQOQwhVlYdJJN .edge{fill:none;}#mermaid-svg-CPpVQOQwhVlYdJJN .mindmap-node-label{dy:1em;alignment-baseline:middle;text-anchor:middle;dominant-baseline:middle;text-align:center;}#mermaid-svg-CPpVQOQwhVlYdJJN :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} OpenClaw Skill
SKILL.md
YAML 元数据
触发描述
使用步骤
输入输出
scripts
Python
Shell
Node
可测试接口
references
规则文档
API 说明
示例资料
assets
模板
图片
配置片段
运行验证
本地脚本测试
Agent 触发测试
依赖检查

注意：本文资料地址：

OpenClaw Agent 与 Skill 开发公开资料集

一、Skill 到底是什么

更准确地说，Skill 是 OpenClaw 功能扩展的核心机制，它通过标准化接口，把某种特定能力封装成独立的软件包，供 Agent 在适当时机自动调用。

这句话可以拆成四个关键词：

标准化
独立性
可被 Agent 理解
可被任务自动调用

所以 Skill 不是"随便写个脚本"那么简单，也不是"只写几句提示词"那么轻。它本质上是一种面向 Agent 的能力封装规范。

可以用一个很形象的类比理解：

Agent 是大脑
Skill 是双手
Tools 是基础工具

大脑决定要不要做、先做什么、后做什么；双手负责把动作真的做出来。没有 Skill，OpenClaw 很容易停留在"会解释"的层面；有了 Skill，它才可能进入"会执行"的层面。

二、一个 Skill 的最小结构长什么样

结合 Agent Skills 的通用做法和 OpenClaw 的 Skill 组织方式，一个 Skill 的核心结构通常是：

text 复制代码

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

其中真正"必需"的文件只有一个：SKILL.md。这点非常重要。也就是说，一个最小 Skill 完全可以先只有一个 Markdown 文件，甚至暂时没有脚本。

各目录的职责可以这样理解：

SKILL.md：Skill 的入口定义文件，既包含元数据，也包含给 Agent 的指令
scripts/：放可执行脚本，适合 Python、Shell、Node 等
references/：放补充说明、规则文档、表格、接口说明
assets/：放模板、图片、配置片段、生成资源

这一结构最大的好处，是把"让 Agent 理解能力"和"让代码实现能力"拆开了。前者由 SKILL.md 完成，后者由脚本和资源文件完成。

三、为什么 `SKILL.md` 是整个机制的灵魂

SKILL.md 是每个 Skill 最关键的入口文件，通常采用 YAML Frontmatter + Markdown 指令 的格式。也就是说，它同时承担两层职责：

1. 元数据职责

最核心的元数据至少包括：

name
description

其中 name 是技能标识符，description 决定 Agent 如何在发现阶段判断这个 Skill 是否相关。这个设计非常关键，因为 Agent 启动时不是把所有 Skill 的全文都读一遍，而是先看这些简短描述，再决定是否激活。

2. 行为指令职责

当 Agent 认为任务和某个 Skill 匹配时，它才会加载完整的 SKILL.md 内容，进一步理解：

这个技能何时使用
如何使用
是否需要调用脚本
输入输出长什么样
遇到错误时怎么办

也就是说，description 决定"能不能被发现"，正文决定"被发现后能不能被正确执行"。

四、渐进式披露机制，为什么是 Skill 设计的关键思想

这类 Skill 机制通常遵循三阶段加载思路：

发现阶段：只加载 name 和 description
激活阶段：任务匹配时加载完整 SKILL.md
执行阶段：按需读取脚本、引用文档、调用资源

这个机制背后的设计思想很先进，因为它天然在控制上下文成本。对于大模型系统来说，上下文就是预算，也是速度，更是稳定性。把所有 Skill 的全部内容一股脑塞给模型，既浪费，又容易干扰。

因此，一个优秀 Skill 的写法，首先不是"越长越好"，而是"发现信息足够准确，激活说明足够清晰，执行资源按需加载"。这就是 Skill 开发和普通文档写作最大的不同。

五、说明型 Skill 与脚本型 Skill，不是对立关系

我们可以通过两个基础案例把这个问题讲清楚：

weather-bit
qrcode-gen

1. `weather-bit`：最典型的说明型 + 脚本调用

仓库里的 代码/weather-bit/SKILL.md 很简洁。它做了几件事：

用 Frontmatter 说明名称和用途
明确什么时候该用这个技能
给出脚本调用示例：python scripts/get_weather.py 上海

这个 Skill 的关键不是脚本多复杂，而是触发条件写得足够明确。比如：

询问某个城市天气
询问温度
询问是否需要带伞
查询出行相关天气信息

对于 Agent 来说，这种"何时使用"的描述，远比花哨文案更重要。

2. `qrcode-gen`：从说明走向可交付工具

代码/qrcode-gen/SKILL.md 则进一步展示了更实用的一类 Skill。它除了说明用途，还补上了：

依赖安装方式：pip install qrcode[pil]
适用场景：网址、文本、密码都能生成二维码
使用命令：python scripts/make_qr.py "https://openclaw.ai/"
输出位置：生成结果保存到 output 目录

这意味着一个 Skill 不只是"告诉 Agent 可以做什么"，还开始关心：

初次运行前依赖是否明确
结果产物输出到哪里
用户是否知道执行后的预期结果

这已经接近可交付的工程单元，而不只是演示脚本。

六、写好一个 Skill，核心不是会编程，而是会定义任务边界

SKILL.md 是纯文本说明，真正涉及编程语言的是 scripts/。这带来一个重要结论：不会写复杂代码，也仍然可以设计出有价值的 Skill。

因为 Skill 开发的第一能力，不是语法能力，而是任务设计能力。你至少要说清楚：

什么时候该调用这个 Skill
输入是什么
输出是什么
是否依赖外部资源
有没有限制条件
失败时如何处理

如果这些边界说不清，即便脚本写得再漂亮，Agent 也很难稳定使用。

反过来，如果边界定义得非常清楚，即使脚本本身很简单，Skill 也会很好用。

七、一个优秀 `description` 应该怎么写

从配套示例可以看出，好的 description 大致具备三层信息：

1. 功能是什么

比如"查询天气""生成二维码""抓取钛媒体早报"。

2. 触发场景是什么

比如"当用户询问天气、温度、是否下雨时自动使用此技能"。

3. 结果会返回什么

比如"返回天气状况、温度、风向、湿度"，或者"生成二维码图片并输出到指定目录"。

这三层信息组合起来，能让 Agent 在发现阶段做出相对稳定的技能匹配判断。

八、一个好 Skill 的正文通常要包含哪些部分

结合 Skill 规范和配套示例，一个面向实用的 SKILL.md 建议至少包括以下结构：

markdown 复制代码

---
name: xxx
description: xxx
---

# Skill 名称

## 何时使用这个技能

## 如何使用这个技能

## 输入要求

## 输出说明

## 依赖与初始化

## 注意事项 / 失败处理

其中最不能省略的是：

何时使用
如何使用

因为这两段分别对应"触发判断"和"执行动作"。

九、Skill 开发的推荐流程

结合实际开发经验，我建议把 Skill 开发总结成下面七步：

1. 先写需求，不要先写代码

先定义这个 Skill 是为了解决什么问题。很多 Skill 最后变得难以维护，往往不是因为代码差，而是因为最开始需求就模糊。

2. 先写 `SKILL.md` 的骨架

先把名字、描述、适用场景、调用方式写出来。这个动作会强迫你把任务边界说清。

3. 再决定是否需要脚本

有些 Skill 只需要说明与已有工具配合的方式，不一定需要自定义脚本；有些 Skill 则必须在 scripts/ 里放执行逻辑。

4. 脚本先单独跑通

本地先直接跑 python scripts/xxx.py 验证脚本。不要一开始就放进 Agent 里黑盒测试。

5. 再接入 OpenClaw

可以安装到技能目录，或通过对应方式注册，让 Agent 能发现并调用它。

6. 用真实对话测试触发效果

不仅测脚本结果，还要测 Agent 会不会在恰当时机自动启用该 Skill。

7. 持续迭代描述与目录结构

如果触发不稳定，先改 description 和"何时使用"段落；如果执行不稳定，再回头改脚本。这是非常高效的调试顺序。

十、从两个小案例能学到哪些通用原则

原则一：小步起步

weather-bit 的价值在于它足够小。它证明 Skill 不必一开始就做成复杂系统，只要触发条件清晰、调用方式明确，就已经是一个合格起点。

原则二：面向结果设计

qrcode-gen 不是只说"能生成二维码"，而是告诉你结果产物在哪里。一个好 Skill 应该始终关心"执行后用户能拿到什么"。

原则三：把依赖写明白

是否需要 pip install，首次初始化怎么做，这些都不该留给使用者猜。

原则四：说明优先于炫技

很多 Skill 的失败，不是因为能力不够，而是因为 Agent 不知道什么时候该用、怎么用。说明文档的精度，往往比代码复杂度更重要。

十一、Skill 生态为什么会成为 OpenClaw 的护城河

从平台视角看，模型能力会逐渐趋同，基础工具也会逐渐普及，真正拉开差距的，往往是生态中沉淀下来的 Skill 资产。

对个人开发者来说，Skill 是自己能力模块化、可复用化的方式。

对团队来说，Skill 是把业务经验转成可执行资产的方式。

对平台来说，Skill 生态越丰富，OpenClaw 就越像一个可扩展的 AI 操作系统，而不是单点工具。

ClawHub 这类技能市场，本质上就是在解决 Skill 的共享、分发和复用问题。一个成熟的 Agent 平台，最终一定会进入"生态竞争"而不是只停留在"模型接入竞争"。

十二、从 Anthropic Agent Skills 看 Skill 设计的共性

OpenClaw 的 Skill 机制并不是孤立出现的。Anthropic 的 Claude Code Skills 也采用了非常相似的思路：每个 Skill 是一个目录，核心文件是 SKILL.md，通过 YAML 元数据描述名称和用途，再用 Markdown 写具体说明，必要时配套脚本、资源和参考文档。

这说明 Agent Skill 已经形成了一种比较清晰的行业共识：让模型稳定执行复杂任务，不能只靠一次性提示词，而要把可复用流程沉淀成文件化、模块化、可加载的能力包。

两者背后的共性至少有三点。

1. 用自然语言描述触发场景

模型擅长理解自然语言，所以 Skill 的入口不是传统函数签名，而是 description。这让 Agent 能根据用户意图判断是否需要加载某个 Skill。

2. 用文件系统组织能力

Skill 通常不是单个函数，而是一组说明、脚本、模板、样例和资源。用文件夹组织，既利于版本控制，也利于团队审查。

3. 用按需加载控制上下文

Agent 不需要每次都读完所有 Skill。先看描述，匹配后再加载完整说明，执行时再按需读取脚本或参考资料。这个模式能显著降低上下文噪音。

理解这些共性后，再回头看 OpenClaw 的 weather-bit 和 qrcode-gen，就能发现它们虽然简单，但已经踩在这套通用设计上：先让 Agent 发现，再让 Agent 理解，再让 Agent 执行。

十三、`SKILL.md` 的质量，决定 Skill 的上限

很多人写 Skill 时会把精力都放在脚本上，觉得 SKILL.md 只是说明书。实际恰好相反：对于 Agent 来说，SKILL.md 是能力入口，是路标，是执行合同。

一个脚本写得再好，如果 Agent 不知道什么时候调用它，用户体验依然会很差。一个 SKILL.md 写得清楚，即使脚本很小，也能让能力表现稳定。

1. `name` 要短、稳定、可识别

Skill 名称最好使用小写字母和连字符，例如：

yaml 复制代码

name: qrcode-gen

名称不需要写成长句，因为它不是给用户看的标题，而是给系统识别的标识。名称一旦被其他文档、自动化任务或团队习惯引用，频繁修改会造成维护成本。

2. `description` 要写"触发条件"，不是写宣传语

差的描述通常是：

yaml 复制代码

description: 一个非常强大的二维码生成工具。

这句话听起来不错，但对 Agent 判断没有太大帮助。更好的描述是：

yaml 复制代码

description: 当用户需要把网址、文本、密码或短字符串生成二维码图片时使用此技能。

后者明确告诉 Agent：什么输入、什么意图、什么结果。

3. 正文要写执行路径

正文不能只写"本技能可以生成二维码"，还要写：

先检查依赖
调用哪个脚本
参数怎么传
输出保存在哪里
失败时怎么提示

Agent 不是人类开发者，它不会自然知道你脚本的隐藏约定。约定越显式，执行越稳定。

十四、让 Agent 更容易选中 Skill 的写法

Skill 触发不稳定，很多时候不是模型不聪明，而是描述没有覆盖用户真实表达。比如用户可能不会说"生成二维码"，而会说：

把这个链接做成码
给我转成扫一扫能打开的图片
做一个二维码给同事
这个 Wi-Fi 密码能不能弄成扫码的

如果 description 和"何时使用"只写了"生成二维码"，模型也许能猜到，但稳定性会下降。更好的写法是把常见意图展开：

何时使用这个技能

当用户想把以下内容转换为二维码时使用：

网址链接
普通文本
Wi-Fi 密码
联系方式
短口令或邀请码

同样，天气 Skill 也应该覆盖用户常见问法：

今天要不要带伞
上海冷不冷
明天适合出门吗
北京现在多少度

这不是堆关键词，而是在帮助 Agent 建立"用户表达"和"技能能力"之间的桥。

十五、脚本接口设计：Skill 稳不稳定，很多时候取决于命令行参数

当 Skill 需要调用 scripts/ 下的代码时，脚本接口要尽量简单、明确、可预测。最糟糕的情况是脚本只能在人手工操作时跑通，Agent 调用时却经常因为参数格式、工作目录、输出路径失败。

一个适合 Skill 调用的脚本，最好满足这些要求：

输入参数明确
输出结果稳定
错误信息可读
不依赖隐含工作目录
必要目录自动创建
不把敏感信息打印到控制台
退出码能反映成功或失败

以 qrcode-gen 为例，命令是：

bash 复制代码

python scripts/make_qr.py "https://openclaw.ai/"

这就是一个比较清楚的接口：一个参数，表示二维码内容。输出保存到固定目录。Agent 很容易照着调用。

如果脚本参数越来越多，就建议引入命名参数：

bash 复制代码

python scripts/make_qr.py --text "https://openclaw.ai/" --output output/openclaw.png

命名参数比位置参数更适合复杂 Skill，因为它可读性更强，也更不容易传错顺序。

十六、输出设计：让 Skill 的结果能被下一步使用

Skill 的结果不只是给用户看，也可能被 Agent 后续步骤继续使用。所以输出设计很重要。

1. 文本输出要简洁

脚本执行成功后，最好输出关键信息，例如：

text 复制代码

二维码已生成: output/openclaw.png

不要输出一大堆调试日志，让 Agent 难以判断重点。

2. 文件输出要路径明确

如果生成图片、文档、表格，一定要返回完整或相对稳定的路径。否则用户不知道结果在哪里，Agent 也无法继续引用。

3. 结构化输出适合复杂任务

如果 Skill 输出多字段结果，可以考虑 JSON，例如：

json 复制代码

{
  "success": true,
  "file": "output/openclaw.png",
  "format": "png"
}

这类输出更利于后续自动化处理。

4. 失败输出要可解释

不要只输出 error。更好的错误信息应该告诉用户：

失败原因
是否缺依赖
是否参数错误
是否可以重试

比如"缺少 qrcode 依赖，请先运行 pip install qrcode[pil]"就比"ModuleNotFoundError"友好得多。

十七、依赖管理：从教学脚本走向可复用 Skill 的关键一步

配套示例 qrcode-gen 已经提醒首次使用前需要安装 qrcode[pil]。这就是依赖管理的最小版本。更复杂的 Skill 应该进一步规范化。

常见做法包括：

在 Skill 根目录放 requirements.txt
在 SKILL.md 写清初始化命令
提供 scripts/setup.bat 或 scripts/setup.sh
在脚本启动时检测关键依赖
明确 Python 版本要求

依赖管理的目标不是"让文档更完整"，而是减少 Agent 执行时的不确定性。

以 tmtpost-news-daily 为例，它需要：

playwright
beautifulsoup4
requests
pyyaml

而 Playwright 还需要额外安装 Chromium：

bash 复制代码

python -m playwright install chromium

如果这一步没做，脚本可能在运行时失败。对 Skill 来说，这类"二段式依赖"尤其要写清楚。

十八、Skill 的测试，不只是测试脚本

普通脚本测试关注输入输出，Skill 测试还要多一层：Agent 能不能正确发现和调用。

建议把 Skill 测试分成四层。

1. 脚本单测

直接运行脚本，确认核心逻辑正确。例如二维码脚本能否生成图片，天气脚本能否处理城市参数。

2. 文档检查

检查 SKILL.md 是否包含：

name
description
何时使用
如何使用
依赖说明
输出说明

3. 本地命令测试

从 Skill 根目录执行文档中的命令，确认路径没有问题。

4. Agent 触发测试

在 OpenClaw TUI 或 WebUI 中用自然语言测试，例如：

text 复制代码

帮我把 https://github.com/openclaw 生成二维码

如果 Agent 没有调用 Skill，优先调整 description 和"何时使用"段落，而不是急着改脚本。

这四层测试能覆盖一个 Skill 从"代码可用"到"Agent 可用"的全过程。

十九、Skill 版本迭代：别让小工具变成无主脚本

当 Skill 数量变多后，最容易出现的问题是：每个 Skill 都能跑，但没人知道谁维护、依赖是什么、适用边界在哪里。为了避免这种情况，建议从一开始就建立轻量版本习惯。

可以在 SKILL.md 或额外文档里记录：

维护人
最近更新时间
支持平台
依赖版本
已知限制
变更说明

比如：

维护信息

支持平台：Windows / macOS / Linux
Python：3.10+
最近更新：2026-05
已知限制：当前仅支持 PNG 输出

这不是为了仪式感，而是为了让未来的自己和团队成员少踩坑。

二十、一个可复用的 Skill 开发检查清单

写完一个 Skill 后，可以用下面这份清单快速自检。

`SKILL.md`

是否有合法 Frontmatter
name 是否短且稳定
description 是否包含触发场景
是否写了"何时使用"
是否写了"如何使用"
是否说明输入输出
是否说明依赖和初始化

脚本

是否能从 Skill 根目录直接运行
参数是否清楚
输出是否稳定
错误信息是否可读
是否避免打印敏感信息
是否自动创建输出目录

运行

是否在终端手动测试过
是否在 OpenClaw 对话中触发过
是否处理了缺依赖场景
是否记录了生成文件路径

安全

是否只访问必要文件
是否不硬编码密钥
是否不执行无边界命令
是否说明外部网络访问

这份清单能帮助 Skill 从"我本机能跑"升级到"别人也能用"。

二十一、参考资料

Claude Code Skills 文档：理解 Agent Skills 的目录结构、SKILL.md、脚本和资源组织方式
OpenClaw Capabilities 文档：理解 OpenClaw 中工具、Skill、插件和自动化能力的区别
Model Context Protocol 官方介绍：理解工具和上下文标准化连接对 Agent 生态的意义

二十二、三种常见 Skill 类型的写法差异

为了避免把所有 Skill 都写成一个样子，可以按任务类型来设计。不同类型的 Skill，SKILL.md 和脚本重点也不同。

1. 查询型 Skill

查询型 Skill 的目标是返回信息，比如天气、新闻、接口状态、知识库条目。它的重点是输入清楚、来源可信、返回简洁。

这类 Skill 的 SKILL.md 应该强调：

支持查询什么对象
需要用户提供什么参数
数据来源是什么
返回哪些字段
查询失败如何处理

weather-bit 就是查询型 Skill 的简化版。它支持北京和上海，用户问天气、温度、是否下雨时触发。真实项目可以把它扩展成更多城市、更多字段，甚至接入真实天气 API。

2. 生成型 Skill

生成型 Skill 的目标是产出文件或内容，比如二维码、报告、表格、PPT、图片、配置模板。它的重点是输出路径、格式和可交付性。

这类 Skill 的 SKILL.md 应该强调：

输出文件在哪里
文件格式是什么
是否会覆盖旧文件
是否需要安装依赖
生成失败如何提示

qrcode-gen 就是生成型 Skill。它的价值不只在"能生成二维码"，还在于把生成结果保存到明确目录，让用户和 Agent 都能继续引用。

3. 流程型 Skill

流程型 Skill 的目标是串联多个步骤，比如 tmtpost-news-daily。它通常包含配置、抓取、生成、通知、调度和测试。

这类 Skill 的 SKILL.md 不能只写一条命令，而应该说明：

整体流程是什么
每一步由哪个模块负责
配置文件在哪里
如何初始化依赖
如何手动运行
如何注册定时任务
哪些失败不会中断流程

流程型 Skill 是最接近业务系统的类型，开发难度也最高。它更需要需求文档、技术方案、测试和日志。

把 Skill 分成这三类后，开发时就不容易混乱。查询型追求准确，生成型追求产物，流程型追求闭环。

二十三、Skill 文档的语气：写给 Agent，也写给未来维护者

SKILL.md 有一个很特殊的双重读者：一方面，它要被 Agent 读取；另一方面，它也要被人类维护者阅读。因此它的语气既不能太随意，也不能像 API 手册一样只有参数。

写给 Agent 的部分，要明确、直接、可操作。比如：

markdown 复制代码

当用户要求生成二维码时，调用 `python scripts/make_qr.py "{文本}"`。

写给人类的部分，要解释限制、依赖和维护方式。比如：

markdown 复制代码

首次运行前需要安装 `qrcode[pil]`。生成的图片保存在 `output/` 目录。

如果文档只照顾人类，Agent 可能不知道怎么调用；如果文档只照顾 Agent，人类接手时又会不知道为什么这么设计。一个优秀 Skill 的文档，应该同时做到：

触发条件清楚
命令示例可复制
依赖说明完整
限制条件明确
输出结果可预期

这种写法会让 Skill 更像团队资产，而不是个人笔记。

二十四、从一个小 Skill 到一组 Skill：组合能力怎么设计

当你写了多个 Skill 后，会遇到一个新问题：它们之间是否能组合？

比如你有：

新闻抓取 Skill
Markdown 生成 Skill
飞书推送 Skill
二维码生成 Skill

这些 Skill 单独都能工作，但如果描述和输出设计得好，Agent 就能把它们串起来。用户可以说："抓取今天的 AI 新闻，生成 Markdown，再把文档链接做成二维码发到群里。"这时，每个 Skill 都承担一段能力。

要让组合顺畅，需要注意：

输出路径要明确
返回结果要简洁
不要把所有能力塞进一个巨型 Skill
相关 Skill 的命名风格保持一致
文档里说明结果能否被其他 Skill 使用

过度拆分会让调用链变复杂，过度合并又会让 Skill 难维护。经验上，如果一个能力能独立被用户请求，就适合做成独立 Skill；如果只是某个流程内部的小函数，就留在脚本模块里。

二十五、结语

Skill 开发真正要掌握的，不是某种语法，而是一种能力工程观：先定义边界，再写说明，再补脚本，再做触发测试，最后沉淀为团队资产。

如果把 Skill 开发提炼成一句操作性最强的话，那就是：

先让 Agent 知道"什么时候该请这位专家出场"，再让这位专家真的把事办成。

这就是 Skill 的本质，也是 OpenClaw 能从"会聊天"走向"会工作"的核心原因。

3. OpenClaw Skill 开发方法论：从 weather-bit 到 qrcode-gen

文章目录

OpenClaw Skill 开发方法论：从 weather-bit 到 qrcode-gen

一、Skill 到底是什么

二、一个 Skill 的最小结构长什么样

三、为什么 SKILL.md 是整个机制的灵魂

1. 元数据职责

2. 行为指令职责

四、渐进式披露机制，为什么是 Skill 设计的关键思想

五、说明型 Skill 与脚本型 Skill，不是对立关系

1. weather-bit：最典型的说明型 + 脚本调用

2. qrcode-gen：从说明走向可交付工具

六、写好一个 Skill，核心不是会编程，而是会定义任务边界

七、一个优秀 description 应该怎么写

1. 功能是什么

2. 触发场景是什么

3. 结果会返回什么

八、一个好 Skill 的正文通常要包含哪些部分

九、Skill 开发的推荐流程

1. 先写需求，不要先写代码

2. 先写 SKILL.md 的骨架

3. 再决定是否需要脚本

4. 脚本先单独跑通

5. 再接入 OpenClaw

6. 用真实对话测试触发效果

7. 持续迭代描述与目录结构

十、从两个小案例能学到哪些通用原则

原则一：小步起步

原则二：面向结果设计

原则三：把依赖写明白

原则四：说明优先于炫技

十一、Skill 生态为什么会成为 OpenClaw 的护城河

十二、从 Anthropic Agent Skills 看 Skill 设计的共性

1. 用自然语言描述触发场景

2. 用文件系统组织能力

3. 用按需加载控制上下文

十三、SKILL.md 的质量，决定 Skill 的上限

1. name 要短、稳定、可识别

2. description 要写"触发条件"，不是写宣传语

3. 正文要写执行路径

十四、让 Agent 更容易选中 Skill 的写法

何时使用这个技能

十五、脚本接口设计：Skill 稳不稳定，很多时候取决于命令行参数

十六、输出设计：让 Skill 的结果能被下一步使用

1. 文本输出要简洁

2. 文件输出要路径明确

3. 结构化输出适合复杂任务

4. 失败输出要可解释

十七、依赖管理：从教学脚本走向可复用 Skill 的关键一步

十八、Skill 的测试，不只是测试脚本

1. 脚本单测

2. 文档检查

3. 本地命令测试

4. Agent 触发测试

十九、Skill 版本迭代：别让小工具变成无主脚本

维护信息

二十、一个可复用的 Skill 开发检查清单

SKILL.md

脚本

运行

安全

二十一、参考资料

二十二、三种常见 Skill 类型的写法差异

1. 查询型 Skill

2. 生成型 Skill

3. 流程型 Skill

二十三、Skill 文档的语气：写给 Agent，也写给未来维护者

二十四、从一个小 Skill 到一组 Skill：组合能力怎么设计

二十五、结语

三、为什么 `SKILL.md` 是整个机制的灵魂

1. `weather-bit`：最典型的说明型 + 脚本调用

2. `qrcode-gen`：从说明走向可交付工具

七、一个优秀 `description` 应该怎么写

2. 先写 `SKILL.md` 的骨架

十三、`SKILL.md` 的质量，决定 Skill 的上限

1. `name` 要短、稳定、可识别

2. `description` 要写"触发条件"，不是写宣传语

`SKILL.md`