OpenClaw Skills 技能系统入门与开发指南

内容型技能：提供输出模板和参考文档。例如 tech-article 技能定义了技术博客文章的写作规范。

集成型技能：连接外部服务。例如 xfyun-tts 技能集成了讯飞语音合成 API。

3. 技能的目录结构

3.1 标准目录结构

一个完整的技能目录通常包含以下结构：

skill-name/
├── SKILL.md          # 必需：技能定义文件
├── scripts/          # 可选：可执行脚本
│   ├── main.py
│   └── utils.py
├── references/       # 可选：参考文档
│   ├── api_docs.md
│   └── examples.md
└── assets/           # 可选：资产文件
    ├── template.docx
    └── logo.png

3.2 各目录的作用

SKILL.md（必需）

这是技能的核心定义文件，包含 YAML 前置元数据和 Markdown 格式的指令内容。OpenClaw 通过这个文件识别和加载技能。

scripts/（可选）

存放可执行的脚本文件，通常是 Python 或 Shell 脚本。这些脚本可以：

• 执行确定性的操作（如文件转换、数据处理）
• 封装复杂的 API 调用
• 提供可复用的工具函数

脚本的优势在于可以在不加载到上下文的情况下直接执行，节省 token 消耗。

references/（可选）

存放参考文档，当技能需要详细的背景知识时会用到。例如：

• API 文档和规范
• 数据库 Schema 定义
• 业务流程说明
• 详细的使用示例

参考文档采用按需加载策略，只有当 AI 需要时才会读取。

assets/（可选）

存放资产文件，这些文件不会加载到上下文，而是直接用于输出。例如：

• 文档模板（.docx, .pptx）
• 图片和图标
• 字体文件
• 代码脚手架

3.3 实际案例：xfyun-tts 技能目录

让我们看一个真实的技能目录结构：

xfyun-tts/
├── SKILL.md          # 技能定义（约 4.7KB）
└── scripts/
    └── tts.py        # 语音合成脚本（约 22KB）

这个技能的结构非常简洁：

• SKILL.md 定义了讯飞 TTS API 的使用方法、参数说明和常用语音列表
• scripts/tts.py 是一个完整的 WebSocket 客户端，实现了与讯飞 API 的通信

这种文档 + 脚本的组合是最常见的技能模式，既提供了清晰的使用指南，又封装了复杂的实现细节。

4. SKILL.md 配置文件详解

4.1 文件结构

SKILL.md 由两部分组成：YAML 前置元数据（Frontmatter）和 Markdown 正文。

---
name: skill-name
description: "技能描述，用于触发匹配"
homepage: https://example.com # 可选
metadata:
  openclaw:
    emoji: "🔧"
    requires:
      bins: ["python3", "curl"]
---
# 技能标题 这里是 Markdown 格式的正文内容...

4.2 元数据字段详解

name（必需）

技能的唯一标识符，使用小写字母、数字和连字符。命名建议：

• 使用动词开头的短语，如 download-file、analyze-code
• 保持简洁，不超过 64 个字符
• 避免使用特殊字符和下划线

description（必需）

技能的描述信息，这是触发匹配的关键字段。OpenClaw 会根据这个描述判断何时激活技能。

编写高质量描述的要点：

1. 明确功能范围：说明技能能做什么，不能做什么
2. 列出触发场景：描述用户可能的表达方式
3. 包含关键词：使用与功能相关的术语

# 好的描述示例
description: "iFlytek Ultra-Realistic TTS (超拟人语音合成) — synthesize natural, expressive speech from text using iFlytek's ultra-realistic voice synthesis API. Supports 50+ voices (male/female/child, Chinese/English/dialect), adjustable speed/volume/pitch, mp3/pcm/opus output. Use when the user wants to convert text to speech, generate audio narration, or create voice content."
# 不好的描述示例
description: "TTS skill for voice synthesis" # 太简略，缺少触发场景

homepage（可选）

技能的主页链接，通常指向官方文档或项目仓库。

metadata（可选）

扩展元数据，可以包含：

• emoji：技能的图标
• requires：依赖项声明（如需要安装的命令行工具）

4.3 正文内容组织

SKILL.md 的正文内容应该遵循渐进式披露原则，将核心信息放在前面，详细信息通过引用指向参考文档。

推荐的正文结构：

# 技能标题
## 概述（Overview）
1-2 句话说明技能的核心功能。
## 何时使用（When to Use）
✅ 使用场景列表
❌ 不适用场景列表
## 快速开始（Quick Start）
最简单的使用示例，让用户能够快速上手。
## 详细用法（Detailed Usage）
分功能模块详细介绍使用方法。
## 参数说明（Parameters）
表格形式列出所有参数及其说明。
## 注意事项（Notes）
重要的限制、依赖和最佳实践。

4.4 完整示例：weather 技能

下面是一个完整的 SKILL.md 示例：

---
name: weather
description: "Get current weather and forecasts via wttr.in or Open-Meteo. Use when: user asks about weather, temperature, or forecasts for any location. NOT for: historical weather data, severe weather alerts, or detailed meteorological analysis. No API key needed."
homepage: https://wttr.in/:help
metadata:
  openclaw:
    emoji: "🌤️"
    requires:
      bins: ["curl"]
---
# Weather Skill
Get current weather conditions and forecasts.

## When to Use
✅ **USE this skill when:**
- What's the weather?
- Will it rain today/tomorrow?
- Temperature in [city]
- Weather forecast for the week
- Travel planning weather checks

## When NOT to Use
❌ **DON'T use this skill when:**
- Historical weather data → use weather archives/APIs
- Climate analysis or trends → use specialized data sources
- Severe weather alerts → check official NWS sources

## Commands
### Current Weather
# One-line summary
curl "wttr.in/London?format=3"
# Detailed current conditions
curl "wttr.in/London?0"

### Forecasts
# 3-day forecast
curl "wttr.in/London"
# Week forecast
curl "wttr.in/London?format=v2"

## Notes
- No API key needed (uses wttr.in)
- Rate limited; don't spam requests
- Works for most global cities

这个示例展示了如何用简洁的方式定义一个完整的技能：

• 元数据清晰说明了功能和触发条件
• 正文提供了快速参考的命令示例
• 注意事项提醒了使用限制

5. 技能加载机制

5.1 三层加载架构

OpenClaw Skills 系统采用三层渐进式加载架构，这是其核心设计理念：

第一层：元数据

始终存在于上下文中，占用约 100 个词。这一层包含 name 和 description 字段，OpenClaw 通过它们判断是否需要激活某个技能。

第二层：SKILL.md 正文

当技能被触发时加载，建议控制在 5000 词以内。这一层包含具体的使用指令、工作流程和示例。

第三层：捆绑资源

按需加载，理论上无大小限制。脚本可以直接执行而无需加载到上下文，参考文档和资产文件在需要时才读取。

5.2 技能触发流程

1. 用户发送消息：今天天气怎么样？
2. 文件系统扫描所有技能的 description
3. 查询匹配的技能
4. 匹配到 weather 技能
5. 读取 weather/SKILL.md
6. 返回技能正文
7. 加载技能到上下文
8. 执行技能指令
9. 执行 curl wttr.in 命令
10. 返回天气数据
11. 回复天气信息

5.3 技能目录扫描

OpenClaw 会扫描以下目录查找技能：

1. 内置技能目录：/app/skills/ — 随 OpenClaw 发行的基础技能
2. 工作区技能目录：~/.openclaw/workspace/skills/ — 用户自定义技能
3. 扩展技能目录：通过配置指定的额外路径

技能发现过程：

1. 扫描所有技能目录，查找 SKILL.md 文件
2. 解析每个 SKILL.md 的 YAML 前置元数据
3. 将所有技能的元数据加载到上下文
4. 根据用户输入匹配最相关的技能

5.4 资源加载策略

不同类型的资源有不同的加载策略：

这种策略确保了：

• 脚本执行的高效性（无需解析）
• 参考文档的灵活性（按需获取详细信息）
• 资产文件的直接可用性（模板、图片等）

6. 内置技能介绍

OpenClaw 自带了丰富的内置技能，覆盖了常见的使用场景。以下是一些代表性技能的介绍：

6.1 工具类技能

weather — 天气查询

通过 wttr.in API 获取全球天气信息，无需 API 密钥。支持当前天气、多日预报、多种输出格式。

downloader — 文件下载

从 URL 下载文件到本地，支持任意文件类型。适合需要保存远程资源的场景。

uploader — 文件上传

将本地文件上传到云存储并返回公开下载链接。

6.2 内容创作类技能

tech-article — 技术文章写作

生成高质量的技术博客文章，目标质量分 98+。支持深度教程、项目实战、源码分析等多种类型。

podcast-gen — 播客生成

根据主题描述生成口语化播客脚本，并合成 MP3 音频。

canvas-design — 视觉设计

创建精美的海报、图表等视觉内容，支持 PNG 和 PDF 输出。

6.3 AI 能力类技能

xfyun-tts — 讯飞语音合成

使用讯飞超拟人语音合成 API，支持 50+ 种声音，可调节语速、音量、音调。

xfyun-ocr — 讯飞 OCR

识别图片中的文字，支持公式、表格、多栏布局等复杂场景。

xfyun-image-understanding — 图片理解

分析图片内容并回答问题，基于讯飞星火视觉模型。

6.4 系统管理类技能

healthcheck — 安全加固

评估和加固运行 OpenClaw 的主机，配置风险容忍度，执行安全审计。

skill-creator — 技能创建

辅助创建新的技能包，提供模板生成、验证和打包功能。

6.5 内置技能一览表

7. 第一个自定义技能

7.1 需求分析

假设我们需要创建一个待办事项管理技能，功能包括：

• 添加待办事项
• 列出所有待办
• 标记完成
• 删除待办

7.2 创建技能目录

使用 skill-creator 技能提供的初始化脚本：

python3 /app/skills/skill-creator/scripts/init_skill.py todo-manager \
--path ~/.openclaw/workspace/skills \
--resources scripts \
--examples

这个命令会创建以下结构：

todo-manager/
├── SKILL.md
└── scripts/
    └── example.py

7.3 编写 SKILL.md

编辑 SKILL.md 文件，填入技能定义：

---
name: todo-manager
description: "Todo list management - add, list, complete, and delete tasks. Use when user wants to manage their todo list, create tasks, check pending items, or organize their work. Supports priority levels and due dates."
---
# Todo Manager
Manage your personal todo list with simple commands.

## When to Use
✅ **USE this skill when:**
- Add a task: buy groceries
- Show my todos
- Mark task 1 as done
- Delete task 2
- What's on my list?

## When NOT to Use
❌ **DON'T use this skill when:**
- Calendar events → use calendar integration
- Project management → use dedicated tools
- Team collaboration → use team tools

## Commands
### Add a task
python3 scripts/todo.py add "Buy groceries" --priority high

### List all tasks
python3 scripts/todo.py list

### Complete a task
python3 scripts/todo.py complete 1

### Delete a task
python3 scripts/todo.py delete 2

## Data Storage
Tasks are stored in `~/.openclaw/workspace/data/todos.json`:
```json
{"tasks":[{"id":1,"title":"Buy groceries","priority":"high","completed":false,"created_at":"2024-01-15T10:30:00"}]}

Notes

• Tasks are persisted locally
• Priority levels: low, medium, high
• IDs are auto-incremented

#### 7.4 编写脚本实现

创建 scripts/todo.py：

```python
#!/usr/bin/env python3
""" Todo Manager - A simple command-line todo list manager
Usage:
    python3 todo.py add "Task title" [--priority low|medium|high]
    python3 todo.py list [--all|--pending|--completed]
    python3 todo.py complete <id>
    python3 todo.py delete <id>
"""
import argparse
import json
import os
from datetime import datetime
from pathlib import Path

# 数据文件路径
DATA_DIR = Path.home() / ".openclaw" / "workspace" / "data"
DATA_FILE = DATA_DIR / "todos.json"

def ensure_data_file():
    """确保数据文件存在"""
    DATA_DIR.mkdir(parents=True, exist_ok=True)
    if not DATA_FILE.exists():
        with open(DATA_FILE, 'w') as f:
            json.dump({"tasks": [], "next_id": 1}, f)

def load_data():
    """加载待办数据"""
    ensure_data_file()
    with open(DATA_FILE, 'r') as f:
        return json.load(f)

def save_data(data):
    """保存待办数据"""
    with open(DATA_FILE, 'w') as f:
        json.dump(data, f, indent=2)

def add_task(title, priority="medium"):
    """添加新任务"""
    data = load_data()
    task = {
        "id": data["next_id"],
        "title": title,
        "priority": priority,
        "completed": False,
        "created_at": datetime.now().isoformat()
    }
    data["tasks"].append(task)
    data["next_id"] += 1
    save_data(data)
    print(f"✅ Task #{task['id']} added: {title}")

def list_tasks(filter_type="all"):
    """列出任务"""
    data = load_data()
    tasks = data["tasks"]
    if filter_type == "pending":
        tasks = [t for t in tasks if not t["completed"]]
    elif filter_type == "completed":
        tasks = [t for t in tasks if t["completed"]]
    if not tasks:
        print("No tasks found.")
        return
    print(f"\n{'ID':<4}{'Status':<10}{'Priority':<8}{'Title'}")
    print("-" * 50)
    for task in tasks:
        status = "✓ Done" if task["completed"] else "○ Pending"
        print(f"{task['id']:<4}{status:<10}{task['priority']:<8}{task['title']}")

def complete_task(task_id):
    """标记任务完成"""
    data = load_data()
    for task in data["tasks"]:
        if task["id"] == task_id:
            task["completed"] = True
            save_data(data)
            print(f"✅ Task #{task_id} completed: {task['title']}")
            return
    print(f"❌ Task #{task_id} not found")

def delete_task(task_id):
    """删除任务"""
    data = load_data()
    for i, task in enumerate(data["tasks"]):
        if task["id"] == task_id:
            deleted = data["tasks"].pop(i)
            save_data(data)
            print(f"🗑️ Task #{task_id} deleted: {deleted['title']}")
            return
    print(f"❌ Task #{task_id} not found")

def main():
    parser = argparse.ArgumentParser(description="Todo list manager")
    subparsers = parser.add_subparsers(dest="command", required=True)
    
    # add 命令
    add_parser = subparsers.add_parser("add", help="Add a new task")
    add_parser.add_argument("title", help="Task title")
    add_parser.add_argument("--priority", choices=["low", "medium", "high"], default="medium", help="Task priority")
    
    # list 命令
    list_parser = subparsers.add_parser("list", help="List tasks")
    list_parser.add_argument("--all", action="store_true", help="Show all tasks")
    list_parser.add_argument("--pending", action="store_true", help="Show pending tasks")
    list_parser.add_argument("--completed", action="store_true", help="Show completed tasks")
    
    # complete 命令
    complete_parser = subparsers.add_parser("complete", help="Mark task as completed")
    complete_parser.add_argument("id", type=int, help="Task ID")
    
    # delete 命令
    delete_parser = subparsers.add_parser("delete", help="Delete a task")
    delete_parser.add_argument("id", type=int, help="Task ID")
    
    args = parser.parse_args()
    
    if args.command == "add":
        add_task(args.title, args.priority)
    elif args.command == "list":
        if args.pending:
            list_tasks("pending")
        elif args.completed:
            list_tasks("completed")
        else:
            list_tasks("all")
    elif args.command == "complete":
        complete_task(args.id)
    elif args.command == "delete":
        delete_task(args.id)

if __name__ == "__main__":
    main()

上述代码实现了一个完整的命令行待办事项管理器。主要功能包括：add 命令用于添加新任务，支持设置优先级（low/medium/high）；list 命令用于列出任务，支持按状态筛选；complete 命令用于标记任务完成；delete 命令用于删除任务。数据以 JSON 格式持久化存储在 ~/.openclaw/workspace/data/todos.json 文件中，包含任务 ID、标题、优先级、完成状态和创建时间等信息。脚本使用 Python 标准库的 argparse 模块处理命令行参数，json 模块处理数据存储，datetime 模块记录时间戳，无需安装任何第三方依赖。

7.5 验证技能

使用验证脚本检查技能结构：

python3 /app/skills/skill-creator/scripts/quick_validate.py \
 ~/.openclaw/workspace/skills/todo-manager 

验证通过后，重启 OpenClaw 或等待自动刷新，新技能即可生效。

7.6 测试技能

在 OpenClaw 中测试新技能：

用户：帮我添加一个待办：明天开会
AI：✅ Task #1 added: 明天开会
用户：查看我的待办
AI： ID Status Priority Title -------------------------------------------------- 1 ○ Pending medium 明天开会
用户：标记任务 1 完成
AI：✅ Task #1 completed: 明天开会

8. 技能调试技巧

8.1 常见问题排查

技能未被触发

检查 description 字段是否包含足够的关键词。确保描述中列出了用户可能的表达方式。

# 问题：描述太简略
description: "Todo management"
# 解决：添加触发场景
description: "Todo list management - add, list, complete, and delete tasks. Use when user wants to manage their todo list, create tasks, check pending items."

脚本执行失败

1. 检查脚本权限：chmod +x scripts/todo.py
2. 检查 Python 版本兼容性
3. 检查依赖是否安装
4. 查看错误日志

上下文过长

如果 SKILL.md 正文过长，考虑：

1. 将详细内容移至 references/ 目录
2. 在 SKILL.md 中添加引用链接
3. 精简指令，保留核心内容

8.2 调试工具

快速验证脚本

# 验证技能结构
python3 /app/skills/skill-creator/scripts/quick_validate.py <skill-path>
# 打包技能
python3 /app/skills/skill-creator/scripts/package_skill.py <skill-path>

日志查看

# 查看 OpenClaw 日志
tail -f ~/.openclaw/logs/openclaw.log
# 查看技能加载日志
grep "skill" ~/.openclaw/logs/openclaw.log

8.3 最佳实践

描述优化

• 使用具体的动词和名词
• 列出典型的用户表达
• 说明不适用场景

内容组织

• 核心指令放在 SKILL.md
• 详细文档放在 references/
• 可执行逻辑放在 scripts/

版本管理

• 使用 Git 管理技能代码
• 为技能添加版本号
• 保持向后兼容

9. 高级话题

9.1 技能组合

多个技能可以协同工作。例如，podcast-gen 技能内部会调用 xfyun-tts 技能进行语音合成。设计技能时，可以考虑与其他技能的协作：

description: "Generate podcast audio from topic description. Combines web search, script generation, and TTS synthesis. Use when user wants to create audio content or podcast episodes."

9.2 技能市场

OpenClaw 支持通过 ClawHub 分享和获取技能：

# 搜索技能
openclaw skill search weather
# 安装技能
openclaw skill install xfyun-tts
# 更新技能
openclaw skill update weather

9.3 技能热更新

修改技能后，无需重启 OpenClaw：

• 元数据变更：下次请求时自动刷新
• 正文变更：下次触发时重新加载
• 脚本变更：下次执行时使用新版本

10. 总结

OpenClaw Skills 技能系统是一个精心设计的扩展框架，通过模块化、渐进式加载的设计，实现了功能丰富性与上下文效率的平衡。本文从系统概述、目录结构、配置文件、加载机制等多个维度进行了全面介绍，并通过实战案例演示了自定义技能的完整开发流程。

核心要点回顾：

1. 三层加载架构：元数据始终加载、正文触发加载、资源按需加载，这种设计确保了上下文的高效利用。
2. 简洁的配置格式：仅需一个 SKILL.md 文件即可定义技能，降低了开发门槛。
3. 灵活的资源组织：scripts/、references/、assets/ 三种资源类型满足不同场景需求。
4. 丰富的内置技能：覆盖工具、内容创作、AI 能力等多个领域，可直接使用或作为开发参考。
5. 完善的调试支持：提供验证、打包等工具，简化开发和发布流程。

思考题：

1. 在你的使用场景中，哪些重复性的任务可以封装成技能？
2. 如何设计技能的 description 才能确保准确触发，同时避免误触发？
3. 对于复杂的业务流程，如何平衡 SKILL.md 的长度和信息的完整性？

参考资料

• OpenClaw 官方文档
• OpenClaw GitHub 仓库
• 讯飞开放平台
• wttr.in 天气 API