夜雨聆风
OpenClaw Skill 开发完全指南
1. 快速入门：5 分钟创建你的第一个 Skill
💡 先动手，再理解 —— 跟着做一遍，后面的概念会更容易理解
1.1 准备工作
确保你已经安装 OpenClaw。如果没有，先运行：
npm install -g openclaw@latestopenclaw onboard --install-daemon
1.2 创建 Skill 骨架
我们创建一个简单的”天气查询”Skill。运行以下命令：
# 找到 init_skill.py 脚本的位置python $(npm root -g)/openclaw/skills/skill-creator/scripts/init_skill.py \weather \--path ~/.openclaw/workspace-main/skills
这会创建以下结构：
weather/└── SKILL.md # 包含模板内容
1.3 编辑 SKILL.md
用文本编辑器打开 SKILL.md，将内容替换为：
---name: weatherdescription: 通过 wttr.in 获取天气和预报。当用户询问天气、温度、降水或出行天气时使用。---# 天气查询## 快速响应获取当前天气：```bashcurl "wttr.in/Beijing?format=3"获取详细预报：curl "wttr.in/Beijing"## 常用格式- `%c` — 天气表情符号（☀️🌧️❄️）- `%t` — 温度- `%w` — 风力- `%h` — 湿度
1.4 测试你的 Skill
-
打开 OpenClaw 控制面板（或任意连接的聊天渠道）
-
发送消息：”北京今天天气怎么样？”
-
如果 Skill 正确触发，你会看到天气信息
恭喜！你已经创建了第一个 Skill！ 🎉
2. 前置知识：OpenClaw 是什么？
📘 如果你已经熟悉 OpenClaw，可以跳过本章
2.1 OpenClaw 简介
OpenClaw 是一个自托管的 AI 网关，它连接你的聊天应用（微信、Telegram、Discord 等）和 AI Agent。
简单理解：
你发消息 → OpenClaw 接收 → AI 处理 → 返回回复
2.2 什么是 Skill？
Skill 是 OpenClaw 中的能力扩展包。
类比理解：
| 类比 | 说明 |
|---|---|
| 手机 App | 手机本身能打电话，但需要 App 才能点外卖、打车 |
| 浏览器插件 | 浏览器本身能上网，但需要插件才能广告拦截、翻译 |
| Skill | AI 本身很聪明，但需要 Skill 才能访问你的公司系统、操作特定工具 |
Skill 的作用：
-
教会 AI 你的公司业务（财务系统、数据库结构）
-
提供可复用的工具（PDF 处理、API 调用）
-
定义工作流程（如何审批、如何发布）
2.3 关键术语解释
| 术语 | 解释 |
|---|---|
| Skill | 能力包，包含指令和资源 |
| SKILL.md | Skill 的主文件，告诉 AI 如何使用这个 Skill |
| scripts/ | 存放可执行代码（Python、Shell 等） |
| references/ | 存放参考文档（API 文档、流程指南） |
| assets/ | 存放输出资源（模板、图片） |
| description | Skill 的触发条件，决定什么时候使用这个 Skill |
| 上下文窗口 | AI 一次能处理的文字量，Skill 需要节省这个空间 |
3.1 目录结构
一个完整的 Skill 目录结构如下：
skill-name/├── SKILL.md # 必需：技能定义文件│ ├── YAML frontmatter # name + description（触发关键）│ └── Markdown body # 使用指南├── scripts/ # 可选：可执行代码│ ├── process_data.py│ └── convert_format.sh├── references/ # 可选：参考文档│ ├── api_reference.md│ └── workflow_guide.md└── assets/ # 可选：输出资源├── template.pptx└── logo.png
3.2 各目录职责说明
| 目录 | 用途 | 是否加载到上下文 |
|---|---|---|
SKILL.md |
核心指令 | 触发后加载 |
scripts/ |
可执行代码 | 可执行，无需加载 |
references/ |
参考文档 | 按需加载 |
assets/ |
输出资源 | 不加载，直接使用 |
理解要点：
-
SKILL.md是 Skill 的核心，包含触发元数据和使用指南 -
scripts/中的代码可以直接执行，适合重复性操作 -
references/存放详细文档，仅在需要时读取 -
assets/是输出资源，如模板文件、品牌素材等
4. 开发流程六步法
4.1 Step 1: 理解需求
目标：明确 Skill 的使用场景和触发条件
在开始编写之前，需要先回答以下关键问题：
-
用户会说什么来触发这个 Skill？
-
这个 Skill 要完成什么具体任务？
-
有哪些典型的使用示例？
示例： 开发 pdf-editor Skill 时，用户可能的请求包括：
-
“帮我旋转这个 PDF”
-
“提取第 3-5 页的内容”
-
“把这两个 PDF 合并”
这些具体请求将帮助你确定 Skill 需要支持的功能范围。
4.2 Step 2: 规划资源
分析每个使用场景，识别需要的资源类型：
| 场景 | 需要的资源 | 类型 |
|---|---|---|
| 旋转 PDF | 旋转脚本 | scripts/ |
| 合并 PDF | 合并脚本 | scripts/ |
| 表单填写 | API 参考文档 | references/ |
| 品牌报告 | PPT 模板 | assets/ |
规划原则：
-
重复性操作 → 放入
scripts/ -
详细参考 → 放入
references/ -
输出模板 → 放入
assets/
4.3 Step 3: 初始化 Skill
使用官方提供的初始化工具创建 Skill 骨架：
# 基础初始化python ~/.npm-global/lib/node_modules/openclaw/skills/skill-creator/scripts/init_skill.py \pdf-editor \--path ~/.openclaw/workspace-main/skills# 带资源目录和示例python .../init_skill.py \pdf-editor \--path ~/.openclaw/workspace-main/skills \--resources scripts,references \--examples
生成的结构：
pdf-editor/├── SKILL.md # 含 TODO 占位符├── scripts/│ └── example.py # 示例脚本（如使用--examples 参数）└── references/└── api_reference.md # 示例文档
初始化工具会自动创建标准目录结构和 SKILL.md 模板，你只需填充具体内容。
4.4 Step 4: 编写 SKILL.md
4.4.1 YAML Frontmatter（关键！）
---name: pdf-editordescription: PDF 文档处理技能，包括旋转、合并、拆分、表单填写和文本提取。当用户需要：(1) 修改 PDF 页面方向，(2) 合并多个 PDF，(3) 提取特定页面，(4) 填写 PDF 表单，或 (5) 提取 PDF 文本时使用。---
重要提示：description 是主要触发机制，必须包含：
-
Skill 做什么
-
具体触发场景（何时使用）
-
不要在 body 中写”When to Use”——太晚了，已经触发了
4.4.2 Body 结构模式
根据 Skill 的类型，可以选择以下三种结构模式：
模式 1：工作流导向（适合顺序流程）
这种模式适用于有明确步骤顺序的场景，用户需要按照特定流程完成任务。结构特点是从决策树开始，引导用户找到正确的操作路径。
## 工作流决策树1. 用户要修改现有 PDF？ → 跳到 [编辑 PDF](#编辑-pdf)2. 用户要创建新 PDF？ → 跳到 [创建 PDF](#创建-pdf)3. 用户要提取内容？ → 跳到 [提取内容](#提取内容)## 编辑 PDF### 旋转页面使用 scripts/rotate_pdf.py：```bashpython scripts/rotate_pdf.py input.pdf 90
模式 2：任务导向（适合工具集合）
这种模式适用于提供多种独立功能的 Skill，每个功能可以单独使用，没有严格的先后顺序。结构特点是从快速开始示例入手，然后逐一介绍各项能力。
## 快速开始```bashpython scripts/rotate_pdf.py document.pdf 90## 核心能力### 1. 旋转 PDF将 PDF 页面顺时针旋转 90、180 或 270 度。**适用场景：** 扫描文档方向错误、需要调整阅读角度**使用方法：**```bashpython scripts/rotate_pdf.py <input.pdf> <degrees> [output.pdf]```### 2. 合并 PDF将多个 PDF 文件按顺序合并为单个文件。**适用场景：** 将分章节的文档整合、合并多个报表**使用方法：**```bashpython scripts/merge_pdfs.py file1.pdf file2.pdf output.pdf```### 3. 提取文本从 PDF 中提取纯文本内容。**适用场景：** 文档分析、内容索引、批量处理**使用方法：**```bashpython scripts/extract_text.py input.pdf```
模式 3：领域导向（适合多框架/多平台）
这种模式适用于需要支持多个平台、框架或领域的 Skill。结构特点是根据用户选择的领域，引导到对应的详细文档。
## 选择你的平台- **AWS 部署** → 阅读 [references/aws.md](references/aws.md)包含 EC2、Lambda、S3 等 AWS 服务的部署指南- **GCP 部署** → 阅读 [references/gcp.md](references/gcp.md)包含 Compute Engine、Cloud Functions 等 GCP 服务的部署指南- **Azure 部署** → 阅读 [references/azure.md](references/azure.md)包含 VM、Functions、Storage 等 Azure 服务的部署指南
4.5 Step 5: 实现资源
4.5.1 Scripts 目录
何时使用：
-
相同代码反复重写
-
需要确定性可靠性
-
复杂自动化任务
示例：PDF 旋转脚本
#!/usr/bin/env python3"""旋转 PDF 页面用法：python rotate_pdf.py <input.pdf> <degrees> [output.pdf]示例：python rotate_pdf.py document.pdf 90python rotate_pdf.py document.pdf 180 rotated.pdf"""import sysfrom pypdf import PdfReader, PdfWriterdef rotate_pdf(input_path, degrees, output_path=None):if output_path is None:output_path = input_path.replace('.pdf', '_rotated.pdf')reader = PdfReader(input_path)writer = PdfWriter()for page in reader.pages:page.rotate(int(degrees))writer.add_page(page)with open(output_path, 'wb') as f:writer.write(f)return output_pathif __name__ == "__main__":if len(sys.argv) < 3:print("用法：python rotate_pdf.py <input.pdf> <degrees> [output.pdf]")sys.exit(1)result = rotate_pdf(sys.argv[1], sys.argv[2])print(f"已旋转并保存到：{result}")
组织技巧：
scripts/├── rotate_pdf.py # 独立工具├── merge_pdfs.py # 独立工具├── __init__.py # 可选：Python 包└── utils/├── validation.py # 共享工具└── constants.py # 配置常量
4.5.2 References 目录
何时使用：
-
API 文档
-
数据库 schema
-
复杂工作流指南
-
公司政策/规范
示例：长文档添加目录
# BigQuery API 参考## 目录- [认证](#认证)- [查询执行](#查询执行)- [表操作](#表操作)- [错误处理](#错误处理)## 认证...
组织技巧：
references/├── api_reference.md # API 完整文档├── workflow_guide.md # 分步指南├── schema.md # 数据结构└── policies/├── security.md # 安全政策└── branding.md # 品牌规范
大文件处理技巧：对于超过 10k 词的参考文档，在 SKILL.md 中添加 grep 搜索提示：
搜索 schema 定义：```bashgrep -r "CREATE TABLE" references/
4.5.3 Assets 目录
何时使用：
-
模板文件（PPT、DOCX）
-
品牌资源（logo、字体）
-
代码样板（项目模板）
示例结构：
assets/├── brand/│ ├── logo.png│ └── colors.json├── templates/│ ├── report.pptx│ └── invoice.docx└── boilerplate/└── react-app/ # 完整项目模板├── package.json└── src/
4.6 Step 6: 打包与验证
完成 Skill 开发后，使用打包工具进行验证和打包：
```bash# 验证并打包python ~/.npm-global/lib/node_modules/openclaw/skills/skill-creator/scripts/package_skill.py \~/.openclaw/workspace-main/skills/pdf-editor# 输出：pdf-editor.skill（zip 格式）
自动验证检查项：
-
YAML frontmatter 格式
-
name/description 完整性
-
目录结构合规性
-
资源引用正确性
-
无符号链接（安全限制）
5. SKILL.md 编写规范
5.1 命名规范
正确的命名示例：
-
my-skill -
pdf-editor-advanced -
gh-issue-tracker
错误的命名示例：
-
MySkill（包含大写字母） -
pdf_editor（使用下划线） -
issue tracker（包含空格）
命名规则：
-
只使用小写字母、数字、连字符
-
最大长度 64 字符
-
优先使用动词开头（如
rotate-pdf优于pdf-rotation）
5.2 Description 编写模板
Description 是 Skill 触发的关键，建议遵循以下模板：
[技能名称]，用于 [核心功能]。当用户需要：(1) [场景 1]，(2) [场景 2]，(3) [场景 3] 时使用。
完整示例：
description: 天气查询技能，通过 wttr.in 获取实时天气和预报。当用户询问：(1) 当前天气，(2) 温度查询，(3) 未来预报，(4) 出行天气规划时使用。
5.3 Body 写作技巧
推荐做法：
-
使用祈使句：”运行以下命令…”
-
提供具体示例：”用户说’旋转这个 PDF’时…”
-
包含决策树：”如果是 X，做 Y；如果是 Z，做 W”
-
引用资源文件：”详见 references/api.md“
避免做法：
-
冗长解释（Codex 已经很聪明）
-
重复信息（SKILL.md 和 references 不要重复）
-
“When to Use” 章节（应该在 description 中）
5.4 渐进式披露模式
对于复杂 Skill，可以采用”核心 + 扩展”的模式，将基础操作放在主文档中，高级功能通过引用方式链接到独立文档。
示例结构：
# DOCX 处理## 基础操作创建文档：```pythonfrom docx import Documentdoc = Document()doc.add_paragraph("Hello")doc.save("output.docx")## 高级功能- **修订跟踪**：详见 [references/redlining.md](references/redlining.md)- **OOXML 细节**：详见 [references/ooxml.md](references/ooxml.md)- **模板渲染**：详见 [references/templates.md](references/templates.md)
设计要点：
-
基础操作：直接展示代码示例，用户可立即使用
-
高级功能：仅列出功能名称和链接，保持主文档简洁
-
引用文档：在 references/ 中提供完整指南
6. 实战案例
6.1 案例 1：简单工具 Skill（Weather）
场景： 天气查询，无复杂资源
这个 Skill 功能简单，只需要 SKILL.md 文件即可，无需额外的资源目录。
目录结构：
weather/└── SKILL.md
SKILL.md 核心内容：
```yaml---name: weatherdescription: 通过 wttr.in 获取天气和预报。当用户询问天气、温度、降水或出行天气时使用。---# 天气查询## 快速响应```bash# 当前天气curl "wttr.in/London?format=3"# 详细预报curl "wttr.in/London?0"# 一周预报curl "wttr.in/London?format=v2"## 格式代码- `%c` — 天气表情符号- `%t` — 温度- `%w` — 风力- `%h` — 湿度
6.2 案例 2：复杂工作流 Skill（PDF Editor）
场景： 多操作 PDF 处理
这个 Skill 提供多种 PDF 编辑功能，每个功能都是独立的操作，用户可能只需要其中一项。因此采用任务导向结构，先给出快速示例，再逐一介绍各项能力。
目录结构：
pdf-editor/├── SKILL.md├── scripts/│ ├── rotate_pdf.py # 旋转 PDF 页面│ ├── merge_pdfs.py # 合并多个 PDF│ ├── split_pdf.py # 拆分 PDF 为多文件│ └── extract_text.py # 提取文本内容└── references/├── form_fields.md # PDF 表单字段处理指南└── api_reference.md # 完整 API 参考
SKILL.md 核心内容：
# PDF 编辑器## 快速开始旋转 PDF 页面：```bashpython scripts/rotate_pdf.py document.pdf 90## 核心能力### 1. 旋转 PDF将 PDF 页面顺时针旋转 90、180 或 270 度。适用于扫描文档方向错误、需要调整阅读角度等场景。**参数说明：**- `input.pdf`：输入的 PDF 文件路径- `degrees`：旋转角度（90/180/270）- `output.pdf`：输出文件路径（可选，默认添加_rotated 后缀）### 2. 合并 PDF将多个 PDF 文件按顺序合并为单个文件。适用于将分章节的文档整合、合并多个报表等场景。**参数说明：**- `file1.pdf file2.pdf ...`：一个或多个输入文件- `output.pdf`：合并后的输出文件### 3. 拆分 PDF将单个 PDF 按页码范围拆分为多个文件。适用于提取特定章节、分离附录等场景。### 4. 提取文本从 PDF 中提取纯文本内容。适用于文档分析、内容索引、批量处理等场景。## 高级功能PDF 表单字段的填写和读取操作较为复杂，详见 [references/form_fields.md](references/form_fields.md)
6.3 案例 3：领域知识 Skill（BigQuery）
场景： 公司数据查询
这个 Skill 面向公司内部的数据查询需求，不同部门关注的数据领域不同。采用领域导向结构，根据用户的数据领域引导到对应的 schema 文档。
目录结构：
bigquery-helper/├── SKILL.md└── references/├── finance_schema.md # 财务数据表结构├── sales_schema.md # 销售数据表结构├── product_schema.md # 产品数据表结构└── common_queries.md # 常用查询模板
SKILL.md 核心内容：
```markdown# BigQuery 助手## 快速开始查询前请确认你需要的数据领域，然后阅读对应的 schema 文档了解表结构。## 按领域查询### 财务数据包含收入、支出、预算等财务相关表。详见 [references/finance_schema.md](references/finance_schema.md)主要表：- `revenue_daily`：每日收入明细- `expense_category`：支出分类汇总- `budget_monthly`：月度预算### 销售数据包含客户、订单、pipeline 等销售相关表。详见 [references/sales_schema.md](references/sales_schema.md)主要表：- `customers`：客户信息- `orders`：订单记录- `opportunities`：销售机会### 产品数据包含功能使用、API 调用、用户行为等产品相关表。详见 [references/product_schema.md](references/product_schema.md)## 常用查询常用查询模板和最佳实践见 [references/common_queries.md](references/common_queries.md)
7. 调试与发布
7.1 调试技巧
1. 触发测试
在对话中测试 Skill 是否正确触发：
# 测试触发"帮我旋转这个 PDF" # 应该触发 pdf-editor
如果没有触发，检查：
-
description 是否包含触发场景
-
name 是否清晰明确
2. 上下文检查
查看已加载的 Skills：
# 查看所有 Skillsopenclaw skills list --verbose# 检查特定 Skillopenclaw skills info pdf-editor --json
3. 执行测试
测试脚本是否可以正常运行：
# 测试脚本cd skills/pdf-editor/scriptspython rotate_pdf.py test.pdf 90 test_rotated.pdf# 验证输出ls -la test_rotated.pdf
7.2 常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| Skill 不触发 | description 不清晰 | 添加具体触发场景 |
| 脚本执行失败 | 路径错误 | 使用绝对路径或相对 skill 根目录 |
| 上下文过大 | SKILL.md 太长 | 移动到 references/ |
| 资源未加载 | 引用路径错误 | 检查相对路径 |
7.3 发布到 ClawHub
完成开发和测试后，可以将 Skill 发布到 ClawHub 供其他用户安装：
# 1. 验证并打包python .../package_skill.py skills/pdf-editor# 2. 提交到 ClawHub# 访问 https://clawhub.ai 上传 .skill 文件# 3. 用户安装openclaw skills install pdf-editor
8. 进阶技巧
8.1 条件性资源加载
在 SKILL.md 中明确何时加载 references 文档：
## 高级功能**仅当用户需要复杂功能时加载：**- 需要修订跟踪？ → 读取 [REDLINING.md](REDLINING.md)- 需要 OOXML 操作？ → 读取 [OOXML.md](OOXML.md)
这样可以避免不必要的上下文加载。
8.2 多 Agent 协作
Skill 可以调用其他 Agent 完成复杂任务：
## 代码审查1. 使用 `coding-agent` Skill 运行静态分析2. 读取分析结果3. 生成审查报告```bash# 触发 coding-agentcodex review --base origin/main
8.3 状态保持
对于多步骤工作流，可以使用 TaskFlow 保持状态：
## 多步骤流程使用 TaskFlow 保持状态：1. 创建 flow：`taskFlow.createManaged(...)`2. 运行子任务：`taskFlow.runTask(...)`3. 等待外部输入：`taskFlow.setWaiting(...)`4. 恢复执行：`taskFlow.resume(...)`5. 完成：`taskFlow.finish(...)`详见 [taskflow/SKILL.md](../taskflow/SKILL.md)
TaskFlow 适用于需要跨多个步骤保持状态的工作流，如 inbox 分类、PR 审核等场景。
参考资源
-
官方 Skill 示例
-
ClawHub Skill 市场
-
Skill Creator Skill
-
OpenClaw 文档