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

七夜zippoe

439人浏览 · 2026-04-07 18:08:11

七夜zippoe · 2026-04-07 18:08:11 发布

摘要

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 根据用户需求动态激活相应的技能。这种设计带来了几个显著优势：

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

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

特性	传统插件系统	OpenClaw Skills
加载机制	启动时全量加载	按需动态加载
配置复杂度	需要注册表、依赖注入	仅需 SKILL.md 文件
上下文占用	常驻内存	按需加载到上下文
开发门槛	需要了解框架 API	只需编写 Markdown
调试方式	需要重启服务	热更新，即时生效

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

2.3 技能的分类

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

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

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

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

集成型技能：连接外部服务。例如 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 会根据这个描述判断何时激活技能。

编写高质量描述的要点：

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

# 好的描述示例
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 技能触发流程

5.3 技能目录扫描

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

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

技能发现过程：

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

5.4 资源加载策略

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

资源类型	加载时机	加载方式
scripts/	执行时	直接运行，不加载到上下文
references/	需要时	读取文件内容到上下文
assets/	输出时	复制或引用，不加载到上下文

这种策略确保了：

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

6. 内置技能介绍

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

6.1 工具类技能

weather — 天气查询

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

downloader — 文件下载

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

uploader — 文件上传

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

6.2 内容创作类技能

csdn-article — CSDN 文章写作

生成高质量的技术博客文章，目标质量分 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 内置技能一览表

技能名称	类别	功能描述
weather	工具	天气查询与预报
downloader	工具	文件下载
uploader	工具	文件上传
csdn-article	内容	CSDN 文章写作
podcast-gen	内容	播客生成
canvas-design	内容	视觉设计
xfyun-tts	AI	语音合成
xfyun-ocr	AI	文字识别
xfyun-search	AI	网络搜索
healthcheck	系统	安全审计
skill-creator	开发	技能创建
clawhub	开发	技能市场

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`:

{
  "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"

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."

脚本执行失败

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

上下文过长

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

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

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

核心要点回顾：

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

思考题：

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

参考资料

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

遗传算法（GA）求解带容量限制的车辆路径规划问题（CVRP）（附MATLAB）

AtomGit开源社区

主流AI命理工具实测：八字紫微梅花六爻避坑指南

AtomGit开源社区

下一代前端框架：Vue3 Composition API与SpringBoot3完美融合

AtomGit开源社区

所有评论(0)

查看更多评论

七夜zippoe

@sinat_41617212

已为社区贡献36条内容