OpenClaw Skills 开发指南

从零开始编写技能模块，让 AI 助手具备专业能力

---

目录

1. 什么是技能？
2. 技能的基本结构
3. 从零开始写技能（基础篇）
4. 进阶篇：让 AI 帮你写技能
5. 最佳实践与设计模式
6. 常见问题与调试

---

什么是技能？

一句话理解

技能就是给 AI 助手的"专业培训手册"。

想象一下，你招聘了一个很聪明但没有行业经验的助理。如果你想让他帮你处理 GitHub 项目、查询天气、或者操作数据库，你需要给他一份工作指南，告诉他：

• 遇到什么情况该做什么
• 具体步骤是什么
• 有哪些注意事项

技能就是这份工作指南。

为什么需要技能？

OpenClaw 的 AI 助手本身已经具备很强的通用能力，但如果你希望它在特定领域表现得像"专家"，就需要给它提供专业技能。

举个例子：

没有技能时	有技能后
用户：“帮我查一下北京的天气”	用户：“帮我查一下北京的天气”
AI：“抱歉，我无法直接获取实时天气信息”	AI：执行 curl wttr.in/Beijing 并返回结果
用户需要自己去找天气网站	用户直接得到答案

技能能做什么？

专业知识 — 数据库结构、接口文档、公司规范等。例如告诉 AI 你公司的数据库表结构，它就能写出正确的查询语句。

工作流程 — 多步骤操作的执行顺序和决策逻辑。例如部署流程：测试 → 构建 → 发布 → 通知。

工具使用 — 如何调用命令行工具或接口。例如使用 gh 命令管理 GitHub 项目。

资源模板 — 代码模板、文档模板等。例如自动生成符合公司规范的接口文档。

技能的三层加载机制

为了节省 AI 的"记忆空间"（上下文窗口），技能采用分层加载的方式：

第一层 — 名称和简介
始终加载，约 100 词。用于判断是否需要这个技能。

第二层 — 技能正文
确定需要后加载。包含核心工作流程和指令。

第三层 — 扩展资源
按需加载。包含详细文档、脚本、模板等。

打个比方：

• 第一层就像图书馆的书名索引卡片，帮你快速找到需要的书
• 第二层就像书的目录和核心章节，告诉你主要内容
• 第三层就像书的附录和参考资料，需要时再翻阅

---

技能的基本结构

目录结构

一个技能本质上就是一个文件夹，里面放着各种文件：

my-skill/                    # 技能文件夹，名称用小写字母和连字符
├── SKILL.md                 # 【必需】核心文件，定义这个技能是做什么的
├── scripts/                 # 【可选】可执行脚本
│   └── helper.py
├── references/              # 【可选】详细参考文档
│   └── api-docs.md
└── assets/                  # 【可选】模板和资源文件
    └── template.json

最简单的技能只需要一个 SKILL.md 文件。其他目录都是可选的，按需添加。

SKILL.md 文件结构

SKILL.md 是技能的核心，它分为两大部分：

第一部分：元数据（放在文件开头）

用于告诉 OpenClaw 这个技能的基本信息和触发条件。

---
name: skill-name                                    # 技能名称（必需）
description: "清晰描述技能的功能和触发条件"            # 简介和触发条件（必需）
homepage: https://example.com/docs                  # 相关文档链接（可选）
metadata:                                           # 高级配置（可选）
  {
    "openclaw": {
      "emoji": "🔧",                                # 显示图标
      "requires": { "bins": ["python"] },           # 需要的软件
      "install": [...]                              # 自动安装方式
    }
  }
---

第二部分：正文内容

告诉 AI 具体该怎么做。

# 技能标题

## 概述
简要说明这个技能能做什么。

## 何时使用
 **适用场景：**
- 场景 1
- 场景 2

 **不适用场景：**
- 场景 A
- 场景 B

## 命令示例
```bash
# 示例命令
command --option value

注意事项

• 重要提示 1
• 重要提示 2

### 元数据字段说明

**必需字段：**

- **name** — 技能名称，只能用小写字母、数字、连字符，不超过 64 个字符
- **description** — **最重要的字段**！描述功能 + 触发条件，决定 AI 会不会调用这个技能

**可选字段：**

- **homepage** — 相关文档或项目主页链接
- **metadata** — 高级配置，包括图标、依赖、自动安装等

### metadata 高级配置详解

这个配置告诉 OpenClaw 技能需要什么环境：

```yaml
metadata:
  {
    "openclaw": {
      "emoji": "🎉",                    # 在界面上显示的图标
      "os": ["darwin", "linux"],        # 支持的操作系统（darwin=苹果，linux=Linux）
      "requires": {
        "bins": ["git"],                # 必须安装的软件
        "anyBins": ["node", "bun"]      # 二选一即可
      },
      "install": [
        {
          "id": "brew",
          "kind": "brew",               # 安装方式：brew/apt/npm
          "formula": "git",
          "bins": ["git"],
          "label": "安装 Git"
        }
      ]
    }
  }

---

从零开始写技能（基础篇）

步骤 1：想清楚技能的用途

在动手之前，先回答这几个问题：

这个技能解决什么问题？ — 决定技能的核心功能

用户会说什么话来触发它？ — 决定描述怎么写

需要哪些外部工具？ — 决定依赖配置

有哪些常见使用场景？ — 决定正文内容

实战示例：创建"天气查询"技能

我们来创建一个查询天气的技能，作为入门练习。

• 解决问题：快速获取天气信息
• 触发语句：“今天天气怎么样？”、“北京温度多少？”
• 依赖工具：curl（一个命令行工具，用于调用 wttr.in 天气接口）
• 使用场景：日常天气查询、旅行规划

步骤 2：创建技能目录

方式一：使用自动初始化脚本（推荐）

# 在 OpenClaw 项目目录下运行
python skills/skill-creator/scripts/init_skill.py weather \
  --path skills/ \
  --resources scripts,references

方式二：手动创建

# 创建技能文件夹
mkdir -p skills/weather

# 创建核心文件
touch skills/weather/SKILL.md

步骤 3：编写 SKILL.md

这是完整的示例，你可以参考这个模板：

---
name: weather
description: "查询实时天气和天气预报。适用于：用户问天气、温度、预报。不适用于：历史天气、气象分析。"
homepage: https://wttr.in/:help
metadata:
  {
    "openclaw":
      {
        "emoji": "☔",
        "requires": { "bins": ["curl"] },
      },
  }
---

# 天气查询

获取指定城市的实时天气和未来几天预报。

## 何时使用

 **适用：**
- "今天天气怎么样？"
- "会下雨吗？"
- "北京多少度？"

 **不适用：**
- 历史天气数据
- 气候分析
- 航空气象

## 常用命令

### 查询当前天气

```bash
# 简洁格式（推荐）
curl "wttr.in/北京?format=3"

# 详细格式
curl "wttr.in/北京?0"

查询预报

# 未来三天预报
curl "wttr.in/北京"

格式代码

代码	含义
%c	天气图标
%t	温度
%w	风速
%h	湿度

注意事项

• 无需申请接口密钥，直接使用
• 有请求频率限制，不要频繁调用

### 步骤 4：添加扩展资源（可选）

#### scripts 目录 —— 存放脚本

当操作比较复杂时，可以写脚本来处理：

```python
# scripts/get_weather.py
#!/usr/bin/env python3
"""获取城市天气"""
import sys
import urllib.request
import json

def get_weather(city):
    url = f"http://wttr.in/{city}?format=j1"
    with urllib.request.urlopen(url) as response:
        data = json.loads(response.read())
    return data['current_condition'][0]

if __name__ == "__main__":
    city = sys.argv[1] if len(sys.argv) > 1 else "北京"
    weather = get_weather(city)
    print(f"{city}: {weather['temp_C']}°C, {weather['weatherDesc'][0]['value']}")

references 目录 —— 存放详细文档

当 SKILL.md 放不下所有细节时，把详细内容放在这里：

# references/api-reference.md

## 接口说明

### 可用地址

| 地址 | 说明 |
|------|------|
| `/城市名` | 当前天气 |
| `/城市名?format=j1` | JSON 格式 |
| `/城市名?0` | 仅当前天气 |
| `/城市名?1` | 明天天气 |

### 参数说明

| 参数 | 可选值 | 说明 |
|------|--------|------|
| `format` | j1, v2, v2&lang=zh | 输出格式 |
| `lang` | zh, en, de | 语言 |

assets 目录 —— 存放模板和静态资源

assets/
├── weather-report-template.html    # 天气报告模板
└── icons/
    ├── sunny.png                   # 晴天图标
    └── rainy.png                   # 雨天图标

步骤 5：验证和打包

写完技能后，需要验证结构是否正确：

# 验证技能结构
python skills/skill-creator/scripts/quick_validate.py skills/weather

# 打包成 .skill 文件（用于分享或发布）
python skills/skill-creator/scripts/package_skill.py skills/weather

---

进阶篇：让 AI 帮你写技能

写技能本身就是一个适合交给 AI 的任务。下面介绍几种高效的方法。

方法 1：直接描述需求

通用模板：

请帮我创建一个 OpenClaw 技能，用于 [功能描述]。

技能需求：
- 触发场景：[用户会说什么]
- 核心功能：[要做什么]
- 依赖工具：[需要哪些软件或接口]
- 输出格式：[结果是什么样的]

请生成完整的 SKILL.md 文件。

实际例子：

请帮我创建一个 OpenClaw 技能，用于快速翻译文本。

需求：
- 触发场景：用户说"翻译这段话"、"帮我翻译"
- 核心功能：调用翻译接口完成翻译
- 依赖工具：curl 或 Python
- 支持语言：中英互译

请生成完整的 SKILL.md 文件。

方法 2：参考现有技能改写

请分析 skills/github/SKILL.md 的结构，然后参考这个格式，
为我创建一个 gitlab 技能，用于通过 GitLab 命令行工具管理项目。

功能包括：
- 查看合并请求状态
- 触发流水线
- 查看构建日志

方法 3：分步骤迭代开发

第一步：生成骨架

创建一个名为 "pdf-tools" 的技能骨架：
- 用于 PDF 操作（合并、拆分、提取文字）
- 使用 pdftk 或 PyPDF2
- 生成 SKILL.md 和 scripts 目录结构

第二步：完善细节

继续完善 pdf-tools 技能：
1. 在 SKILL.md 中添加合并 PDF 的具体命令
2. 创建 scripts/merge_pdfs.py 脚本
3. 添加常见错误处理说明

第三步：优化检查

审查 pdf-tools 技能，检查：
1. description 是否足够清晰
2. 命令示例是否正确
3. 是否有遗漏的使用场景

方法 4：从文档自动生成

这里是某工具的命令行帮助文档：

[粘贴 --help 输出内容或文档链接]

请根据以上文档，创建一个完整的 OpenClaw 技能。
包括：
1. 清晰的触发描述
2. 常用命令示例
3. 最佳实践建议

让 AI 帮你优化技能

生成测试用例：

为刚创建的 pdf-tools 技能生成测试场景：

1. 正常使用场景
2. 边界情况
3. 错误处理场景

输出格式：
- 用户输入示例
- 预期 AI 行为
- 预期技能触发情况

审查技能质量：

请审查以下 SKILL.md 的质量：

[粘贴内容]

检查清单：
□ description 是否完整描述触发条件
□ 命令示例是否正确可执行
□ 是否有不必要的冗余内容

---

最佳实践与设计模式

原则 1：简洁至上

AI 的"记忆空间"是有限的，每个技能都要精打细算。

** 错误示例（废话太多）：**

## 什么是天气

天气是指大气层在特定时间和地点的状态，包括温度、湿度、降水等因素。
天气对人类生活有重要影响，比如出行、穿衣、农业等...

## 如何查询天气

天气查询可以通过多种方式进行，包括手机 APP、网站、命令行工具等。
本技能使用 wttr.in 服务，这是一个免费的天气接口...

** 正确示例（直奔主题）：**

## 快速开始

```bash
curl "wttr.in/北京?format=3"

常用命令

命令	结果
wttr.in/城市?format=3	单行摘要
wttr.in/城市	三天预报

### 原则 2：description 是最重要的字段

这个字段决定了 AI 是否会调用你的技能。

**好的 description 应该包含：**

1. **功能描述**：这个技能做什么
2. **触发条件**：什么情况下应该用
3. **边界说明**：什么情况下不应该用

**示例：**

```yaml
description: "通过 gh 命令管理 GitHub 项目：问题、合并请求、构建。适用于：用户提到问题、合并请求、构建状态。不适用于：本地 git 操作、克隆仓库、非 GitHub 项目。"

原则 3：分层组织内容

核心内容放 SKILL.md，详细内容放 references。

在 SKILL.md 中引用外部文档：

## 高级配置

详细的接口文档请参考 `references/api-docs.md`。

公司特定的数据库结构请参考 `references/schemas.md`。

原则 4：选择正确的资源类型

scripts/ — 可执行代码、重复使用的逻辑。例如：rotate_pdf.py、sync_data.sh

references/ — 按需加载的详细文档。例如：接口文档、数据库结构、工作流指南

assets/ — 输出中使用的模板。例如：HTML 模板、Logo、字体文件

原则 5：用具体示例代替抽象描述

AI 从具体示例中学习更有效。

** 抽象描述：**

使用命令行工具搜索，支持多种过滤条件。

** 具体示例：**

### 搜索示例

```bash
# 按名称搜索
gh issue list --search "bug"

# 按标签搜索
gh issue list --label "priority:high"

# 按负责人搜索
gh issue list --assignee @me

### 常见的技能结构模式

#### 模式 1：流程驱动型

适合有明确步骤的任务：

```markdown
## 工作流程

1. **检查环境**：确认所需工具已安装
2. **身份验证**：执行登录命令
3. **执行任务**：运行具体命令
4. **验证结果**：检查输出是否正确

模式 2：功能分类型

适合提供多种功能的技能：

## 功能列表

### 读取文档
[相关命令]

### 创建文档
[相关命令]

### 编辑文档
[相关命令]

模式 3：速查表型

适合工具类技能：

## 速查表

| 功能 | 命令 |
|------|------|
| 列表 | `tool list` |
| 创建 | `tool create 名称` |
| 删除 | `tool delete ID` |

---

常见问题与调试

问题 1：技能没有被触发

可能原因：

• description 描述不够清晰
• 触发条件没有覆盖用户的表达方式

解决方案：

# 改进前
description: "管理 GitHub 问题"

# 改进后
description: "通过 gh 命令管理 GitHub 项目的问题、合并请求、构建。适用于：用户提到问题、合并请求、构建检查。触发语句：'查看合并请求状态'、'列出问题'、'查看构建日志'。"

问题 2：技能内容太多，AI 记不住

解决方案：

1. 精简 SKILL.md 到 500 行以内
2. 将详细文档移至 references 目录
3. 用表格代替冗长的文字描述

问题 3：命令执行失败

检查清单：

• 依赖的软件已经安装
• metadata.openclaw.requires 配置正确
• 命令在当前操作系统上可用
• 文件路径格式正确

问题 4：如何测试技能

# 1. 验证结构是否正确
python skills/skill-creator/scripts/quick_validate.py skills/my-skill

# 2. 打包测试
python skills/skill-creator/scripts/package_skill.py skills/my-skill

# 3. 实际使用测试
# 在 OpenClaw 中尝试触发该技能，观察 AI 是否正确调用

---

附录：技能复杂度示例

示例 1：最简单的技能

weather/
└── SKILL.md    # 只有一个文件

适合：功能单一、命令简单的场景

示例 2：中等复杂度

github/
└── SKILL.md    # 包含多种命令示例和使用场景

适合：功能较多、但不需要额外资源的场景

示例 3：完整结构

himalaya/
├── SKILL.md
└── references/
    ├── configuration.md
    └── message-composition.md

适合：需要详细参考文档的场景

示例 4：带脚本的技能

video-frames/
├── SKILL.md
└── scripts/
    └── frame.sh

适合：需要执行复杂脚本的场景

---

总结

编写好的技能，记住这五点：

1. 描述是灵魂 — description 决定技能何时被调用，要写清楚
2. 简洁是美德 — AI 的记忆空间宝贵，每个字都要有价值
3. 示例胜于解释 — 具体的命令示例比抽象描述更有效
4. 分层组织 — 核心在 SKILL.md，细节在 references
5. 持续改进 — 根据实际使用反馈不断优化

---