夜雨聆风🎯 学习目标
⏱️ 阅读时间：约 10 分钟
💡 前置要求：无
🎯 什么是自定义技能？
一句话概括
自定义技能 = 你自己开发的功能模块 = 手机下载的 App
生活化比喻
| 操作系统 | ||
| 预装 App | ||
| 下载 App | ||
| 用户 |
为什么需要自定义技能？
📦 技能结构详解
完整技能目录结构
my-custom-skill/├── SKILL.md # 技能说明（必需）⭐├── index.js # 技能实现（可选）├── package.json # 依赖配置（可选）├── scripts/ # 辅助脚本（可选）│ └── helper.js└── references/ # 参考资料（可选） └── api-docs.md最小技能结构（仅需一个文件）
weather-skill/└── SKILL.md # 只有这个文件也可以！📝 SKILL.md 编写指南 ⭐
标准模板
# 技能名称## 描述用 1-2 句话简短描述这个技能的用途## 何时使用列出触发这个技能的场景：- 场景 1- 场景 2- 场景 3## 参数| 参数名 | 类型 | 必需 | 默认值 | 说明 ||--------|------|------|--------|------|| city | string | 是 | - | 城市名称 || days | number | 否 | 3 | 预报天数 |## 使用示例# 示例 1对话或命令示例# 示例 2另一个示例## 错误处理| 错误 | 原因 | 解决方案 ||--------|------|------|| 错误 1 | 原因 1 | 解决方案 2 || 错误 2 | 原因 2 | 解决方案 1 |## 注意事项- 注意点 1- 注意点 2SKILL.md完整示例
# 天气查询## 描述根据用户指定的城市，查询实时天气状况及未来多天天气预报，支持文字对话与命令式调用。## 何时使用- 用户主动询问天气情况- 用户出行前需要查看天气- 用户想了解未来几天的天气趋势- 用户需要根据天气安排行程或活动## 参数| 参数名 | 类型 | 必需 | 默认值 | 说明 ||--------|------|------|--------|------|| city | string | 是 | - | 城市名称，支持中英文、地级市及以上 || days | number | 否 | 3 | 预报天数，取值范围 1-7 |## 使用示例# 示例 1：命令式查询当天天气天气查询 --city 北京# 示例 2：命令式查询未来多天天气天气查询 --city 上海 --days 5# 示例 3：自然对话触发"北京今天天气怎么样？""上海未来 5 天天气如何？"## 错误处理| 错误 | 原因 | 解决方案 ||--------|------|------|| 未获取到天气数据 | 城市名称错误或不支持 | 请检查城市名是否正确，仅支持地级市及以上 || 天数超出范围 | days 不在 1-7 之间 | 请输入 1~7 之间的整数 || 网络请求失败 | 网络异常或服务不可用 | 请稍后重试，或检查网络连接 |## 注意事项- 仅支持国内地级市及以上城市，不支持区县、乡镇级查询- 预报数据来源于公开气象接口，结果仅供参考- 多次重复查询可能会触发限流，建议间隔使用- 自然语言对话会自动提取城市与天数，无需手动传参🛠️ 实战 1：创建第一个技能（无代码）
场景：名言警句生成器
这个技能不需要代码，只需要配置 SKILL.md。
步骤流程
步骤 2：创建技能目录
mkdir -p ~/.openclaw/skills/quote-generatorcd ~/.openclaw/skills/quote-generator步骤 2：编写 SKILL.md
# 名言警句生成器## 描述随机返回一句名人名言，激励用户## 何时使用- 用户需要鼓励时- 用户请求名言警句- 用户说"来句鸡汤"## 参数无## 使用示例```bash# 示例 1用户："来句名言"AI："生活就像骑自行车，要保持平衡就得往前走。——爱因斯坦"# 示例 2用户："我需要鼓励"AI："成功不是最终的，失败不是致命的：重要的是继续前进的勇气。——丘吉尔"## 注意事项名言库内置在技能描述中每次随机返回一句## 内置名言库- "生活就像骑自行车，要保持平衡就得往前走。" —— 爱因斯坦- "成功不是最终的，失败不是致命的：重要的是继续前进的勇气。" —— 丘吉尔- "唯一能阻止你实现明天目标的就是今天的犹豫。" —— 罗斯福- "最好的预测未来的方式就是去创造它。" —— 德鲁克- "你必须在有限的时间里充分利用自己。" —— 乔布斯步骤 3：安装技能
openclaw skill install ~/.openclaw/skills/quote-generator步骤 4：测试
# 命令行测试openclaw skill test quote-generator# 对话测试"来句名言""我需要鼓励"🛠️ 实战 2：创建天气查询技能（带代码）
场景：查询实时天气
步骤流程
步骤 1：创建技能目录
mkdir -p ~/.openclaw/skills/weather-querycd ~/.openclaw/skills/weather-query步骤 2：编写 SKILL.md
# 天气查询## 描述查询指定城市的实时天气和预报## 何时使用- 用户询问天气情况- 用户需要出行前查看天气- 用户想了解未来几天的天气趋势## 参数| 参数名 | 类型 | 必需 | 默认值 | 说明 ||--------|------|------|--------|------|| city | string | 是 | - | 城市名称 || days | number | 否 | 3 | 预报天数 |## 使用示例# 查询北京今天天气天气查询 --city 北京# 查询上海未来 5 天预报天气查询 --city 上海 --days 5## 错误处理| 错误 | 原因 | 解决方案 ||--------|------|------|| 城市不存在 | 输入的城市名称无效 | 检查城市名称拼写 || API 调用失败 | 网络连接问题 | 检查网络连接 |## 注意事项- 城市名称支持中英文- 预报最多 7 天- 数据来源：wttr.in步骤 3：创建 index.js
// index.jsmodule.exports = { name: 'weather-query', async execute({ city, days = 3 }) { try { // 1. 验证参数 if (!city) { throw new Error('城市名称必填'); } if (days < 1 || days > 7) { throw new Error('预报天数范围为 1-7 天'); } // 2. 调用天气 API const response = await fetch( `https://wttr.in/${encodeURIComponent(city)}?format=j&num_of_days=${days}` ); if (!response.ok) { throw new Error(`API 调用失败：${response.statusText}`); } const data = await response.json(); // 3. 格式化天气信息 return formatWeather(data); } catch (error) { // 4. 错误处理 console.error('天气查询失败:', error); throw error; } }};// 格式化天气数据function formatWeather(data) { const current = data.current_condition[0]; const forecast = data.weather; let result = `🌤️ ${data.nearest_area[0].areaName[0].value} 天气\n\n`; result += `当前温度：${current.temp_C}°C\n`; result += `天气状况：${current.weatherDesc[0].value}\n`; result += `湿度：${current.humidity}%\n`; result += `风速：${current.windspeedKmph} km/h\n\n`; if (forecast && forecast.length > 0) { result += `📅 未来 ${forecast.length} 天预报：\n`; forecast.forEach(day => { result += `\n${day.date}:\n`; result += ` 最高：${day.maxtempC}°C, 最低：${day.mintempC}°C\n`; result += ` 天气：${day.avgtempC}°C\n`; }); } return result;}步骤 4：安装并测试
# 安装技能openclaw skill install ~/.openclaw/skills/weather-query# 测试openclaw skill test weather-query --city 北京 --days 3# 对话测试"北京今天天气怎么样？""上海未来 5 天天气"🔧 技能调试技巧
1. 日志输出
module.exports = {name: 'my-skill',asyncexecute(params) {// 1. 打印输入参数console.log('输入参数:', JSON.stringify(params, null, 2));// 2. 验证参数const errors = validateParams(params);if (errors.length > 0) {console.error('参数验证失败:', errors);thrownewError(`参数错误：${errors.join(', ')}`); }// 3. 执行主要逻辑console.log('开始执行主要逻辑...');const result = awaitdoSomething(params);// 4. 打印输出console.log('输出结果:', JSON.stringify(result, null, 2));return result; }};2. 本地测试
# 使用测试命令openclaw skill test my-skill --param1 value1 --param2 value2# 查看详细日志openclaw skill logs my-skill --tail 100# 实时调试模式openclaw skill dev my-skill3. 错误定位
module.exports = {name: 'my-skill',asyncexecute(params) {try {// 分步骤执行，便于定位问题console.log('步骤 1: 准备数据');const data = awaitprepareData(params);console.log('步骤 2: 调用 API');const result = awaitcallAPI(data);console.log('步骤 3: 格式化结果');const formatted = formatResult(result);return formatted; } catch (error) {console.error('技能执行失败:', {name: error.name,message: error.message,stack: error.stack });throw error; } }};📋 技能配置选项
package.json 示例
{"name":"weather-query","version":"1.0.0","description":"天气查询技能","main":"index.js","dependencies":{"node-fetch":"^3.0.0"},"scripts":{"test":"openclaw skill test weather-query"}}技能元数据（可选）
## 元数据- 版本：1.0.0- 作者：你的名字- 许可证：MIT- 标签：天气、查询、生活💡 最佳实践
1. 命名规范
weather-query | ||
Weather Query |
2. 错误处理
asyncexecute({ city }) {// 1. 验证参数if (!city) {thrownewError('缺少必需参数：city'); }try {// 2. 主要逻辑const result = awaitcallAPI(city);return result; } catch (error) {// 3. 友好的错误信息thrownewError(`天气查询失败：${error.message}`); }}3. 文档完整
4. 代码质量
📊 技能开发流程总结
✅ 学完这篇你能做什么
学完 Day 8，你将能够：
✅ 理解自定义技能的作用 ✅ 编写规范的 SKILL.md ✅ 创建简单自定义技能 ✅ 调试技能问题 ✅ 遵循最佳实践
🔜 下篇预告
Day 9：自定义技能开发（下）：复杂场景、技能组合、错误处理
🎯 复杂场景处理 🔗 技能组合使用 ⚠️ 错误处理最佳实践