编写高质量 SKILL.md：最佳实践

开篇简介

SKILL.md 是 OpenClaw 技能的核心配置文件，决定了技能如何被理解、调用和执行。本文总结编写高质量 SKILL.md 的最佳实践，帮助你创建清晰、易用、健壮的技能。

---

SKILL.md 基础结构

标准模板

# Skill 名称

描述

一句话描述技能的核心功能。

触发条件

描述什么情况下应该使用这个技能。

参数

参数名 | 类型 | 必填 | 默认值 | 描述
|--------|------|------|--------|------|
param1 | string | 是 | - | 参数描述
param2 | number | 否 | 10 | 参数描述

执行步骤

第一步做什么
第二步做什么
...

输出格式

描述技能的输出内容和格式。

错误处理

描述可能的错误和应对方式。

示例

示例 1

输入：...
输出：...

示例 2

输入：...
输出：...

注意事项

注意点 1
注意点 2

相关文件

`script.js` - 主脚本
`config.json` - 配置文件

---

最佳实践

1. 清晰的技能名称

好的命名：

• `weather` - 天气查询
• `github-issues` - GitHub 问题管理
• `file-organizer` - 文件整理

避免的命名：

• `skill1` - 无意义
• `do-something` - 太模糊
• `super-awesome-skill` - 不专业

命名原则：

• 使用小写字母和连字符
• 名称反映核心功能
• 保持简洁（2-4 个词）

2. 精准的描述

好的描述：
> "查询指定城市的当前天气和未来 3 天预报"

避免的描述：
> "这是一个很有用的技能，可以帮你获取天气信息，非常好用"

描述原则：

• 一句话说明核心功能
• 包含关键信息（输入、输出）
• 避免营销语言

3. 明确的触发条件

好的触发条件：

## 触发条件

当用户询问以下内容时使用此技能：
某地的天气情况
未来几天的天气预报
是否适合出门（基于天气）

避免的触发条件：

## 触发条件

当用户需要天气信息时

触发条件原则：

• 列举具体场景
• 包含常见问法
• 说明边界情况

4. 完善的参数定义

好的参数定义：

## 参数

参数名 | 类型 | 必填 | 默认值 | 描述
|--------|------|------|--------|------|
location | string | 是 | - | 城市名称，支持中文和英文
days | number | 否 | 3 | 预报天数，范围 1-7
| unit | string | 否 | celsius | 温度单位：celsius 或 fahrenheit |

参数定义原则：

• 明确参数类型（string/number/boolean/array）
• 标注是否必填
• 提供默认值（可选参数）
• 详细描述参数含义和约束

5. 详细的执行步骤

好的执行步骤：

## 执行步骤

验证参数：检查 location 是否有效
调用 API：使用 wttr.in API 获取天气数据
解析数据：提取温度、湿度、风速等信息
格式化输出：生成易读的天气报告
返回结果：将结果返回给用户

执行步骤原则：

• 按顺序列出关键步骤
• 说明每步的目的
• 包含错误处理点

6. 清晰的输出格式

好的输出格式：

## 输出格式

📍 北京天气
当前：23°C，晴，湿度 45%
今天：23°C/15°C，晴转多云
明天：25°C/17°C，多云
后天：22°C/14°C，小雨

输出格式原则：

• 提供实际输出示例
• 说明格式元素含义
• 考虑不同场景的输出

7. 全面的错误处理

好的错误处理：

## 错误处理

错误情况 | 处理方式 | 用户提示
|---------|---------|---------|
城市不存在 | 返回错误 | "未找到城市'{location}'，请检查拼写"
API 超时 | 重试 2 次 | "天气服务暂时不可用，请稍后重试"
| 参数无效 | 拒绝执行 | "天数必须在 1-7 之间" |

错误处理原则：

• 列举可能的错误
• 说明处理逻辑
• 提供友好的用户提示

8. 丰富的示例

好的示例：

## 示例

示例 1：查询当前天气

输入：

北京天气怎么样？

输出：

📍 北京天气
当前：23°C，晴，湿度 45%

### 示例 2：查询多日预报

输入：

上海未来 5 天天气

输出：

📍 上海天气（5 天预报）
今天：28°C/22°C，多云
明天：30°C/24°C，晴
后天：29°C/23°C，晴转多云
...

### 示例 3：带参数的查询

输入：

纽约天气，要华氏度

输出：

📍 纽约天气
当前：73°F，晴，湿度 50%

示例原则：

• 覆盖常见使用场景
• 展示不同参数组合
• 包含边界情况

---

进阶技巧

1. 使用技能组合

复杂任务可以拆分为多个技能：

## 相关技能

`weather-alert` - 天气预警
`outfit-suggest` - 穿衣建议
`travel-plan` - 出行规划

2. 提供配置选项

允许用户自定义行为：

## 配置选项

在 `TOOLS.md` 中添加：

markdown

Weather Skill

• 默认城市：北京
• 温度单位：celsius
• 是否包含空气质量：true

3. 添加性能提示

说明技能的性能特征：

## 性能特征

平均响应时间：2-3 秒
API 调用次数：1 次/查询
缓存策略：10 分钟内复用数据

4. 说明安全考虑

对于敏感操作，说明安全措施：

## 安全考虑

不存储用户位置信息
API 密钥加密存储
限制查询频率（10 次/分钟）

---

常见错误

错误 1：描述过于模糊

❌ 不好：
> "这个技能可以帮你做很多事情"

✅ 好：
> "查询指定城市的当前天气和未来 3 天预报"

错误 2：参数定义不完整

❌ 不好：

| 参数 | 描述 |
|------|------|
| city | 城市 |

✅ 好：

| 参数名 | 类型 | 必填 | 默认值 | 描述 |
|--------|------|------|--------|------|
| location | string | 是 | - | 城市名称，支持中文和英文 |

错误 3：缺少错误处理

❌ 不好：
（没有错误处理部分）

✅ 好：

## 错误处理

城市不存在：提示用户检查拼写
API 超时：重试后返回友好错误
参数无效：说明有效范围

错误 4：示例太少

❌ 不好：
只有一个示例

✅ 好：
提供 3-5 个示例，覆盖不同场景

---

检查清单

在发布技能前，检查以下项目：

内容完整性

• [ ] 技能名称清晰准确
• [ ] 描述一句话说明核心功能
• [ ] 触发条件列举具体场景
• [ ] 参数定义完整（类型、必填、默认值）
• [ ] 执行步骤按顺序列出
• [ ] 输出格式有实际示例
• [ ] 错误处理覆盖主要场景
• [ ] 示例覆盖常见用法

质量检查

• [ ] 语言简洁清晰
• [ ] 格式一致规范
• [ ] 无拼写错误
• [ ] 链接可访问
• [ ] 代码示例可运行

用户体验

• [ ] 新手能理解
• [ ] 高级用户能找到细节
• [ ] 错误提示友好
• [ ] 示例贴近实际

---

模板下载

完整的 SKILL.md 模板：

# {技能名称}

描述

{一句话描述核心功能}

触发条件

{列举具体使用场景}

参数

参数名 | 类型 | 必填 | 默认值 | 描述
|--------|------|------|--------|------|
{param1} | {type} | {是/否} | {default} | {描述}

执行步骤

{步骤 1}
{步骤 2}
...

输出格式

{输出示例和说明}

错误处理

错误情况 | 处理方式 | 用户提示
|---------|---------|---------|
{error1} | {handling1} | {message1}

示例

示例 1

输入：{input1}
输出：{output1}

示例 2

输入：{input2}
输出：{output2}

注意事项

{note1}
{note2}

相关文件

`{file1}` - {描述}
`{file2}` - {描述}

延伸阅读

链接 1
链接 2

---

总结

编写高质量的 SKILL.md 是创建优秀 OpenClaw 技能的关键。遵循本文的最佳实践，你可以创建：

• 清晰的文档：让用户快速理解技能功能
• 易用的接口：参数设计合理，示例丰富
• 健壮的逻辑：错误处理完善，边界情况考虑周全
• 可维护的代码：结构清晰，便于后续迭代

记住：好的文档不是一次性完成的，而是随着技能的使用不断迭代完善的。收集用户反馈，持续优化你的 SKILL.md。

---

本文属于「OpenClaw」系列专题
最后更新：2026 年 4 月

本文标签：OpenClaw , Skill , 最佳实践