OpenClaw Skill 保姆级教程：基于 AgentSkills 规范与 YAML 配置

你是否希望自己的 AI 助手能完成更多定制化任务？比如让它自动整理文件、调用某个特定的 API，或者生成图片？实现这些功能的核心，就是为 OpenClaw 制作专属的 Skill。

OpenClaw 强大的 Skill 系统基于 AgentSkills 规范，支持你自定义工具、构建自动化流程，甚至是设计复杂的 AI 工作流。今天，我们将深入 云栈社区 开发者们的实践，为你提供一份手把手的 OpenClaw Skill 制作指南。

什么是 OpenClaw Skill？

简单来说，Skill 就是一份告诉 AI 如何使用工具的详细“说明书”。当你为 AI 加载一个 Skill，它就获得了新的认知：有哪些工具可用？这些工具能干什么？以及如何正确调用它们？

OpenClaw 的 Skill 系统具备以下显著特点：

• 基于标准：遵循 AgentSkills 规范，意味着你编写的 Skill 具有良好的可移植性，可在其他支持该规范的平台上复用。
• 配置灵活：支持定义丰富的工具参数、返回值、使用条件乃至环境依赖。
• 层级加载：采用多层加载机制，允许你的自定义 Skill 覆盖官方内置的同名 Skill，实现高度定制化。

Skill 的存放位置与优先级

OpenClaw 会从三个位置加载 Skill，优先级从高到低依次为：

1. 工作区 Skill：存放在当前工作目录的 skills 子目录下，仅对当前工作区生效。
2. 本地 Skill：存放在 ~/.openclaw/skills 目录下，对本机所有 Agent 都可用。
3. 内置 Skill：随 OpenClaw 安装包自带，是官方的核心技能。

这个优先级机制非常实用：你完全可以创建一个与内置 Skill 同名的自定义版本，放在工作区或本地目录，OpenClaw 会自动优先加载你的版本，从而实现功能覆盖或增强。

Skill 的基本结构

一个 Skill 本质上就是一个文件夹，其内部至少需要包含一个核心定义文件 SKILL.md。此外，你还可以在文件夹内放置脚本、配置文件、示例等辅助资源。

例如，一个名为 my-first-skill 的 Skill 可能具有如下结构：

my-first-skill/
├── SKILL.md          # 核心技能定义文件
├── scripts/          # 存放可执行脚本
│   └── handler.py
└── examples/         # 存放使用示例
    └── demo.md

核心：SKILL.md 文件格式详解

SKILL.md 是 Skill 的灵魂。它采用“YAML frontmatter + Markdown 正文”的格式。前半部分的 YAML 用于定义元信息，后半部分的 Markdown 用于详细描述工具和使用方法。掌握正确的 技术文档 书写规范，能让你的 Skill 更易被 AI 理解。

1. 最简 frontmatter 示例

文件以三个短横线 --- 开始和结束，中间定义最基本的元数据：

---
name: hello-world
description: 一个简单的 Hello World 技能
---

后续可以接着编写详细的使用说明文档。

2. 完整的 frontmatter 配置

除了 name 和 description，你可以在 metadata 字段中设置复杂的加载条件，让 Skill 更智能。例如：

---
name: image-generator
description: 使用 AI 生成图片
metadata: {"openclaw": {"requires": {"bins": ["python3"], "env": ["API_KEY"]}, "emoji": "🖼️"}}
---

这个配置表示：image-generator 技能需要系统已安装 python3 命令，并设置了 API_KEY 环境变量才会被加载。emoji 字段则指定了该技能在界面中显示的图标。

如何清晰地定义工具？

Skill 的核心价值在于“教会” AI 使用工具。你需要在 SKILL.md 的正文部分，用清晰的结构描述每个工具。

工具描述的四个要点

1. 功能说明：一句话讲清楚这个工具是干什么的。
2. 参数列表：详细列出每个参数的名称、类型、是否必填、默认值和简短描述。
3. 返回值说明：明确告知 AI 调用后会得到什么格式的结果。
4. 调用示例：提供典型的调用示例，这是帮助 AI 理解和模仿的关键。

下面是一个定义 generate_image 工具的完整示例：

## 工具：generate_image

根据文本描述生成图片。

### 参数

- **prompt**: string, 必填
  要生成图片的描述文本

- **size**: string, 可选，默认 `"1024x1024"`
  图片尺寸，支持 `1024x1024`, `512x512`, `256x256`

- **style**: string, 可选，默认 `"natural"`
  图片风格，支持 `natural`, `vivid`, `anime`

### 返回值

返回一个图片 URL 字符串。

### 示例

用户说“帮我画一只可爱的猫”，AI 应该调用：

```python
generate_image(prompt="一只可爱的橘猫，大眼睛，卡通风格", size="1024x1024", style="vivid")
```

进阶：使用条件加载让 Skill 更智能

OpenClaw 支持在 metadata 中设置多种条件，让 Skill 只在满足特定环境时才被加载，避免错误。

1. 操作系统限制

metadata: {"openclaw": {"os": ["darwin", "linux"]}}

此技能仅在 macOS 和 Linux 系统上加载。

2. 依赖工具检查

metadata: {"openclaw": {"requires": {"bins": ["python3", "pip"]}}}

此技能需要系统已安装 python3 和 pip 命令。

3. 环境变量检查

metadata: {"openclaw": {"requires": {"env": ["OPENAI_API_KEY"]}}}

此技能需要 OPENAI_API_KEY 环境变量已设置。

4. 配置文件检查

metadata: {"openclaw": {"requires": {"config": ["browser.enabled"]}}}

此技能需要在 openclaw.json 配置文件中启用了 browser.enabled 选项。

你可以灵活组合上述条件，确保 Skill 在正确的上下文中工作。

实战演练：制作一个天气查询 Skill

让我们通过一个完整的例子来巩固所学：制作一个名为 weather-skill 的天气查询技能。

1. 创建文件夹结构

weather-skill/
├── SKILL.md
└── scripts/
    └── weather.py

2. 编写 SKILL.md 文件

---
name: weather
description: 查询指定城市的天气信息
metadata: {"openclaw": {"emoji": "🌤️", "requires": {"bins": ["curl"]}}}
---

## 工具：get_weather

获取指定城市的当前天气信息。

### 参数

- **city**: string, 必填
  城市名称，支持中英文，如“北京”、“New York”

- **format**: string, 可选，默认 `"celsius"`
  温度单位，`celsius` 表示摄氏度，`fahrenheit` 表示华氏度

### 返回值

返回格式化的天气信息字符串，例如：
`北京 today: 晴, 温度 15°C, 湿度 45%`

### 调用示例

用户问“北京今天天气怎么样”，AI 应该调用：
```python
get_weather(city="北京")
```

用户问“纽约的温度是多少（华氏度）”，AI 应该调用：
```python
get_weather(city="New York", format="fahrenheit")
```

### 注意事项

- 本技能依赖 `curl` 命令调用第三方天气 API。
- 如果 API 调用失败，将返回明确的错误信息。
- 支持中英文城市名称查询。

3. 编写工具脚本

在 scripts/weather.py 中，你可以使用 Python 编写具体的 API 调用和数据处理逻辑。这部分就是常规的编程工作，用于实现 SKILL.md 中描述的功能。

Skill 制作的最佳实践

1. 描述清晰准确：AI 的理解完全依赖于你的描述。务必明确参数类型、是否必填、返回值格式。
2. 提供丰富示例：示例是最佳的教学材料。为每个工具提供 1-2 个典型调用示例，能极大提升 AI 的使用正确率。
3. 预见边界情况：提前考虑网络超时、参数非法、API 返回错误等异常场景，并在文档中说明建议的处理方式。
4. 善用条件加载：通过 requires 条件确保 Skill 只在满足运行环境时才被激活，提升整体稳定性。
5. 保持功能单一：一个 Skill 最好只专注于一个核心功能或一组紧密相关的工具。功能过于复杂时，应考虑拆分为多个 Skill，便于维护和复用。

总结

OpenClaw 的 Skill 系统将 AI 从单纯的对话伙伴，转变为了能够执行具体任务的工作助手。通过制作自定义 Skill，你可以无限扩展 AI 的能力边界，实现工作流程自动化，并打造个性化的智能体验。

制作过程本身并不复杂，核心在于一份结构清晰的 SKILL.md 文件。从今天开始，尝试为你最常做的重复性工作创建一个 Skill，迈出 AI 赋能的第一步吧。