OpenClaw Skill 开发完整指南：从零构建AI技能扩展的实战教程

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功能

  1. 启动OpenClaw控制面板（或任何已连接的聊天渠道界面）
  2. 发送测试消息：“北京今天天气怎么样？”
  3. 如果Skill被正确激活，你将立即接收到天气数据反馈

祝贺！你已经成功创建了首个Skill！ 🎉

2. 背景知识：OpenClaw核心概念解析

📘 如果你已经了解OpenClaw基本原理，可以跳过本章节

2.1 OpenClaw平台简介

OpenClaw本质上是一个可自主托管的人工智能网关，它在你的聊天应用程序（例如微信、Telegram、Discord等）和AI智能体之间建立连接桥梁。

简化理解流程：

用户发送消息 → OpenClaw接收消息 → AI进行处理分析 → 返回相应回复

2.2 Skill核心定义

Skill是OpenClaw系统中的功能扩展模块包。

类比说明：

类比对象 解释说明
智能手机应用 手机基础功能是通话，但需要各类App实现外卖订购、车辆预约等
浏览器扩展插件 浏览器核心是网页浏览，但需要插件完成广告过滤、语言翻译等
Skill技能包 AI本身具备智能，但需要Skill才能接入企业内部系统、操作特定工具

Skill的核心价值：

  • 教授AI理解企业专属业务逻辑（如财务系统、数据库架构）
  • 提供可重复使用的工具集合（如PDF文档处理、API接口调用）
  • 定义标准化工作流程（如审批流程、内容发布流程）

2.3 关键术语定义

术语 详细解释
Skill 功能能力包，包含指令集和相关资源
SKILL.md Skill的核心定义文件，指导AI如何正确使用该Skill
scripts/ 存储可执行程序代码的目录（Python、Shell脚本等）
references/ 存储参考文档资料的目录（API文档、流程指南等）
assets/ 存储输出资源的目录（模板文件、图片素材等）
description Skill的触发条件描述，决定AI何时调用这个Skill
上下文窗口 AI单次能够处理的文本数量上限，Skill设计需考虑节省此空间

3. Skill的标准架构设计

3.1 标准目录架构

一个符合规范的完整Skill目录结构如下所示：

skill-name/├── SKILL.md              # 必需文件：技能核心定义文件│   ├── YAML frontmatter  # 名称+描述（触发关键元数据）│   └── 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 核心指令和定义 Skill触发后立即加载
scripts/ 存储可执行程序代码 可直接执行，无需加载到上下文
references/ 存储参考文档资料 根据需求按需加载
assets/ 存储输出资源文件 不加载到上下文，直接调用使用

核心理解要点：

  • SKILL.md是Skill的中央核心，包含了触发元数据和操作指南
  • scripts/目录中的代码文件可以直接运行，适合自动化重复操作
  • references/目录存放详尽文档，仅在AI需要时读取
  • assets/目录存储输出资源，例如模板文档、品牌视觉素材等

4. 标准开发流程六步法

4.1 第一步：需求分析理解

核心目标：明确Skill的具体使用场景和准确触发条件

在开始编写代码之前，必须清晰回答以下关键问题：

  • 用户会通过哪些语句触发这个Skill？
  • 这个Skill需要完成哪些具体任务？
  • 存在哪些典型的使用场景示例？

场景示例：开发pdf-editor Skill时，用户可能提出的请求包括：

  • “请帮我旋转这份PDF文档”
  • “提取第3到第5页的内容”
  • “将这两个PDF文件合并为一个”

这些具体用户请求将帮助你明确Skill需要支持的功能范围。

4.2 第二步：资源规划分析

针对每个使用场景，识别所需的资源类型：

使用场景 所需资源 资源类型
旋转PDF文档 旋转功能脚本 scripts/
合并PDF文档 合并功能脚本 scripts/
表单自动填写 API接口参考文档 references/
品牌报告生成 PPT演示模板 assets/

资源规划基本原则：

  • 重复性操作任务 → 放入scripts/目录
  • 详细参考文档 → 放入references/目录
  • 输出模板文件 → 放入assets/目录

4.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 第四步：编写SKILL.md文件

4.4.1 YAML Frontmatter（至关重要！）

---name: pdf-editordescription: PDF文档处理专用技能，支持页面旋转、文档合并、文件拆分、表单填写和文本内容提取。              当用户需要：(1) 调整PDF页面方向，(2) 合并多个PDF文件，               (3) 提取指定页面，(4) 填写PDF表单，或 (5) 提取PDF文本内容时自动启用。---

重要提示：description字段是主要的触发机制，必须包含以下信息：

  • Skill的核心功能说明
  • 具体触发场景描述（何时应该使用）
  • 切勿在正文部分重复编写“何时使用”章节——因为此时Skill已经触发了

4.4.2 正文结构设计模式

根据Skill的不同类型，可以选择以下三种结构模式：

模式一：工作流程导向（适用于顺序化流程）

这种模式适合具有明确步骤顺序的场景，用户需要按照特定流程完成任务。结构特点是从决策树开始，引导用户找到正确的操作路径。

## 工作流程决策树  
1. 用户需要修改现有PDF文档？ → 跳转到 [编辑PDF](#编辑-pdf)2. 用户需要创建新的PDF文档？ → 跳转到 [创建PDF](#创建-pdf)3. 用户需要提取文档内容？ → 跳转到 [内容提取](#内容提取)  
## 编辑PDF文档  
### 旋转页面功能使用 scripts/rotate_pdf.py 脚本：```bashpython scripts/rotate_pdf.py input.pdf 90

模式二：任务功能导向（适用于工具集合）

这种模式适合提供多种独立功能的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文本提取  
从PDF文档中提取纯文本内容。  
**适用场景：** 文档内容分析、文本索引建立、批量文本处理  
**使用命令：**  
```bashpython scripts/extract_text.py input.pdf```

模式三：专业领域导向（适用于多框架/多平台）

这种模式适合需要支持多个平台、框架或专业领域的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)  包含虚拟机、Functions函数、Storage存储等Azure服务的部署指南

4.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 90    python rotate_pdf.py document.pdf 180 rotated.pdf"""  
import sysfrom pypdf import PdfReader, PdfWriter  
def 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_path  
if __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        # 品牌规范指南

大文件处理技巧：对于超过1万词的参考文档，建议在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/         # 完整React项目模板        ├── package.json        └── src/

4.6 第六步：打包与验证测试

完成Skill开发后，使用打包工具进行最终验证和打包：

```bash# 验证并打包Skillpython ~/.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 正文内容写作技巧

推荐实践：

  • 使用祈使语句：“请运行以下命令…”
  • 提供具体操作示例：“当用户说‘旋转这个PDF’时…”
  • 包含决策逻辑树：“如果是X情况，执行Y操作；如果是Z情况，执行W操作”
  • 引用资源文件：“详细信息请查阅references/api.md文档”

避免做法：

  • 冗长复杂解释（AI本身已经足够智能）
  • 信息重复表述（SKILL.md和references文档不应重复相同内容）
  • 编写“何时使用”章节（此信息应包含在description字段中）

5.4 渐进式披露设计模式

对于功能复杂的Skill，可以采用“核心功能+扩展功能”的模式，将基础操作放在主文档中，高级功能通过引用方式链接到独立文档。

示例结构设计：

# DOCX文档处理  
## 基础操作指南  
创建新文档：```pythonfrom docx import Documentdoc = Document()doc.add_paragraph("Hello World")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 案例一：简易工具型Skill（天气查询）

应用场景：天气信息查询，无需复杂资源支持

这个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 案例二：复杂工作流Skill（PDF编辑器）

应用场景：多操作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文档中提取纯文本内容。适用于文档内容分析、文本索引建立、批量文本处理等场景。  
## 高级功能指引  
PDF表单字段的填写和读取操作较为复杂，详见 [references/form_fields.md](references/form_fields.md)

6.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`：月度预算数据表  
### 销售数据领域  
包含客户信息、订单记录、销售管道等销售相关数据表。详见 [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：

# 查看所有Skills列表openclaw skills list --verbose  
# 检查特定Skill详细信息openclaw 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. 验证并打包Skillpython .../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-agent技能codex review --base origin/main

8.3 状态保持技术

对于多步骤工作流程，可以使用TaskFlow机制保持执行状态：

## 多步骤工作流程  
使用TaskFlow保持执行状态：  
1. 创建流程实例：`taskFlow.createManaged(...)`2. 运行子任务：`taskFlow.runTask(...)`3. 等待外部输入：`taskFlow.setWaiting(...)`4. 恢复流程执行：`taskFlow.resume(...)`5. 完成流程：`taskFlow.finish(...)`  
详细指南见 [taskflow/SKILL.md](../taskflow/SKILL.md)

TaskFlow适用于需要跨多个步骤保持状态的工作流，例如收件箱分类处理、PR代码审核等场景。

参考资源推荐

  • 官方Skill开发示例库
  • ClawHub Skill应用市场
  • Skill Creator核心技能
  • OpenClaw官方文档中心