OpenClaw Skill 开发指南：从零开始创建自定义技能

OpenClaw 是一个强大的 AI Agent 平台，通过**Skill（技能）**机制，你可以为 AI 扩展各种专业能力。本文将详细介绍如何从零开始创建自己的 Skill，让你的 AI 助手更加智能和个性化。

什么是 Skill？

Skill 是 OpenClaw 的模块化扩展单元，可以理解为 AI 的"专业工具包"。每个 Skill 包含：

• SKILL.md - 技能的核心定义文件，包含触发条件和使用说明
• scripts/ - 可执行脚本（Python、Bash 等）
• references/ - 参考资料和文档
• assets/ - 模板、图片等资源文件

通过 Skill，你可以让 AI 掌握特定领域的知识、执行特定的工作流程，甚至调用外部 API。

Skill 的核心设计原则

1. 简洁至上

上下文窗口是有限的公共资源。Skill 需要与系统提示词、对话历史、其他 Skill 共享上下文空间。

核心原则：Claude 本身已经很聪明，只添加它不知道的信息。对每个信息都要质疑："Claude 真的需要这个解释吗？"

2. 适当的自由度

根据任务的复杂程度和变化性，设置不同的自由度：

3. 渐进式披露

Skill 使用三级加载系统管理上下文：

1. Metadata（name + description） - 始终在上下文中（约100词）
2. SKILL.md body - 技能触发时加载（<5k词）
3. Bundled resources - 按需加载（无限制，因为脚本可以不在上下文中执行）

Skill 的文件结构

skill-name/
├── SKILL.md              # 必需：技能定义和使用说明
├── scripts/              # 可选：可执行脚本
│   └── example.py
├── references/           # 可选：参考资料
│   └── guide.md
└── assets/               # 可选：资源文件
    └── template.docx

SKILL.md 的结构

---
name: skill-name
description: "技能的详细描述。说明技能做什么，以及何时使用它。包含所有触发条件信息。"
---

# 技能标题

## 使用场景

说明何时使用此技能。

## 工作流程

详细的使用步骤和示例。

## 命令参考

可用的命令和参数说明。

关键要点：

• description 是最重要的触发机制，必须清晰描述技能的功能和使用场景
• 不要在正文中写"何时使用此技能"，因为正文只在触发后加载
• 保持 SKILL.md 简洁，详细内容放到 references/ 中

创建 Skill 的完整流程

步骤1：明确技能用途

首先想清楚：

• 这个技能要解决什么问题？
• 用户会怎么描述需求？
• 需要哪些工具或资源？

步骤2：规划资源

分析每个使用场景，确定需要：

• scripts/ - 哪些代码需要复用？
• references/ - 哪些文档需要参考？
• assets/ - 哪些模板或资源需要准备？

步骤3：初始化技能

使用官方脚本创建技能骨架：

# macOS/Linux
scripts/init_skill.py my-skill --path ~/.qclaw/skills

# Windows
python scripts\init_skill.py my-skill --path %USERPROFILE%\.qclaw\skills

重要：

• 必须使用 --path ~/.qclaw/skills，这样技能才能在应用更新后保留
• 不要在应用内置目录创建技能，更新时会被删除

步骤4：编写 SKILL.md

Frontmatter（YAML 头部）

---
name: my-skill
description: "一句话描述技能功能。使用场景包括：(1) 场景一，(2) 场景二，(3) 场景三。"
---

正文内容

• 快速开始指南
• 详细工作流程
• 命令和参数说明
• 示例

步骤5：添加资源文件

根据需要添加脚本、参考资料或资源文件。

步骤6：打包技能

scripts/package_skill.py ~/.qclaw/skills/my-skill

这会生成 my-skill.skill 文件，可以分享给他人使用。

实战示例：创建一个天气查询 Skill

1. 初始化技能

scripts/init_skill.py weather-query --path ~/.qclaw/skills

2. 编写 SKILL.md

---
name: weather-query
description: "查询指定城市的实时天气和未来7天预报。使用场景包括：(1) 用户询问某城市天气，(2) 需要获取温度、湿度、风速等详细信息，(3) 需要未来几天的天气预报。"
---

# 天气查询

## 快速开始

使用 wttr.in 服务查询天气，无需 API Key。

## 查询命令

```bash
# 当前天气
curl -s "wttr.in/城市名?format=3"

# 详细天气
curl -s "wttr.in/城市名"

# JSON 格式
curl -s "wttr.in/城市名?format=j1"

输出格式

• format=3：简洁格式（城市: 温度, 天气）
• format=4：仅温度和天气图标
• format=j1：完整 JSON 数据

### 3. 打包分享

```bash
scripts/package_skill.py ~/.qclaw/skills/weather-query

进阶技巧

1. 多领域组织

对于复杂的技能，可以按领域组织 references：

my-skill/
├── SKILL.md
└── references/
    ├── finance.md      # 财务相关
    ├── sales.md        # 销售相关
    └── product.md      # 产品相关

当用户询问销售指标时，Claude 只加载 sales.md。

2. 条件加载

在 SKILL.md 中使用条件引用：

## 基础用法

[基础说明...]

**高级功能**：
- **表单处理**：参见 [FORMS.md](references/FORMS.md)
- **API 参考**：参见 [REFERENCE.md](references/REFERENCE.md)

3. 脚本最佳实践

• 脚本应该独立可运行
• 提供清晰的错误信息
• 使用标准输入输出
• 支持 --help 参数

常见陷阱

总结

创建 Skill 的核心要点：

1. 明确用途 - 清楚定义技能解决的问题
2. 精简描述 - description 是触发关键，要详尽但简洁
3. 合理组织 - 使用渐进式披露管理上下文
4. 正确位置 - 只在 ~/.qclaw/skills 创建技能
5. 充分测试 - 确保脚本和流程都能正常工作

Skill 让 OpenClaw 从通用助手变成专业工具。无论是处理 PDF、生成文档、查询数据，还是自动化工作流程，都可以通过 Skill 实现。开始创建你的第一个 Skill 吧！

参考资源

• OpenClaw 官方文档
• Skill 示例仓库
• Skill 设计模式