OpenClaw Skills 技能系统入门：打造可扩展的 AI 助手能力体系

目录

• 摘要
• 1. 引言
• 2. Skills 技能系统概述
  • 2.1 什么是 Skills？
  • 2.2 Skills 与传统插件系统的区别
  • 2.3 技能的分类
• 3. 技能的目录结构
  • 3.1 标准目录结构
  • 3.2 各目录的作用
  • 3.3 实际案例：xfyun-tts 技能目录
• 4. SKILL.md 配置文件详解
  • 4.1 文件结构
  • 4.2 元数据字段详解
  • 4.3 正文内容组织
  • 4.4 完整示例：weather 技能
• 5. 技能加载机制
  • 5.1 三层加载架构
  • 5.2 技能触发流程
  • 5.3 技能目录扫描
  • 5.4 资源加载策略
• 6. 内置技能介绍
  • 6.1 工具类技能
  • 6.2 内容创作类技能
  • 6.3 AI 能力类技能
  • 6.4 系统管理类技能
  • 6.5 内置技能一览表
• 7. 第一个自定义技能
  • 7.1 需求分析
  • 7.2 创建技能目录
  • 7.3 编写 SKILL.md
  • 7.4 编写脚本实现
  • 7.5 验证技能
  • 7.6 测试技能
• 8. 技能调试技巧
  • 8.1 常见问题排查
  • 8.2 调试工具
  • 8.3 最佳实践
• 9. 高级话题
  • 9.1 技能组合
  • 9.2 技能市场
  • 9.3 技能热更新
• 10. 总结
• 参考资料

摘要

OpenClaw Skills 技能系统是 OpenClaw 框架的核心扩展机制，它通过模块化、可复用的技能包为 AI 助手赋予专业能力。本文将深入剖析 Skills 系统的设计理念、目录结构、配置文件规范以及技能加载机制，帮助开发者快速掌握技能开发技巧。通过实战案例，读者将学会如何创建第一个自定义技能，并了解技能调试的最佳实践。无论是想要增强 AI 助手的功能，还是希望将专业知识封装成可复用的技能包，本文都将为你提供完整的入门指南。

1. 引言

在 AI 助手领域，通用大语言模型虽然具备强大的推理和生成能力，但在特定领域的专业任务上往往力不从心。一个优秀的 AI 助手需要具备"术业有专攻"的能力——既能进行通用的对话交互，又能在特定场景下调用专业工具、执行复杂流程。

OpenClaw Skills 技能系统正是为解决这一需求而设计的。它采用"渐进式披露"的设计原则，将技能的元数据、核心指令和资源文件分层加载，在保证功能完整性的同时最大限度地节省上下文空间。这种设计使得 OpenClaw 能够同时支持数十个技能，而不会因为上下文膨胀而影响响应质量。

本文将带领读者全面了解 OpenClaw Skills 系统，从基础概念到实战开发，帮助你掌握这一强大的扩展机制。

2. Skills 技能系统概述

2.1 什么是 Skills？

Skills（技能）是 OpenClaw 框架中的模块化能力单元。每个技能都是一个自包含的包，包含以下核心要素：

• 元数据：技能名称和描述，用于触发匹配
• 指令文档：Markdown 格式的使用指南和最佳实践
• 捆绑资源（可选）：脚本、参考文档、资产文件等

可以把 Skills 理解为 AI 助手的"技能树"——每个技能点代表一项特定能力，AI 根据用户需求动态激活相应的技能。这种设计带来了几个显著优势：

Skills 系统

核心优势

模块化设计

独立开发测试

按需加载

易于维护升级

可复用性

跨项目共享

社区生态

版本管理

上下文效率

渐进式披露

元数据优先

资源按需加载

应用场景

工具集成

API 调用

文件处理

系统操作

领域专家

业务流程

行业知识

最佳实践

输出模板

文档生成

代码模板

设计资产

2.2 Skills 与传统插件系统的区别

传统的插件系统通常需要复杂的注册、初始化和生命周期管理，而 Skills 采用了更加轻量级的设计：

这种设计使得开发者可以专注于"教 AI 如何做事"，而不是"如何与框架集成"。

2.3 技能的分类

根据功能特点，OpenClaw 技能可以分为以下几类：

工具型技能：提供具体的命令行工具或 API 封装。例如 weather 技能封装了 wttr.in 天气 API，downloader 技能提供了文件下载功能。

流程型技能：定义多步骤的工作流程。例如 healthcheck 技能定义了完整的安全审计流程，从环境检测到修复建议。

内容型技能：提供输出模板和参考文档。例如 ZEEKLOG-article 技能定义了 ZEEKLOG 高质量文章的写作规范。

集成型技能：连接外部服务。例如 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 系统采用三层渐进式加载架构，这是其核心设计理念：

技能匹配

需要资源

第三层：捆绑资源（按需加载）

scripts/

references/

assets/

无限制

第二层：SKILL.md 正文（触发时加载）

概述

使用指南

命令示例

~5k words

第一层：元数据（始终加载）

name: weather

description: Get weather...

~100 words

第一层：元数据

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

第二层：SKILL.md 正文

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

第三层：捆绑资源

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

5.2 技能触发流程

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

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 内容创作类技能

ZEEKLOG-article — ZEEKLOG 文章写作

生成高质量的技术博客文章，目标质量分 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 StorageTasks are stored in `~/.openclaw/workspace/data/todos.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：

#!/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"defensure_data_file():"""确保数据文件存在""" DATA_DIR.mkdir(parents=True, exist_ok=True)ifnot DATA_FILE.exists():withopen(DATA_FILE,'w')as f: json.dump({"tasks":[],"next_id":1}, f)defload_data():"""加载待办数据""" ensure_data_file()withopen(DATA_FILE,'r')as f:return json.load(f)defsave_data(data):"""保存待办数据"""withopen(DATA_FILE,'w')as f: json.dump(data, f, indent=2)defadd_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}")deflist_tasks(filter_type="all"):"""列出任务""" data = load_data() tasks = data["tasks"]if filter_type =="pending": tasks =[t for t in tasks ifnot t["completed"]]elif filter_type =="completed": tasks =[t for t in tasks if t["completed"]]ifnot tasks:print("No tasks found.")returnprint(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']}")defcomplete_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']}")returnprint(f"❌ Task #{task_id} not found")defdelete_task(task_id):"""删除任务""" data = load_data()for i, task inenumerate(data["tasks"]):if task["id"]== task_id: deleted = data["tasks"].pop(i) save_data(data)print(f"🗑️ Task #{task_id} deleted: {deleted['title']}")returnprint(f"❌ Task #{task_id} not found")defmain(): 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

实现脚本

本地测试

验证结构

技能触发正确?

优化 description

上下文合理?

拆分到 references

打包发布

描述优化

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

内容组织

• 核心指令放在 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