05-OpenClaw-Skills技能开发指南

作者：安逸 i
OpenClaw Skills 技能开发指南

免费专栏全套教程：OpenClaw从入门到精通
OpenClaw 通过 Skills（技能）系统实现功能扩展，让 AI 助手能够学习和使用各种工具。本指南将深入讲解 Skill 的概念、结构、开发流程和最佳实践。
目录

Skill 是什么、作用SKILL.md 文件结构技能目录结构开发自定义技能技能最佳实践示例技能讲解

---

1. Skill 是什么、作用

1.1 什么是 Skill？

Skill 是 OpenClaw 的核心扩展机制，它是一个包含 SKILL.md 文件的目录。SKILL.md 文件使用 YAML frontmatter 定义元数据，使用 Markdown 编写指令，教会 LLM 如何使用特定工具或完成特定任务。
可以理解为：Skill 是给 AI 助手的"技能说明书"，告诉它：

什么时候该使用这个技能如何使用相关工具有哪些注意事项和最佳实践

1.2 Skill 的作用

1. ┌─────────────────────────────────────────────────────────────┐
2. │                      OpenClaw Agent                          │
3. ├─────────────────────────────────────────────────────────────┤
4. │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐         │
5. │  │ weather │  │ github  │  │ notion  │  │ coding  │  ...    │
6. │  │ Skill   │  │ Skill   │  │ Skill   │  │ agent   │         │
7. │  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘         │
8. │       │            │            │            │               │
9. │       v            v            v            v               │
10. │  ┌─────────────────────────────────────────────────┐        │
11. │  │              Tools (bash, browser, etc.)         │        │
12. │  └─────────────────────────────────────────────────┘        │
13. └─────────────────────────────────────────────────────────────┘

复制代码

核心作用：

功能	说明
工具教学	指导 LLM 如何使用命令行工具（如 gh、curl、sag）
工作流封装	封装复杂的多步骤操作流程
上下文注入	在系统提示词中注入特定领域的知识和指令
门控控制	根据环境、配置自动启用或禁用特定功能
跨平台适配	根据操作系统或可用二进制文件动态加载

1.3 Skill 加载位置与优先级

OpenClaw 从三个位置加载 Skills：

1. 优先级（从高到低）：
3. 1. <workspace>/skills/     ← 工作区技能（最高优先级，用户自定义）
4.        ↓
5. 2. ~/.openclaw/skills/     ← 托管/本地技能（所有 Agent 共享）
6.        ↓
7. 3. 内置技能（npm 包或 OpenClaw.app 附带）

复制代码

示例： 如果在三个位置都有名为 weather 的技能，工作区版本将覆盖其他版本。

---

2. SKILL.md 文件结构

2.1 基本结构

1. ---
2. name: skill-name
3. description: "简短描述技能的功能和用途"
4. homepage: https://example.com
5. metadata: { "openclaw": { ... } }
6. ---
8. # Skill 标题
10. 这里是 Markdown 格式的详细指令...

复制代码

2.2 YAML Frontmatter 字段详解

必需字段

字段	类型	说明
name	string	技能的唯一标识符，用于配置和引用
description	string	简短描述，用于系统提示词中向 LLM 介绍技能

可选字段

字段	类型	说明
homepage	string	技能主页 URL，在 macOS Skills UI 中显示为"网站"
user-invocable	boolean	是否作为用户斜杠命令暴露（默认 true）
disable-model-invocation	boolean	是否从模型提示词中排除（默认 false）
command-dispatch	string	设为 tool 时，斜杠命令直接调度到工具
command-tool	string	当 command-dispatch: tool 时要调用的工具名称
command-arg-mode	string	参数模式，默认 raw
metadata	object	OpenClaw 特定配置（JSON 格式）

2.3 metadata.openclaw 配置详解

metadata 字段是一个单行 JSON 对象，包含 OpenClaw 特定的配置：

1. ---
2. name: gemini
3. description: Use Gemini CLI for coding assistance and Google search lookups.
4. metadata:
5.   {
6.     "openclaw":
7.       {
8.         "emoji": "♊️",
9.         "os": ["darwin", "linux"],
10.         "requires": { "bins": ["gemini"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
11.         "primaryEnv": "GEMINI_API_KEY",
12.         "install":
13.           [
14.             {
15.               "id": "brew",
16.               "kind": "brew",
17.               "formula": "gemini-cli",
18.               "bins": ["gemini"],
19.               "label": "Install Gemini CLI (brew)",
20.             },
21.           ],
22.       },
23.   }
24. ---

复制代码

metadata.openclaw 字段说明

字段	类型	说明
always	boolean	设为 true 时始终包含该技能，跳过其他门控检查
emoji	string	macOS Skills UI 使用的表情符号
homepage	string	覆盖顶层 homepage
os	string[]	平台限制：darwin、linux、win32
requires.bins	string[]	必须存在于 PATH 的二进制文件列表
requires.anyBins	string[]	至少一个必须存在于 PATH
requires.env	string[]	必须存在的环境变量（或在配置中提供）
requires.config	string[]	openclaw.json 中必须为真值的路径
primaryEnv	string	与 apiKey 配置关联的环境变量名
install	object[]	安装器规格数组（用于 macOS Skills UI）

2.4 完整 Frontmatter 示例

最简示例：

1. ---
2. name: hello_world
3. description: A simple skill that says hello.
4. ---
6. # Hello World Skill
8. When the user asks for a greeting, use the `echo` tool to say "Hello!".

复制代码

完整配置示例：
[code]---
name: summarize
description: Summarize or extract text/transcripts from URLs, podcasts, and local files.
homepage: https://summarize.sh
metadata:
  {
    "openclaw":
      {
        "emoji": "