OpenClaw Skills 完全指南:从入门到精通

本文将带你由浅入深地了解 OpenClaw Skills —— 这个让 AI Agent 从"通用助手"进化为"专业专家"的强大机制。

什么是 Skill？

Skill（技能）是 OpenClaw 中用于扩展 AI Agent 能力的模块化知识包。

简单来说，Skills 就是给 AI 的"专业培训手册"。它们将特定领域的知识、工作流程和工具封装成可复用的模块，让 AI 能够在特定场景下表现得像专家一样。

类比理解

类比	解释
游戏技能书	就像 RPG 游戏中的技能书，学习后获得新能力
员工手册	新员工的入职培训资料，包含公司特定的流程和规范
工具箱	针对特定任务的专业工具集合

一个实际的 Skill 例子

比如 ddg-search-fetch 这个 Skill：

---
name:duckduckgo-search
description:SearchthewebandfetchURLcontentusingDuckDuckGo.
Usewhentheuserwantstosearchforinformationonlinewithout
requiringAPIkeysorpaidservices...
---

它让 AI 能够：

• 使用 DuckDuckGo 搜索网页
• 抓取指定 URL 的内容
• 无需 API Key，完全免费

为什么需要 Skills？

1. 弥补模型的知识缺口

AI 模型虽然强大，但它不知道：

• 你公司的内部 API 规范
• 你项目的特定架构模式
• 某个小众工具的使用方法

Skills 填补了这个空白。

2. 确保一致性和可靠性

没有 Skills 时，每次处理相似任务，AI 可能采用不同的方法。Skills 提供了标准化的流程，确保每次执行都是一致和可靠的。

3. 节省上下文窗口

Skills 采用渐进式披露设计：

1. 元数据（name + description）— 始终加载（~100 词）
2. SKILL.md 正文 — 触发时加载（<5k 词）
3. 资源文件 — 按需加载（无限制）

这样避免了每次对话都加载大量无关信息。

4. 可复用和共享

写好的 Skill 可以：

• 在多个项目中复用
• 分享给团队成员
• 发布到 ClawHub 供社区使用

Skill 的基本结构

一个标准的 Skill 目录结构如下：

skill-name/
├── SKILL.md              # 必需：核心文档
├── _meta.json            # 自动生成：元数据
├── .clawhub/             # ClawHub 相关配置
├── scripts/              # 可选：可执行脚本
│   ├── ddg_search.py
│   └── ddg_fetch.py
├── references/           # 可选：参考文档
│   ├── api-docs.md
│   └── examples.md
└── assets/               # 可选：资源文件
    ├── templates/
    └── images/

SKILL.md 详解

SKILL.md 是 Skill 的核心，包含两部分：

1. YAML Frontmatter（头部元数据）

---
name:skill-name# Skill 名称（小写、连字符分隔）
description:Usewhen...# 触发条件描述（最关键！）
---

description 的重要性：

• 这是 AI 决定是否加载该 Skill 的唯一依据
• 必须以 "Use when..." 开头
• 描述触发条件，而非 Skill 的功能
• 最多 1024 字符

✅ 好的描述：

description:Usewhenimplementinganyfeatureorbugfix,
beforewritingimplementationcode

❌ 不好的描述：

description:ThisskillhelpswithTDD-writetestfirst,
watchitfail,writeminimalcode,refactor

2. Markdown 正文

正文包含：

• Overview：Skill 是什么，核心原则
• When to Use：使用场景和症状
• Core Pattern：核心模式/流程
• Quick Reference：速查表
• Implementation：实现细节
• Common Mistakes：常见错误

从零创建一个 Skill

让我们通过一个实际例子来学习。假设我们要创建一个天气查询 Skill。

Step 1: 理解需求

首先明确 Skill 要解决的问题：

• 用户想查询某个城市的天气
• 不需要 API Key
• 支持当前天气和预报

Step 2: 规划资源

分析需要什么：

• 一个调用天气 API 的脚本
• 使用说明文档

Step 3: 初始化 Skill

# 使用 OpenClaw 提供的初始化脚本
clawhub init weather-query --path skills/

这会生成：

skills/weather-query/
├── SKILL.md
└── .clawhub/

Step 4: 编写 SKILL.md

---
name: weather-query
description: Get current weather and forecasts for any location. 
  Use when the user asks about weather, temperature, or forecasts 
  for any location. Triggers on phrases like "weather", "temperature", 
  "forecast", "will it rain".
---

# Weather Query

Get weather information using wttr.in or Open-Meteo (no API key needed).

## Quick Start

```bash
# Current weather
python3 scripts/weather.py "Beijing"

# Forecast
python3 scripts/weather.py "Shanghai" --forecast

# Specific format
python3 scripts/weather.py "Tokyo" --format json

Options

Flag	Description	Default
`--forecast`	Get 3-day forecast	false
`--format`	Output format: text, json	text

Output Example

{
"location":"Beijing",
"temperature":"15°C",
"condition":"Sunny",
"humidity":"45%"
}


### Step 5: 添加脚本

创建 `scripts/weather.py`：

```python
#!/usr/bin/env python3
import argparse
import urllib.request
import json

def get_weather(location, forecast=False):
    # 使用 wttr.in API
    url = f"https://wttr.in/{location}?format=j1"

    req = urllib.request.Request(url)
    with urllib.request.urlopen(req) as response:
        data = json.loads(response.read().decode())

    return data

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("location")
    parser.add_argument("--forecast", action="store_true")
    args = parser.parse_args()

    result = get_weather(args.location, args.forecast)
    print(json.dumps(result, indent=2))

Step 6: 测试

python3 skills/weather-query/scripts/weather.py "Beijing"

Step 7: 发布

clawhub publish skills/weather-query

进阶：Skill 的设计哲学

1. TDD for Skills

创建 Skills 也要遵循测试驱动开发：

TDD 概念	Skill 创建对应
测试用例	压力场景 + Subagent
生产代码	Skill 文档
测试失败	Agent 违反规则
测试通过	Agent 遵守规则
重构	堵住漏洞

铁律：没有失败的测试，就不要写 Skill。

2. 渐进式披露

用户提问
    ↓
[元数据匹配] → name + description（始终加载）
    ↓
[触发 Skill] → 加载 SKILL.md 正文
    ↓
[需要时] → 加载 references/ 或执行 scripts/

3. 自由度控制

根据任务的脆弱性调整指导的严格程度：

• 高自由度：文本说明，适用于多种方法都有效的场景
• 中自由度：伪代码或带参数的脚本
• 低自由度：特定脚本，适用于易错、需要严格顺序的任务

4. Claude Search Optimization (CSO)

让未来的 AI 能够找到你的 Skill：

• 关键词覆盖：包含错误信息、症状、工具名
• 描述性命名：使用动词开头，如 creating-skills
• Token 效率：getting-started < 150 词，其他 < 500 词

发布与分享你的 Skill

发布到 ClawHub

# 登录
clawhub login

# 发布
clawhub publish skills/my-skill

# 更新
clawhub update my-skill

安装他人的 Skill

# 搜索
clawhub search weather

# 安装
clawhub install weather-query

# 列出已安装
clawhub list

Skill 安全审查

安装前建议审查：

# 查看 Skill 信息
clawhub inspect skill-name

# 临时安装检查
clawhub install skill-name --dir /tmp/test

inspect 检查清单：

• curl/wget 到未知 URL
• 发送数据到外部服务器
• 请求凭证/令牌
• 读取 ~/.ssh, ~/.aws 等敏感目录
• 使用 eval() 或 exec()
• 混淆/压缩的代码

最佳实践与常见陷阱

✅ 最佳实践

1. 从具体例子开始

• 不要抽象地设计 Skill
• 先收集 3-5 个实际使用场景

2. 保持简洁

• 默认假设：AI 已经很聪明了
• 只添加 AI 不知道的信息
• 一个优秀的例子胜过五个普通的

3. 正确的描述写法

• 以 "Use when..." 开头
• 描述触发条件，而非功能
• 包含具体症状和场景

4. 渐进式披露

• SKILL.md < 500 行
• 大段参考内容放到 references/
• 可执行代码放到 scripts/

5. 交叉引用

• 使用 superpowers:skill-name 引用其他 Skill
• 不要用 @ 强制加载

❌ 常见陷阱

陷阱	后果	解决
描述 summarises workflow	AI 跳过正文，直接按描述执行	只写触发条件
多语言示例	质量稀释，维护负担	一种语言，一个优秀示例
代码放在流程图	无法复制粘贴	用 Markdown 代码块
深度嵌套引用	难以发现	保持引用一层深度
重复信息	上下文膨胀	SKILL.md 或 references/，不要同时

结语

Skills 是 OpenClaw 生态系统的核心。它们让 AI Agent 能够：

• 学习专业知识 — 从通用到专业
• 保持一致性 — 标准化工作流程
• 高效协作 — 团队共享最佳实践
• 持续进化 — 社区共同完善

记住 Skill 创建的铁律：

没有失败的测试，就不要写 Skill。
No skill without a failing test first.

现在，去创建你的第一个 Skill 吧！🚀

参考资源

• OpenClaw 官方文档
• ClawHub Skill 仓库