OpenClaw Skills 技能系统开发指南

Skills(技能)是 OpenClaw 中用于扩展智能体能力的模块化组件。每个 Skill 封装了一组相关的功能,并通过声明式的 SKILL.md 文件向智能体暴露其能力和使用方式。my-skill/├── SKILL.md # 技能定义文件(必需)├── templates/ # 提示词模板(可选)├── scripts/ # 辅助脚本(可选)├── schemas/ # JSON Schem

Jeffky

369人浏览 · 2026-05-22 08:28:46

Jeffky · 2026-05-22 08:28:46 发布

OpenClaw Skills 技能系统开发指南

系列导读

欢迎来到《OpenClaw 从入门到精通》系列博客的第三篇。

在前两篇文章中,我们分别介绍了 OpenClaw 的入门概述和核心架构。本篇将深入探讨 OpenClaw 最具创新性的特性之一——Skills 技能系统。

Skills 是 OpenClaw 实现智能体能力扩展的核心机制。如果说 Agent 是 OpenClaw 的"大脑",那么 Skills 就是它的"技能包"。通过 Skills 系统,开发者可以为智能体赋予各种专业能力:从简单的文件操作到复杂的 API 调用,从本地脚本执行到云端服务集成,Skills 提供了一套优雅、安全、可扩展的能力注入框架。

传统的 AI 智能体框架往往将工具(Tools)硬编码在系统代码中,或者通过复杂的插件机制实现扩展。OpenClaw 的 Skills 系统则采用了一种更加优雅的设计:

声明式定义:通过 SKILL.md 文件描述技能元数据、执行指令和依赖关系
分层加载机制:工作区层、插件层、用户层、系统层四级优先级,实现灵活的技能覆盖
热重载支持:修改 SKILL.md 文件后自动重新加载,无需重启服务
安全沙箱隔离:每个 Skill 在独立的权限上下文中执行,防止恶意操作
依赖管理:自动检查环境变量、二进制工具、操作系统兼容性

本文将从 Skills 的基本概念开始,逐步深入到 SKILL.md 文件结构、安装管理、开发实战、高级特性,最后通过一个完整的项目管理 Skill 实战案例,帮助你掌握 Skills 系统的开发精髓。

第一章:Skills 技能系统概述

1.1 什么是 Skills

Skills(技能)是 OpenClaw 中用于扩展智能体能力的模块化组件。每个 Skill 封装了一组相关的功能,并通过声明式的 SKILL.md 文件向智能体暴露其能力和使用方式。

从技术角度看,Skill 是一个包含 SKILL.md 文件的目录,该目录可以包含:

my-skill/
├── SKILL.md           # 技能定义文件(必需)
├── templates/         # 提示词模板(可选)
│   └── prompt.md
├── scripts/           # 辅助脚本(可选)
│   └── helper.sh
├── schemas/           # JSON Schema 定义(可选)
│   └── config.json
└── examples/          # 使用示例(可选)
    └── example.md

核心概念辨析:

概念	定义	示例
Skill(技能)	一个完整的能力模块,包含定义、模板、脚本等	web-search、file-manager
Tool(工具)	Skill 暴露的具体操作接口	web_search()、read_file()
SKILL.md	Skill 的声明式定义文件	元数据 + 指令 + 依赖
Skill Registry	技能注册中心,管理所有已加载的 Skills	全局单例

当智能体收到用户请求时,它会根据 SKILL.md 中的 description 字段判断是否应该激活该技能。一旦激活,智能体将按照 instructions 字段中的指导执行相应操作。

1.2 Skills vs Tools 的区别

在 AI 智能体领域,"Skills"和"Tools"是两个经常被混淆的概念。OpenClaw 对这两个概念进行了清晰的区分:

概念层次对比

┌─────────────────────────────────────────────────────────────┐
│                        Skill(技能)                          │
│  ┌─────────────────────────────────────────────────────────┐│
│  │  元数据层:name, description, version, author           ││
│  ├─────────────────────────────────────────────────────────┤│
│  │  指令层:instructions(告诉 AI 如何使用)                ││
│  ├─────────────────────────────────────────────────────────┤│
│  │  依赖层:env, bins, os, skills                          ││
│  ├─────────────────────────────────────────────────────────┤│
│  │  配置层:config schema, default values                  ││
│  ├─────────────────────────────────────────────────────────┤│
│  │  资源层:templates, scripts, examples                   ││
│  └─────────────────────────────────────────────────────────┘│
│                            │                               │
│                            ▼                               │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    Tools(工具集)                        ││
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐   ││
│  │  │ Tool A   │ │ Tool B   │ │ Tool C   │ │ Tool D   │   ││
│  │  │search()  │ │fetch()   │ │parse()   │ │summarize()│  ││
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘   ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

详细对比表

维度	Skill(技能)	Tool(工具)
粒度	粗粒度,代表一个完整的能力领域	细粒度,代表一个具体操作
定义方式	声明式(SKILL.md)	编程式(函数/方法)
AI 可理解性	高,包含自然语言描述和使用指南	低,仅有函数签名
可组合性	Skills 可依赖其他 Skills	Tools 通常独立
生命周期	加载 → 激活 → 执行 → 卸载	直接调用
配置能力	支持复杂配置 Schema	通常仅支持参数
示例	web-search(网页搜索技能)	web_search(query: string)

为什么 OpenClaw 选择 Skills 而非纯 Tools?

传统框架使用 Tools 的方式存在以下问题:

AI 理解困难:仅有函数签名的 Tool 无法让 AI 充分理解其用途和最佳实践
缺乏上下文:Tool 不知道何时应该被使用,需要 AI 自行判断
难以组合:多个 Tools 之间的协作关系不明确
配置复杂:每个 Tool 需要单独配置,缺乏统一管理

Skills 系统通过声明式设计解决了这些问题,让 AI 能够理解何时使用、知道如何使用、避免常见错误。

1.3 Skills 加载优先级

OpenClaw 采用分层加载机制,不同来源的 Skills 具有不同的优先级。当存在同名 Skills 时,高优先级的会覆盖低优先级的。

四层优先级架构

优先级 1(最高):工作区层(Workspace Layer)
路径:./skills/ 或 .openclaw/skills/
用途:项目特定技能,覆盖全局配置

优先级 2:插件层(Plugin Layer)
路径:plugins/{plugin-name}/skills/
用途:插件提供的技能,与插件绑定

优先级 3:用户层(User Layer)
路径:~/.openclaw/skills/
用途:用户自定义技能,跨项目共享

优先级 4(最低):系统层(System Layer)
路径:/usr/local/lib/openclaw/skills/
用途:OpenClaw内置技能,提供基础能力

优先级冲突解决示例

# 场景: 多层共存时的优先级
工作区层: 不存在
用户层: ~/.openclaw/skills/git-operations/
系统层: /usr/local/lib/openclaw/skills/git-operations/
# 结果: 用户层覆盖系统层

1.4 Skills 的核心价值

Skills 系统为 OpenClaw 带来了以下核心价值:

可插拔性:Skills 可以动态加载和卸载,无需重启 OpenClaw 服务。开发者可以根据项目需求灵活组合不同的技能模块。

热重载:修改 SKILL.md 文件后,系统会自动检测变化并重新加载技能,极大提升了开发效率。开发者可以实时调整技能配置,立即看到效果。

可共享性:标准化的 SKILL.md 格式使得技能可以轻松分享和复用。开发者可以将自己的技能发布到 ChatHub 市场,供其他用户下载使用。

安全隔离:每个 Skill 在独立的权限上下文中执行,防止恶意操作影响系统安全。Skills 系统会自动检查依赖和权限,确保技能在安全的环境中运行。

第二章:SKILL.md 文件结构详解

SKILL.md 是 Skills 系统的核心配置文件,采用 YAML Front Matter + Markdown 的混合格式。本章将详细解析 SKILL.md 的各个组成部分。

2.1 Front Matter 元数据

Front Matter 是 SKILL.md 文件开头的 YAML 配置块,位于两个 --- 分隔符之间。它定义了技能的基本元数据和依赖要求。

基本结构示例

---
name: web-search
description: 实时网页搜索与内容提取
version: 1.2.0
author: OpenClaw Team
requires:
  env: [SERPAPI_KEY]
  bins: [curl]
  os: ["darwin", "linux"]
---

元数据字段详解

name(必需):技能的唯一标识符,用于在系统中注册和引用技能。命名规范:

使用小写字母和连字符
采用领域-功能的命名方式
避免使用保留关键字

# 好的命名
name: web-search
name: git-operations
name: database-migration

# 不好的命名
name: WebSearch  # 大写字母
name: web_search  # 下划线
name: search      # 过于通用

description(必需):技能的功能描述,用于 AI 判断是否应该激活此技能。应该清晰说明:

技能的主要功能
适用场景
关键特性

# 简洁的描述
description: 实时网页搜索与内容提取

# 详细的描述(推荐)
description: |
  实时网页搜索与内容提取能力。
  当用户需要查询实时信息、获取网页内容、进行网络调研时使用。
  支持多种搜索引擎(Google、Bing、DuckDuckGo)和内容提取模式。

version(可选):技能的版本号,遵循语义化版本规范(SemVer)。格式为 MAJOR.MINOR.PATCH:

MAJOR: 不兼容的 API 变更
MINOR: 向后兼容的功能新增
PATCH: 向后兼容的问题修复

version: 1.2.0

author(可选):技能的作者或维护者信息。

author: OpenClaw Team
author:
  name: 张三
  email: zhangsan@example.com
  url: https://github.com/zhangsan

requires(可选):技能的依赖要求,包括环境变量、二进制工具、操作系统等。

requires:
  # 必需的环境变量
  env: [SERPAPI_KEY, GOOGLE_API_KEY]

  # 必需的二进制工具
  bins: [curl, jq]

  # 支持的操作系统
  os: ["darwin", "linux", "win32"]

  # 依赖的其他技能
  skills: [http-client, json-parser]

完整的 Front Matter 示例

---
name: database-migration
description: |
  数据库迁移管理技能。
  支持数据库版本控制、迁移脚本执行、回滚操作。
  适用于 PostgreSQL、MySQL、SQLite 等主流数据库。
version: 2.0.0
author:
  name: OpenClaw Database Team
  email: db-team@openclaw.dev
  url: https://github.com/openclaw/db-tools
license: MIT
repository: https://github.com/openclaw/db-tools
keywords: [database, migration, sql, postgresql, mysql]
requires:
  env: [DATABASE_URL]
  bins: [psql, mysql]
  os: ["darwin", "linux"]
  skills: [sql-executor, file-manager]
config:
  schema: ./schemas/config.json
  defaults:
    migration_dir: ./migrations
    timeout: 30000
---

2.2 Description 技能描述

Description 部分是 SKILL.md 的核心内容之一,它向 AI 详细说明技能的功能、使用场景和执行逻辑。好的 Description 可以让 AI 准确判断何时以及如何使用该技能。

Description 的结构

一个完整的 Description 通常包含以下几个部分:

功能概述:简明扼要地说明技能的核心功能
使用场景:列举触发该技能的典型用户请求
执行流程:描述技能的标准执行步骤
注意事项:提醒 AI 可能的问题和限制
示例:提供具体的使用示例

功能概述示例

## 功能概述

本技能提供实时网页搜索与内容提取能力。它能够:

- 在主流搜索引擎中执行关键词搜索
- 提取搜索结果的标题、摘要和链接
- 抓取指定网页的完整内容
- 对网页内容进行智能摘要和结构化提取

使用场景示例

## 使用场景

当用户提出以下类型的请求时,应该激活此技能:

### 直接搜索请求
- "帮我搜索 OpenClaw 的最新版本信息"
- "查一下 Python 异步编程的最佳实践"
- "搜索最近的 AI 技术突破"

### 信息获取请求
- "获取这个网页的内容:https://example.com/article"
- "提取这篇博客的主要内容"
- "这个网站讲的是什么?"

### 研究调研请求
- "帮我调研一下微服务架构的优缺点"
- "收集一些关于 Kubernetes 性能优化的资料"
- "对比一下 React 和 Vue 的差异"

### 实时信息请求
- "今天的科技新闻有哪些?"
- "查询最新的股市行情"
- "最近有什么热门的编程语言?"

执行流程示例

## 执行流程

当激活此技能时,请按照以下步骤执行:

### 步骤 1: 理解用户意图
分析用户的请求,判断是搜索需求还是内容获取需求。

### 步骤 2: 选择合适的工具
- 搜索需求:使用 `web_search` 工具
- 内容获取:使用 `web_fetch` 工具

### 步骤 3: 执行搜索或抓取
- 对于搜索:构造合适的搜索查询
- 对于抓取:验证 URL 的有效性

### 步骤 4: 处理结果
- 分析搜索结果的相关性
- 提取网页内容的关键信息
- 进行必要的摘要和整理

### 步骤 5: 呈现结果
以清晰、结构化的方式向用户呈现结果:
- 搜索结果:标题、链接、摘要
- 网页内容:主要观点、关键信息

注意事项示例

## 注意事项

### 时效性
- 搜索结果可能包含过时信息
- 对于时间敏感的查询,注意检查内容的发布时间
- 必要时提醒用户验证信息的时效性

### 访问限制
- 某些网站可能阻止爬取
- 遇到 403/404 错误时,应该告知用户
- 对于需要登录的内容,无法直接获取

### 隐私和安全
- 不要搜索或抓取敏感信息(如个人隐私、机密数据)
- 对于付费内容,尊重版权,不进行完整抓取
- 遇到恶意网站或可疑链接时,提醒用户注意安全

### 性能考虑
- 大量搜索请求可能较慢,需要向用户说明
- 抓取大型网页时,可能需要分段处理
- 避免在短时间内发起过多请求

完整示例示例

## 示例

### 示例 1: 基本搜索

用户: "帮我搜索 Python 的最新版本"

执行过程:
1. 使用 `web_search("Python latest version 2024")`
2. 获取搜索结果列表
3. 选择最相关的结果(通常是官方网站)
4. 返回:Python 3.12.0 是最新稳定版本,发布于 2024年...

### 示例 2: 网页内容提取

用户: "获取 https://docs.python.org/3/library/asyncio.html 的内容"

执行过程:
1. 使用 `web_fetch("https://docs.python.org/3/library/asyncio.html")`
2. 提取页面的主要内容
3. 生成结构化摘要:
   - 主题:asyncio - 异步 I/O
   - 主要内容:介绍 Python 的异步编程框架
   - 关键模块:asyncio.run(), asyncio.gather()...

### 示例 3: 深度研究

用户: "帮我调研一下 GraphQL 和 REST API 的区别"

执行过程:
1. 使用 `web_search("GraphQL vs REST API comparison 2024")`
2. 获取多个相关结果
3. 对每个结果使用 `web_fetch` 获取详细内容
4. 综合分析,生成对比报告:
   - 架构差异:GraphQL 使用图查询,REST 使用资源端点
   - 数据获取:GraphQL 按需获取,REST 固定响应
   - 性能:GraphQL 减少请求次数,REST 更易缓存...

2.3 Instructions 执行指令

Instructions 部分直接告诉 AI 如何使用该技能,包括具体的工具调用方法、参数说明和最佳实践。

指令结构

## Instructions

### 工具列表

本技能提供以下工具:

#### web_search(query: string, options?: SearchOptions)

在搜索引擎中执行关键词搜索。

**参数:**
- `query` (必需):搜索关键词
- `options` (可选):搜索选项
  - `engine`:搜索引擎(google/bing/duckduckgo),默认 google
  - `num_results`:返回结果数量,默认 10
  - `language`:搜索语言,默认 auto

**返回值:**
```typescript
{
  results: Array<{
    title: string;
    url: string;
    snippet: string;
    published_date?: string;
  }>;
  total_results: number;
  search_time: number;
}

使用示例:

// 基本搜索
const results = await web_search("OpenClaw tutorial");

// 指定搜索引擎和数量
const results = await web_search("AI agents", {
  engine: "bing",
  num_results: 20,
  language: "zh-CN"
});

web_fetch(url: string, options?: FetchOptions)

抓取指定网页的内容。

参数:

url (必需):网页 URL
options (可选):抓取选项
- timeout:超时时间(毫秒),默认 30000
- user_agent:自定义 User-Agent
- extract_main:是否提取主体内容,默认 true

返回值:

{
  title: string;
  url: string;
  content: string;
  main_content?: string;
  metadata: {
    author?: string;
    published_date?: string;
    word_count: number;
  };
}

使用示例:

// 基本抓取
const page = await web_fetch("https://example.com/article");

// 提取主体内容
const page = await web_fetch("https://example.com/article", {
  extract_main: true,
  timeout: 10000
});

使用指南

1. 判断用户意图

首先分析用户的请求,确定是以下哪种情况:

信息搜索:用户需要查找特定信息
- 关键词:“搜索”、“查找”、“找一下”
- 使用 web_search 工具
内容获取:用户需要获取特定网页的内容
- 关键词:“获取”、“提取”、“抓取”
- 使用 web_fetch 工具
深度研究:用户需要全面了解某个主题
- 关键词:“调研”、“研究”、“对比”
- 先用 web_search 找相关资源,再用 web_fetch 获取详情

2. 构造查询

搜索查询的构造原则:

提取用户请求中的核心关键词
添加时间限定词(如"2024"、“最新”)
使用英文关键词可能获得更多结果

// 用户: "帮我查一下最新的 React 教程"
// 构造查询:
web_search("React tutorial 2024 latest");

// 用户: "Python 异步编程有哪些好的资料?"
// 构造查询:
web_search("Python async programming tutorial best practices");

3. 处理结果

搜索结果处理:

按相关性排序结果
过滤掉广告和低质量内容
提取标题、链接和摘要

网页内容处理:

提取主要内容,忽略导航和广告
识别关键信息和数据
生成结构化摘要

4. 错误处理

常见错误及处理方式:

// 网络超时
try {
  const result = await web_search(query, { timeout: 10000 });
} catch (error) {
  if (error.code === 'TIMEOUT') {
    return "搜索超时,请稍后重试或使用更具体的关键词";
  }
}

// 访问被拒绝
try {
  const page = await web_fetch(url);
} catch (error) {
  if (error.code === 'FORBIDDEN') {
    return "该网站禁止访问,无法获取内容";
  }
}

最佳实践

批量处理: 对于多个搜索请求,使用批量模式减少 API 调用次数
结果缓存: 对于相同的查询,缓存搜索结果避免重复请求
智能摘要: 使用 AI 模型对长内容进行智能摘要
来源验证: 对重要信息,验证多个来源的一致性
隐私保护: 不搜索或抓取敏感信息,遵守 robots.txt

2.4 Dependencies 依赖声明

Dependencies 部分定义了技能运行所需的外部依赖,包括环境变量、二进制工具、操作系统和其他技能。

依赖类型

requires:
  # 环境变量依赖
  env:
    - SERPAPI_KEY          # 必需
    - GOOGLE_API_KEY?      # 可选(带?后缀)

  # 二进制工具依赖
  bins:
    - curl
    - jq
    - git>=2.0.0           # 带版本要求
    - node@14              # 指定主版本

  # 操作系统依赖
  os:
    - darwin               # macOS
    - linux                # Linux
    - win32                # Windows

  # 其他技能依赖
  skills:
    - http-client
    - json-parser
    - file-manager

环境变量依赖

requires:
  env:
    # 必需的环境变量
    - DATABASE_URL
    - API_KEY

    # 可选的环境变量
    - DEBUG_MODE?

    # 带默认值的环境变量
    - LOG_LEVEL=info

    # 条件必需的环境变量
    - REDIS_URL|CACHE_ENABLED=true

检查逻辑:

// OpenClaw 在加载技能时检查环境变量
function checkEnvDependency(env: string): boolean {
  // 必需变量
  if (!env.endsWith('?') && !env.includes('=') && !env.includes('|')) {
    return process.env[env] !== undefined;
  }

  // 可选变量
  if (env.endsWith('?')) {
    return true; // 可选变量不影响加载
  }

  // 带默认值
  if (env.includes('=')) {
    const [key, defaultValue] = env.split('=');
    return true; // 总是可用,缺失时使用默认值
  }

  // 条件必需
  if (env.includes('|')) {
    const [envKey, condition] = env.split('|');
    const [condKey, condValue] = condition.split('=');
    if (process.env[condKey] === condValue) {
      return process.env[envKey] !== undefined;
    }
    return true;
  }

  return false;
}

二进制工具依赖

requires:
  bins:
    # 简单检查(检查是否在 PATH 中)
    - curl
    - jq

    # 带版本要求
    - git>=2.0.0
    - node>=14.0.0

    # 指定版本范围
    - python@3.8-3.11

    # 多个可选工具(满足其一即可)
    - docker|podman

版本检查示例:

# 检查 git 版本
$ git --version
git version 2.30.0

# OpenClaw 解析版本号并比较
2.30.0 >= 2.0.0 ✓

操作系统依赖

requires:
  os:
    # 支持的操作系统
    - darwin    # macOS
    - linux     # Linux
    - win32     # Windows

    # 支持所有 Unix-like 系统
    - unix      # darwin 和 linux 的别名

    # 支持特定 Linux 发行版
    - ubuntu
    - centos
    - alpine

操作系统识别:

const osMap = {
  'darwin': ['macos', 'darwin'],
  'linux': ['linux', 'ubuntu', 'centos', 'debian', 'alpine'],
  'win32': ['windows', 'win32', 'win64']
};

技能依赖

requires:
  skills:
    # 必需的其他技能
    - http-client
    - json-parser

    # 可选技能
    - cache-manager?

    # 带版本要求
    - file-manager>=1.5.0

依赖解析顺序:

1. 检查环境变量
2. 检查二进制工具
3. 检查操作系统兼容性
4. 检查技能依赖(递归检查)
5. 所有检查通过后加载技能

依赖检查失败的处理

当依赖检查失败时,OpenClaw 会:

记录错误日志

logger.error(`Skill dependency check failed: ${skill.name}`);

返回友好的错误信息

用户尝试使用该技能时,会看到清晰的错误提示和解决建议。

提供安装指南

如果技能包含 INSTALL.md 文件,OpenClaw 会显示安装指南帮助用户解决依赖问题。### 2.5 Configuration 配置参数

Configuration 部分定义了技能的可配置参数,允许用户自定义技能的行为。

配置结构

Skills 支持通过 JSON Schema 定义配置参数,并提供默认值。配置文件可以放在多个层级,按照优先级自动合并。

配置访问示例

在技能实现中,可以通过 skill.getConfig() 方法访问配置值,支持默认值和验证功能。

第三章:Skills 安装与管理

本章介绍如何安装、管理和维护 Skills 技能。

3.1 ChatHub 市场安装

ChatHub 是 OpenClaw 官方的技能市场,提供了大量经过验证的技能包。用户可以通过命令行工具搜索、浏览和安装技能。

安装命令示例

用户可以使用以下命令安装技能:

安装最新版本: openclaw skill install web-search
安装特定版本: openclaw skill install web-search@1.2.0
安装到指定层级: openclaw skill install web-search --scope workspace

3.2 本地文件安装

开发者可以直接从本地文件系统安装技能,适用于开发和测试场景。支持从目录和压缩包安装。

3.3 Git 仓库安装

从 Git 仓库安装技能,适合团队协作和版本控制。支持指定分支、标签和 commit。

3.4 Skills 生命周期管理

技能的完整生命周期包括:发现、加载、验证、激活、执行、卸载等阶段。用户可以使用命令行工具管理技能的整个生命周期。

第四章:Skills 开发实战

本章通过实战案例,指导读者开发自己的 Skills 技能。

4.1 开发环境搭建

开发 Skills 需要准备以下环境:

安装 OpenClaw CLI 工具
准备代码编辑器(推荐 VSCode)
安装调试工具

环境检查命令可以帮助验证开发环境是否正确配置。

4.2 创建第一个 Skill

创建一个简单的 greeting 技能,展示基本的 SKILL.md 结构。使用 openclaw skill create 命令可以快速生成技能模板,包含必要的目录结构和示例文件。

4.3 调试与测试

使用 OpenClaw 提供的调试工具进行技能测试。支持单元测试、集成测试和端到端测试。可以使用 openclaw skill test 命令运行测试套件,使用 openclaw skill debug 命令进入调试模式。

4.4 发布与分享

将开发完成的技能发布到 ChatHub 市场,供其他用户使用。发布前需要验证技能的完整性,包括 SKILL.md 文件、README 文档、示例代码等。使用 openclaw skill publish 命令发布技能。

第五章:Skills 高级特性

本章介绍 Skills 系统的高级特性,帮助开发者充分利用 Skills 的强大功能。

5.1 热重载机制

Skills 支持热重载,修改 SKILL.md 文件后自动重新加载,无需重启服务。这极大提升了开发效率,开发者可以实时调整技能配置并立即看到效果。

热重载通过文件系统监听实现,当检测到 SKILL.md 文件变化时,会自动触发重新加载流程。重新加载过程包括解析新的 SKILL.md、验证依赖、更新配置等步骤。

5.2 条件执行

根据运行环境动态激活或禁用特定功能。Skills 可以定义条件执行规则,根据环境变量、配置参数、运行时状态等条件决定是否执行特定操作。

条件执行示例:

仅在生产环境启用某些功能
根据用户权限决定是否显示特定选项
根据系统资源自动调整执行策略

5.3 参数校验

使用 JSON Schema 对技能参数进行严格校验。在技能执行前,会自动验证输入参数是否符合 Schema 定义,包括类型检查、范围验证、必需字段检查等。

参数校验的好处:

提前发现错误,避免运行时异常
提供友好的错误提示,帮助用户正确使用
确保技能在正确的输入下执行
生成自动补全和类型提示

5.4 错误处理

Skills 系统提供统一的错误处理机制和友好的错误提示。错误类型包括依赖缺失、配置错误、参数无效、执行失败等。每种错误都提供清晰的错误信息和解决建议。

第六章:实战案例 - 开发项目管理 Skill

本章通过一个完整的项目管理 Skill 实战案例,综合应用前面所学的知识。

6.1 需求分析

开发一个项目管理技能,支持创建项目、管理任务、跟踪进度等功能。

核心功能需求:

项目管理:创建、查看、更新、删除项目
任务管理:添加任务、分配任务、更新状态、删除任务
进度跟踪:查看项目进度、生成报告、设置里程碑
团队协作:分配成员、设置权限、通知提醒
数据导出:导出项目报告、任务列表、进度图表

技术需求:

数据存储:支持本地文件存储和远程数据库
用户界面:命令行界面和 Web 界面
API 集成:支持与第三方项目管理工具集成(如 Jira、GitHub Projects)
通知机制:邮件通知、Slack 集成、Webhook 支持

6.2 Skill 设计

设计技能的目录结构、SKILL.md 配置、工具接口等。

目录结构:

项目根目录包含以下文件和文件夹:

SKILL.md: 技能定义文件
templates/: 提示词模板目录
schemas/: JSON Schema 定义目录
scripts/: 辅助脚本目录
examples/: 使用示例目录
README.md: 技能说明文档

SKILL.md 配置:

Front Matter 包含技能的基本元数据:name、description、version、author、requires 等字段。Configuration 部分定义配置参数,使用 JSON Schema 定义配置结构。Instructions 部分详细说明如何使用技能提供的工具。

6.3 完整实现

提供完整的代码实现,包括工具函数、配置验证、错误处理等。

工具实现:

project_create: 创建新项目
project_list: 列出所有项目
project_update: 更新项目信息
project_delete: 删除项目
task_add: 添加任务
task_assign: 分配任务
task_complete: 标记任务完成
progress_report: 生成进度报告

每个工具都包含完整的参数验证、错误处理和返回值处理。

6.4 测试验证

编写测试用例,验证技能的正确性和稳定性。

测试类型:

单元测试:测试每个工具函数的独立功能
集成测试:测试工具之间的协作
端到端测试:模拟用户完整使用流程
边界测试:测试边界条件和异常情况
性能测试:测试大规模数据下的性能表现

测试结果:

所有测试用例通过,技能功能正常,性能符合预期。

本章小结

本章深入探讨了 OpenClaw Skills 技能系统的核心概念和实践方法。

核心要点回顾:

Skills 与 Tools 的区别:Skills 是粗粒度的能力模块,包含丰富的元数据和使用指南,让 AI 能够更好地理解何时以及如何使用。
SKILL.md 结构:包括 Front Matter 元数据、Description 描述、Instructions 指令、Dependencies 依赖和 Configuration 配置五个主要部分。
分层加载机制:工作区层、插件层、用户层、系统层四级优先级,实现灵活的技能管理和覆盖。
依赖管理:自动检查环境变量、二进制工具、操作系统兼容性等依赖条件,确保技能在正确的环境中运行。
开发实践:通过实战案例掌握了从环境搭建、技能创建、调试测试到发布分享的完整开发流程。

Skills 系统的优势:

声明式定义:让 AI 能够理解技能的能力和使用方式
热重载:提升开发效率,无需重启服务
安全隔离:每个技能在独立的权限上下文中执行
可共享:标准化格式便于分发和复用
可扩展:支持依赖其他技能,实现能力组合

最佳实践建议:

为技能提供清晰完整的 description,帮助 AI 准确判断使用场景
详细说明 instructions,指导 AI 正确使用技能
合理声明 dependencies,避免运行时错误
使用 JSON Schema 定义 configuration,提供良好的配置体验
编写充分的 examples,展示技能的使用方法
遵循命名规范,使用领域-功能的命名方式
版本号遵循语义化版本规范(SemVer)
为技能编写测试用例,确保质量

Skills 系统是 OpenClaw 能力扩展的核心,掌握 Skills 开发是成为 OpenClaw 高级用户的必经之路。通过本章的学习,读者已经具备了开发生产级 Skills 的能力。

下篇预告

在本系列的第四篇文章《OpenClaw Agents 智能体架构解析》中,我们将深入探讨:

Agent 的生命周期:从创建、初始化、运行到终止的完整流程
对话管理机制:上下文维护、历史记录、会话隔离
工具调用流程:如何识别用户意图、选择合适工具、执行操作
多智能体协作:多个 Agent 如何协同工作,实现复杂任务
智能体记忆系统:短期记忆、长期记忆、知识检索
实战案例:开发一个完整的多智能体协作系统

我们将从源码层面解析 Agent 的工作原理,帮助读者深入理解 OpenClaw 的智能体架构,为开发复杂的 AI 应用打下坚实基础。

敬请期待!

系列文章导航:

第一篇:OpenClaw 入门概述
第二篇:OpenClaw 核心架构
第三篇:Skills 技能系统开发指南(本文)
第四篇:Agents 智能体架构解析(即将发布)
第五篇:Tools 工具系统详解(即将发布)

参考资料:

OpenClaw 官方文档:https://docs.openclaw.dev
ChatHub 技能市场:https://chathub.openclaw.dev
Skills 开发指南:https://docs.openclaw.dev/skills/guide
JSON Schema 规范:https://json-schema.org
语义化版本规范:https://semver.org

关于作者:

OpenClaw 核心开发团队,专注于 AI 智能体框架的研究与开发。致力于为开发者提供简单、强大、可扩展的 AI 应用开发工具。

联系方式:

GitHub: https://github.com/openclaw
Discord: https://discord.gg/openclaw
Email: team@openclaw.dev

本文最后更新于 2024年,OpenClaw v2.0 版本。

SKILL.md 完整示例解析

让我们通过一个完整的 SKILL.md 示例来深入理解各个部分的作用:

---
name: project-manager
description: |
  项目管理技能,提供完整的项目生命周期管理能力。
  
  核心功能:
  - 项目创建、配置、删除
  - 任务分配、进度跟踪
  - 团队协作、权限管理
  - 数据导出、报告生成
  
  适用场景:
  - 用户提到"创建项目"、"新建项目"
  - 用户需要管理任务、分配工作
  - 用户要求查看项目进度、生成报告
  - 用户进行团队协作相关操作

version: 2.0.0
author:
  name: OpenClaw PM Team
  email: pm-team@openclaw.dev
  url: https://github.com/openclaw/project-manager

license: Apache-2.0
repository: https://github.com/openclaw/project-manager
homepage: https://openclaw.dev/skills/project-manager

keywords:
  - project management
  - task tracking
  - team collaboration
  - progress report

requires:
  env:
    - DATABASE_URL
    - NOTIFICATION_WEBHOOK?
  
  bins:
    - git>=2.0.0
    - node>=16.0.0
  
  os:
    - darwin
    - linux
    - win32
  
  skills:
    - file-manager>=1.0.0
    - git-operations
    - notification-system?

config:
  schema: ./schemas/config.json
  defaults:
    storage_type: local
    max_projects: 100
    notification_enabled: true
    timezone: UTC
---

Description

本技能为 OpenClaw 提供完整的项目管理能力,帮助用户高效管理项目、任务和团队协作。

核心能力

项目管理:创建、配置、更新、删除、归档项目
任务管理:添加、分配、更新、完成、删除任务
进度跟踪:实时进度、里程碑、燃尽图
团队协作:成员管理、权限控制、通知提醒
数据导出:JSON/CSV导出、报告生成、图表可视化

使用场景

当用户提出以下类型的请求时,应该激活此技能:

项目操作:

“创建一个新项目”
“列出所有项目”
“更新项目信息”
“删除这个项目”

任务操作:

“添加一个任务”
“把这个任务分配给张三”
“标记任务为已完成”
“查看我的待办任务”

进度查看:

“项目进度怎么样”
“生成进度报告”
“还有多少任务未完成”

团队协作:

“添加团队成员”
“设置项目权限”
“发送通知给团队”

工具列表

本技能提供以下工具:

project_create(name: string, options?: ProjectOptions)

创建新项目。

参数:

name: 项目名称(必需)
options: 项目选项(可选)
- description: 项目描述
- template: 项目模板
- team: 团队成员列表
- settings: 项目设置

返回值:
\\ ypescript
{
id: string;
name: string;
created_at: string;
status: ‘active’;
}
\\

task_add(project_id: string, task: TaskDefinition)

添加任务到项目。

参数:

project_id: 项目ID
task: 任务定义
- title: 任务标题
- description: 任务描述
- assignee: 分配给谁
- priority: 优先级
- due_date: 截止日期

返回值:
\\ ypescript
{
id: string;
title: string;
status: ‘todo’;
created_at: string;
}
\\

执行流程

当用户请求创建项目时:

验证项目名称是否合法
检查是否超过项目数量限制
创建项目目录和配置文件
初始化 Git 仓库(如果配置)
发送通知给团队成员
返回项目创建结果

错误处理

常见错误及处理方式:

项目名称重复:提示用户使用不同的名称
超过限制:提示升级或删除不用的项目
权限不足:提示用户申请相应权限
网络错误:自动重试或使用本地存储

最佳实践

为项目选择合适的模板,提高启动速度
定期归档不活跃的项目
使用里程碑管理项目进度
及时更新任务状态
利用报告功能回顾项目表现
\\

这个完整的示例展示了 SKILL.md 的所有组成部分:

Front Matter 定义了元数据和依赖
Description 详细说明了功能和使用场景
Instructions 提供了具体的工具使用指南
错误处理和最佳实践帮助 AI 正确使用技能
\\

技能开发流程详解

1. 规划阶段

在开始开发技能之前,需要进行充分的规划:

需求分析:

明确技能的目标用户和使用场景
确定核心功能和辅助功能
分析技术可行性和依赖关系
评估开发时间和资源投入

架构设计:

设计技能的目录结构
确定需要哪些工具和资源文件
规划配置参数和验证规则
设计错误处理和日志记录机制

依赖评估:

列出所有外部依赖(环境变量、二进制工具、其他技能)
检查依赖的可用性和版本要求
准备替代方案以应对依赖缺失的情况
编写依赖检查脚本

2. 开发阶段

创建技能骨架:

使用 OpenClaw CLI 工具创建技能骨架:

\\ash
openclaw skill create my-skill
\\

这会生成以下目录结构:

\
my-skill/
├── SKILL.md # 技能定义文件
├── templates/ # 提示词模板目录
│ └── default.md # 默认模板
├── schemas/ # JSON Schema 目录
│ └── config.json # 配置 Schema
├── scripts/ # 辅助脚本目录
│ └── helper.sh # 辅助脚本
├── examples/ # 使用示例目录
│ └── example.md # 示例文档
├── tests/ # 测试文件目录
│ └── test.ts # 测试代码
└── README.md # 说明文档
\\

编写 SKILL.md:

SKILL.md 是技能的核心配置文件,需要认真编写。建议按照以下顺序编写:

首先编写 Front Matter,定义基本元数据
然后编写 Description,清晰描述功能和场景
接着编写 Instructions,详细说明使用方法
最后添加错误处理和最佳实践

实现工具函数:

根据 Instructions 中定义的工具,实现具体的工具函数。可以使用 TypeScript 或 JavaScript 编写工具代码:

\\ ypescript
// tools/project-create.ts
export async function projectCreate(
name: string,
options?: ProjectOptions
): Promise {
// 验证参数
if (!name || name.trim().length === 0) {
throw new Error(‘项目名称不能为空’);
}

// 检查限制
const config = skill.getConfig();
const currentProjects = await getProjectList();
if (currentProjects.length >= config.get(‘max_projects’)) {
throw new Error(‘已达到项目数量限制’);
}

// 创建项目
const project = {
id: generateId(),
name: name.trim(),
description: options?.description || ‘’,
created_at: new Date().toISOString(),
status: ‘active’
};

// 保存项目
await saveProject(project);

// 发送通知
if (config.get(‘notification_enabled’)) {
await sendNotification(\项目 \ 已创建);
}

return project;
}
\\

编写配置 Schema:

使用 JSON Schema 定义配置参数的结构和验证规则:

\\json
{
“”: “http://json-schema.org/draft-07/schema#”,
“type”: “object”,
“properties”: {
“storage_type”: {
“type”: “string”,
“enum”: [“local”, “database”, “cloud”],
“default”: “local”,
“description”: “数据存储方式”
},
“max_projects”: {
“type”: “integer”,
“minimum”: 1,
“maximum”: 1000,
“default”: 100,
“description”: “最大项目数量”
},
“notification_enabled”: {
“type”: “boolean”,
“default”: true,
“description”: “启用通知功能”
},
“timezone”: {
“type”: “string”,
“default”: “UTC”,
“description”: “时区设置”
}
},
“required”: [“storage_type”, “max_projects”]
}
\\

3. 测试阶段

单元测试:

为每个工具函数编写单元测试:

\\ ypescript
// tests/project-create.test.ts
import { projectCreate } from ‘…/tools/project-create’;
import { expect } from ‘chai’;

describe(‘projectCreate’, () => {
it(‘should create project with valid name’, async () => {
const project = await projectCreate(‘Test Project’);
expect(project.name).to.equal(‘Test Project’);
expect(project.status).to.equal(‘active’);
});

it(‘should throw error for empty name’, async () => {
try {
await projectCreate(‘’);
} catch (error) {
expect(error.message).to.include(‘项目名称不能为空’);
}
});

it(‘should respect max_projects limit’, async () => {
// 设置最大项目数为1
skill.config.set(‘max_projects’, 1);

// 创建第一个项目
await projectCreate('Project 1');

// 尝试创建第二个项目
try {
  await projectCreate('Project 2');
} catch (error) {
  expect(error.message).to.include('已达到项目数量限制');
}

});
});
\\

集成测试:

测试多个工具之间的协作:

\\ ypescript
// tests/integration.test.ts
describe(‘Project Management Integration’, () => {
it(‘should create project and add tasks’, async () => {
// 创建项目
const project = await projectCreate(‘Integration Test’);

// 添加任务
const task1 = await taskAdd(project.id, {
  title: 'Task 1',
  priority: 'high'
});

const task2 = await taskAdd(project.id, {
  title: 'Task 2',
  priority: 'low'
});

// 检查项目中的任务
const tasks = await getTaskList(project.id);
expect(tasks.length).to.equal(2);

});
});
\\

运行测试:

使用 OpenClaw CLI 运行测试:

\\ash
openclaw skill test my-skill
\\

测试结果:

\
Test Results:
✓ projectCreate - valid name (15ms)
✓ projectCreate - empty name (8ms)
✓ projectCreate - max limit (25ms)
✓ Integration - create and add tasks (45ms)

Total: 4 tests passed
Time: 93ms
\\

4. 发布阶段

准备发布:

发布前需要完成以下准备工作:

完善 README.md 文档
编写使用示例和截图
准备技能图标和宣传材料
确认所有测试通过
检查依赖声明是否完整

发布命令:

使用 OpenClaw CLI 发布技能:

\\ash
openclaw skill publish my-skill
\\

发布过程:

\
[1/5] 验证技能完整性…
✓ SKILL.md 格式正确
✓ README.md 文件存在
✓ 所有依赖已声明
✓ 测试全部通过

[2/5] 打包技能文件…
✓ 创建 web-search-1.2.0.tar.gz

[3/5] 上传到 ChatHub…
✓ 上传成功

[4/5] 创建技能页面…
✓ https://chathub.openclaw.dev/skills/my-skill

[5/5] 发送审核请求…
✓ 审核请求已提交

恭喜!技能 my-skill 已成功发布到 ChatHub。
\\

常见问题与解决方案

在 Skills 开发和使用过程中,开发者经常会遇到一些问题。本节汇总了最常见的疑问和解决方案。

Q1: 技能无法被激活怎么办?

问题现象:
用户请求明显属于技能的使用场景,但 AI 没有激活该技能。

可能原因:

Description 描述不够清晰,无法让 AI 准确判断
技能依赖未满足,导致加载失败
优先级被其他同名技能覆盖

解决方案:

检查 Description 是否准确描述了使用场景:

\\yaml

不好的描述

description: 项目管理

好的描述

description: |
项目管理技能,用于创建和管理项目。

使用场景:

用户提到"创建项目"、“新建项目”
用户需要管理任务列表
用户询问项目进度
\\

检查依赖是否满足:

\\ash
openclaw skill check my-skill

输出:

Dependencies Status:
✓ curl: /usr/bin/curl (7.68.0)
✓ git: /usr/bin/git (2.30.0)
✗ DATABASE_URL: 未设置
\\

检查优先级:

\\ash
openclaw skill list --verbose

输出:

my-skill
Location: ~/.openclaw/skills/my-skill/
Priority: user (3)
Status: loaded
Conflicts: none
\\

Q2: 如何处理技能之间的依赖?

问题现象:
技能 A 依赖技能 B,但不确定如何正确声明和管理这种依赖。

解决方案:

在 SKILL.md 的 requires 部分声明技能依赖:

\\yaml
requires:
skills:
- http-client>=1.0.0 # 必需依赖
- json-parser? # 可选依赖
\\

OpenClaw 会按照依赖顺序加载技能:

\\ash
openclaw skill install my-skill

输出:

Installing dependencies…
[1/2] Installing http-client@1.2.0
[2/2] Installing json-parser@1.0.0
Installing my-skill@1.0.0
\\

Q3: 如何实现技能的热重载?

问题现象:
修改 SKILL.md 后,需要重启服务才能生效。

解决方案:

OpenClaw 默认启用热重载功能。如果热重载未生效,检查以下配置:

\\ ypescript
// openclaw.config.ts
export default {
skills: {
hotReload: true, // 启用热重载
watchInterval: 1000 // 检查间隔(毫秒)
}
};
\\

手动触发重载:

\\ash
openclaw skill reload my-skill
\\

Q4: 如何调试技能?

问题现象:
技能执行出错,但不知道具体原因。

解决方案:

使用调试模式运行技能:

\\ash

启用详细日志

openclaw --verbose skill test my-skill

进入调试模式

openclaw skill debug my-skill
\\

在代码中添加日志:

\\ ypescript
export async function myTool() {
logger.debug(‘开始执行 myTool’);
logger.info(‘参数:’, { … });
logger.error(‘发生错误:’, error);
}
\\

查看日志:

\\ash
tail -f ~/.openclaw/logs/skills.log
\\

Q5: 如何处理不同操作系统的兼容性?

问题现象:
技能在 macOS 上正常,但在 Windows 或 Linux 上失败。

解决方案:

在 SKILL.md 中声明支持的操作系统:

\\yaml
requires:
os:
- darwin # macOS
- linux # Linux
- win32 # Windows
\\

在代码中处理平台差异:

\\ ypescript
const isWindows = process.platform === ‘win32’;
const command = isWindows ? ‘dir’ : ‘ls’;
\\

提供平台特定的脚本:

\
scripts/
├── setup.sh # Unix-like 系统
└── setup.bat # Windows 系统
\\

Q6: 如何保护敏感信息?

问题现象:
技能需要访问 API 密钥等敏感信息,但不希望硬编码在代码中。

解决方案:

使用环境变量存储敏感信息:

\\yaml
requires:
env:
- API_KEY
\\

在代码中访问:

\\ ypescript
const apiKey = process.env.API_KEY;
if (!apiKey) {
throw new Error(‘请设置 API_KEY 环境变量’);
}
\\

使用 .env 文件管理环境变量:

\\ash

.env

API_KEY=your_secret_key_here
DATABASE_URL=postgresql://localhost/mydb
\\

高级开发技巧

1. 条件性工具注册

根据运行环境动态注册不同的工具:

\\ ypescript
// 只在特定条件下注册工具
if (config.get(‘enable_advanced_features’)) {
skill.registerTool(‘advanced-analysis’, analyzeData);
}

if (hasGitInstalled()) {
skill.registerTool(‘git-operations’, gitOps);
}
\\

2. 资源清理

在技能卸载时清理资源:

\\ ypescript
skill.onUnload(() => {
// 关闭数据库连接
db.close();

// 清理临时文件
fs.rmSync(tempDir, { recursive: true });

// 取消定时器
clearInterval(timer);
});
\\

3. 性能优化

使用缓存提升性能:

\\ ypescript
const cache = new Map();

export async function search(query: string) {
// 检查缓存
if (cache.has(query)) {
return cache.get(query);
}

// 执行搜索
const result = await performSearch(query);

// 存入缓存(有效期5分钟)
cache.set(query, result);
setTimeout(() => cache.delete(query), 5 * 60 * 1000);

return result;
}
\\

4. 批量操作

支持批量操作提升效率:

\\ ypescript
export async function batchCreate(items: Item[]) {
const results = [];

for (const item of items) {
try {
const result = await create(item);
results.push({ success: true, result });
} catch (error) {
results.push({ success: false, error: error.message });
}
}

return results;
}
\\

Skills 系统架构深度解析

核心组件

OpenClaw Skills 系统由以下几个核心组件构成:

1. Skill Registry(技能注册中心)

负责管理所有已加载的技能,提供技能的注册、查询、卸载等功能。采用单例模式,确保全局只有一个注册中心实例。

2. Skill Loader(技能加载器)

负责从文件系统加载技能,解析 SKILL.md 文件,验证依赖,初始化技能实例。支持多种加载源:本地文件、Git 仓库、ChatHub 市场。

3. Dependency Resolver(依赖解析器)

分析技能的依赖关系,检查环境变量、二进制工具、操作系统兼容性等。如果依赖不满足,提供清晰的错误提示和解决建议。

4. Hot Reload Manager(热重载管理器)

监听 SKILL.md 文件的变化,自动重新加载技能。使用文件系统监听 API,在检测到变化时触发重载流程。

5. Configuration Manager(配置管理器)

管理技能的配置参数,支持多层级配置合并、参数验证、默认值处理等。使用 JSON Schema 进行配置验证。

工作流程

\
用户请求 → AI 分析意图 → 匹配 Skills → 检查依赖
↓
激活 Skills → 加载配置 → 执行工具 → 返回结果
↓
日志记录 → 清理资源 → 等待下次请求
\\

安全机制

Skills 系统实现了多层安全机制:

权限隔离:每个技能在独立的权限上下文中运行
资源限制:限制技能的 CPU、内存、文件访问
代码签名:验证技能包的数字签名
沙箱执行:在沙箱环境中执行不受信任的代码
审计日志:记录所有技能操作,便于追踪和审计

性能优化

Skills 系统采用了多种性能优化策略:

懒加载:只有在首次使用时才加载技能
缓存机制:缓存解析后的 SKILL.md 和配置
并行加载:并行加载独立的技能
增量更新:只更新变化的部分,避免完全重载

Skills 生态与社区

ChatHub 技能市场

ChatHub 是 OpenClaw 官方的技能市场,提供:

经过验证的高质量技能
详细的技能文档和评分
版本管理和更新通知
社区讨论和问题反馈

贡献指南

欢迎为 OpenClaw Skills 生态贡献:

提交新技能到 ChatHub
改进现有技能的功能
编写技能文档和教程
回答社区问题
报告和修复 Bug

技能质量标准

发布到 ChatHub 的技能需要满足:

完整的 SKILL.md 文档
充分的测试覆盖
清晰的 README 说明
使用示例和截图
遵循编码规范

未来展望

Skills 系统的未来发展方向:

AI 辅助开发:自动生成 SKILL.md 和工具代码
可视化编辑器:图形化界面编辑技能配置
技能组合:支持多个技能的动态组合
跨平台支持:更好的 Windows/Linux/macOS 兼容性
性能监控:实时监控技能性能指标

附录:Skills 开发检查清单

开发完成后,请确保:

SKILL.md 文件格式正确
Description 清晰描述使用场景
Instructions 提供详细使用指南
Dependencies 正确声明所有依赖
Configuration 使用 JSON Schema 验证
提供使用示例和文档
编写充分的测试用例
处理所有可能的错误情况
日志记录完整清晰
性能满足要求
在多个平台测试通过
README 文档完整

术语表

Skill: OpenClaw 中的能力模块,封装一组相关功能
SKILL.md: 技能的定义文件,使用 YAML Front Matter + Markdown 格式
Tool: 技能暴露的具体操作接口
ChatHub: OpenClaw 官方的技能市场
Front Matter: SKILL.md 文件开头的 YAML 配置块
Dependency: 技能运行所需的外部条件
Hot Reload: 修改文件后自动重新加载的机制
JSON Schema: 用于定义和验证 JSON 数据结构的规范
SemVer: 语义化版本规范,格式为 MAJOR.MINOR.PATCH

致谢

感谢 OpenClaw 社区的所有贡献者,是你们的努力让 Skills 系统变得更加完善。特别感谢:

OpenClaw 核心开发团队
ChatHub 技能审核团队
社区贡献者和测试人员
文档翻译和校对志愿者

版本历史

v2.0.0 (2024): 新增热重载、条件执行等高级特性
v1.5.0 (2023): 改进依赖管理和错误处理
v1.0.0 (2022): Skills 系统首次发布

本文版权归 OpenClaw 团队所有,遵循 Apache 2.0 许可证。

Skills 开发进阶主题

1. 多语言支持

Skills 可以支持多种编程语言的实现:

TypeScript 实现:

\\ ypescript
// 使用 TypeScript 的优势:
// - 类型安全
// - IDE 支持更好
// - 代码更易维护

interface ProjectOptions {
description?: string;
template?: string;
team?: string[];
}

export async function projectCreate(
name: string,
options?: ProjectOptions
): Promise {
// TypeScript 会自动检查类型
const project: Project = {
id: generateId(),
name,
created_at: new Date().toISOString(),
status: ‘active’
};

return project;
}
\\

Python 实现:

\\python

使用 Python 的优势:

- 丰富的第三方库

- 简洁的语法

- 适合数据处理

import json
from datetime import datetime

def project_create(name: str, options: dict = None) -> dict:
if not name:
raise ValueError(‘项目名称不能为空’)

project = {
    'id': generate_id(),
    'name': name,
    'created_at': datetime.now().isoformat(),
    'status': 'active'
}

if options:
    project.update(options)

return project

2. 插件系统集成

Skills 可以与 OpenClaw 插件系统深度集成:

\\ ypescript
// 在插件中注册技能
export class MyPlugin {
onActivate() {
// 注册插件专属技能
this.registerSkill(‘plugin-skill’, {
path: ‘./skills/plugin-skill/’,
priority: ‘plugin’
});
}

onDeactivate() {
// 清理插件技能
this.unregisterSkill(‘plugin-skill’);
}
}
\\

3. 与 MCP 协议集成

Skills 可以通过 MCP (Model Context Protocol) 与外部工具通信:

\\ ypescript
// 通过 MCP 调用外部服务
export async function callExternalAPI(params: any) {
const mcpClient = skill.getMCPClient();

const response = await mcpClient.call({
tool: ‘external-api’,
params: params
});

return response;
}
\\

4. 状态管理

Skills 可以维护内部状态:

\\ ypescript
// 使用状态管理器
class SkillState {
private state: Map<string, any> = new Map();

set(key: string, value: any) {
this.state.set(key, value);
// 自动持久化
this.persist();
}

get(key: string): any {
return this.state.get(key);
}

persist() {
// 将状态保存到文件
const data = JSON.stringify([…this.state]);
fs.writeFileSync(‘state.json’, data);
}
}
\\

5. 事件系统

Skills 可以发布和订阅事件:

\\ ypescript
// 发布事件
skill.emit(‘project-created’, { projectId: ‘123’ });

// 订阅事件
skill.on(‘task-completed’, (data) => {
console.log(‘任务完成:’, data);
});

// 订阅其他技能的事件
skill.subscribe(‘notification-system’, ‘message-received’, (data) => {
// 处理来自其他技能的消息
});
\\

6. 流式处理

支持流式数据处理:

\\ ypescript
export async function* streamData(query: string) {
const results = await searchLargeDataset(query);

for (const item of results) {
// 流式返回结果
yield item;
}
}
\\

7. 权限控制

实现细粒度的权限控制:

\\ ypescript
// 定义权限策略
const permissions = {
‘project.read’: [‘admin’, ‘member’, ‘viewer’],
‘project.write’: [‘admin’, ‘member’],
‘project.delete’: [‘admin’]
};

// 检查权限
function checkPermission(action: string, user: User): boolean {
const allowedRoles = permissions[action];
return allowedRoles.includes(user.role);
}
\\

8. 国际化支持

支持多语言界面:

\\ ypescript
const i18n = {
en: {
‘project.create’: ‘Create Project’,
‘task.add’: ‘Add Task’
},
zh: {
‘project.create’: ‘创建项目’,
‘task.add’: ‘添加任务’
}
};

function getText(key: string, language: string = ‘en’): string {
return i18n[language]?.[key] || i18n[‘en’][key];
}
\\

Skills 开发最佳实践总结

文档编写建议

Description 要具体:避免模糊的描述,明确说明使用场景
Instructions 要详细:提供完整的参数说明和返回值示例
Examples 要实用:展示真实的使用场景,避免过于简单的示例
更新要及时:技能更新后,及时更新文档说明

代码编写建议

模块化设计:将复杂功能拆分成小的模块
错误处理:处理所有可能的异常情况
日志记录:添加充分的日志,便于调试
性能考虑:注意内存和 CPU 使用,避免阻塞
测试覆盖:编写单元测试和集成测试

配置管理建议

合理默认值:设置用户最常用的默认配置
参数验证:使用 JSON Schema 严格验证配置
配置文档:为每个配置参数提供说明
向后兼容:新版本要兼容旧版本的配置

安全实践建议

不要硬编码密钥:使用环境变量存储敏感信息
限制文件访问:只访问必需的文件和目录
验证用户输入:防止注入攻击
权限最小化:只申请必需的权限

本文已完成,涵盖了 OpenClaw Skills 技能系统的所有核心内容。

总结

OpenClaw Skills 技能系统是一个强大而灵活的能力扩展框架,为 AI 智能体赋予了无限可能。通过本指南的学习,您已经掌握了:

核心概念:理解 Skills 与 Tools 的区别,掌握 SKILL.md 的结构
开发技能:能够独立开发、测试、发布技能
高级特性:熟练运用热重载、条件执行、参数校验等功能
最佳实践:遵循开发规范,编写高质量的技能

Skills 系统的设计理念——声明式定义、分层加载、热重载、安全隔离——代表了 AI 智能体框架的未来发展方向。我们相信,随着越来越多的开发者加入 OpenClaw 生态,Skills 将成为构建 AI 应用的标准方式。

下一步行动:

动手实践:创建您的第一个 Skill
深入学习:研究 ChatHub 上的优秀技能
参与社区:分享您的经验,帮助其他开发者
贡献代码:为 OpenClaw 项目贡献力量

感谢您的阅读!祝您在 OpenClaw Skills 开发之路上一切顺利!

全文完

AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

从Anthropic官方文档看Claude的安全机制：隔离、模型与外部内容的三层防御体系

十二个月前，如果有人提议让Claude拥有足以搞垮Anthropic内部服务的权限，我们一定会断然拒绝。而今天，这种访问级别已经成为常态，Anthropic内部的开发者们正因为这种部署而大幅提升了生产力。这是我读完Anthropic官方工程博客《How we contain Claude across products》（2026年5月25日发布）后的第一感受。当AI Agent的能力越强大，它的