5.3 编写你的第一个 Skill（基础教程）

概述

一、Skill 文件的基本结构

每个 Skill 就是一个 .md 文件，基本结构：

```markdown # 技能名称

简介

（简单说明这个技能做什么）

触发条件

（什么时候该调用这个技能）

基础信息

• 功能：...
• API 地址：...
• 认证方式：...

调用示例

（AI 怎么调用，参数怎么传）

返回格式

（结果是什么样子，AI 怎么解析） ```

二、实战：写一个"天气查询"Skill

目标

步骤 1：创建 Skill 文件夹

mkdir -p ~/.openclaw/workspace/skills/weather

步骤 2：创建 SKILL.md 文件

```markdown # 天气查询技能

简介

查询指定城市的天气情况，返回温度、天气状况等信息。

触发条件

当用户说以下内容时触发：

• "天气"
• "查天气"
• "今天天气怎么样"
• "XX 天气"

关键词：天气

基础信息

• 功能：查询城市天气
• API 地址：https://wttr.in/api
• 认证方式：无（免费公开 API）
• 请求方式：GET
• 返回格式：JSON

调用方式

当触发条件满足时，AI 应： 1. 从用户消息中提取城市名称 2. 调用 API：https://wttr.in/{城市}?format=j1 3. 解析返回的 JSON 数据

调用示例

用户说："北京天气怎么样"

AI 调用： GET https://wttr.in/北京?format=j1

返回数据示例： { "current_condition": [ { "temp_C": "15", "weatherDesc": [{"value": "晴"}], "humidity": "45" } ] }

返回格式

解析后返回给用户的格式： "北京今天天气：晴，温度15°C，湿度45%" ```

三、Skill 编写要点

要点 1：触发条件要明确

❌ 不好：

用户说任何话时都可能触发

✅ 好：

当用户提到"天气"相关关键词时触发：
"天气"
"查天气"
"温度"

要点 2：API 调用要具体

❌ 不好：

调用天气 API 获取天气信息

✅ 好：

调用 https://wttr.in/{城市}?format=j1
方法：GET
参数：城市名（从用户消息中提取）

要点 3：返回格式要清晰

告诉 AI 返回的数据长什么样，怎么解析。

四、让 Skill 生效

步骤 1：保存文件

将 SKILL.md 保存到：

~/.openclaw/workspace/skills/weather/SKILL.md

步骤 2：重新加载 Skills

openclaw skills reload
# 或
openclaw gateway restart

步骤 3：测试

你：北京天气怎么样
AI：应该返回北京天气信息

五、一个完整的 Skill 示例

```markdown # 计算器技能

简介

进行数学计算，支持加减乘除和复杂表达式。

触发条件

当用户消息包含：

• "计算"
• "等于多少"
• "帮我算一下"

基础信息

• 功能：数学计算
• 使用工具：JavaScript eval() 或 math.js
• 精度：小数点后 10 位

调用方式

1. 从用户消息中提取数学表达式 2. 使用 JavaScript 解析和计算 3. 返回结果

返回格式

"计算结果：{表达式} = {结果}"

示例

用户：计算 (123 + 456) * 789 AI：计算结果：(123 + 456) * 789 = 456,771 ```

六、调试 Skill

6.1 查看 Skill 是否被加载

openclaw skills list

6.2 查看 Skill 加载日志

tail -50 ~/.openclaw/logs/gateway.log | grep skill

6.3 测试 Skill 触发

发送带有触发词的消息，看 AI 是否正确响应。

七、常见错误

八、下一步学什么

• 5.4 Skill 调用原理解析 → 理解 AI 怎么找到和调用 Skill
• 5.5 进阶 Skill：带参数的 Skill → 编写更复杂的 Skill

动手写一个 Skill 比想象中简单！试试看 💪

常见问题