Agent Skills开发完全指南 | OpenClaw技能编写教程

导读：Skills是OpenClaw的核心扩展机制。通过编写Skills，你可以让AI获得任何能力——从网页搜索到代码执行，从数据分析到图像生成。本教程将手把手教你如何开发自己的Agent Skills。

📋 功能介绍

Agent Skills是OpenClaw的插件系统，具有以下特点：

模块化设计 - 每个Skill独立运行，互不影响
自动发现 - AI自动识别何时调用哪个Skill
版本控制 - 支持Skill版本管理和更新
权限隔离 - 细粒度的权限控制，确保安全性
易于分享 - 可以发布到ClawHub与他人共享

🏗️ 技能架构

一个完整的Skill包含以下文件：

my-skill/
├── SKILL.md          # 技能定义文件（必需）
├── index.js          # 入口文件（可选）
├── utils.js          # 工具函数（可选）
└── package.json      # 依赖配置（可选）

✍️ SKILL.md编写规范

SKILL.md是Skill的核心定义文件，采用Markdown格式：

# Skill名称

## 描述
简短描述这个Skill的功能

## 触发条件
- 当用户询问天气时
- 当需要获取当前温度时

## 参数
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| city | string | 是 | 城市名称 |
| date | string | 否 | 日期，默认今天 |

## 示例
### 示例1：获取北京天气
用户："北京今天天气怎么样？"
调用：{"city": "北京", "date": "today"}
返回：{"temperature": "25°C", "weather": "晴"}

### 示例2：获取明天天气
用户："明天上海会下雨吗？"
调用：{"city": "上海", "date": "tomorrow"}
返回：{"temperature": "22°C", "weather": "小雨"}

🔧 开发实战：创建一个天气查询Skill

步骤1：创建项目目录

mkdir -p ~/.openclaw/skills/weather-query
cd ~/.openclaw/skills/weather-query

步骤2：编写SKILL.md

# Weather Query

## 描述
查询指定城市的实时天气和未来预报

## 触发条件
- 用户询问天气情况
- 需要获取温度、湿度、风速等气象信息
- 涉及"天气"、"温度"、"下雨"、"晴天"等关键词

## 参数
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| city | string | 是 | 城市名称，如"北京"、"Shanghai" |
| days | number | 否 | 预报天数，1-7天，默认1 |

## 示例
### 示例1：查询今天天气
用户："今天北京天气怎么样？"
调用：{"city": "北京", "days": 1}
返回：{"current": {"temp": 25, "weather": "晴"}}

## 依赖
- 需要环境变量 WEATHER_API_KEY
- 网络访问权限

步骤3：编写执行代码

// index.js
const axios = require('axios');

async function execute(params) {
  const { city, days = 1 } = params;
  const apiKey = process.env.WEATHER_API_KEY;
  
  try {
    const response = await axios.get(
      `https://api.weather.com/v1/current?city=${encodeURIComponent(city)}&key=${apiKey}`
    );
    
    return {
      success: true,
      data: {
        city: response.data.city,
        temperature: response.data.temp,
        weather: response.data.condition,
        humidity: response.data.humidity,
        windSpeed: response.data.wind
      }
    };
  } catch (error) {
    return {
      success: false,
      error: `查询失败: ${error.message}`
    };
  }
}

module.exports = { execute };

步骤4：注册Skill

# 让OpenClaw识别新Skill
openclaw skills refresh

# 验证Skill已加载
openclaw skills list

        💡 提示：Skill编写完成后，建议先用openclaw skills test weather-query命令测试，确保功能正常。
      

✅ 最佳实践

1. 触发条件要精准

避免过于宽泛的触发条件，否则AI会频繁误调用。使用具体的关键词组合。

2. 参数设计要合理

必要参数越少越好
提供合理的默认值
参数名要语义清晰

3. 错误处理要完善

始终返回包含success字段的结果，错误信息要友好易懂。

4. 文档要详细

示例场景越丰富，AI理解越好。至少提供3-5个不同场景的示例。

🚀 高级技巧

Skill组合调用

Skills可以相互调用，构建复杂工作流：

// 在Skill A中调用Skill B
const { callSkill } = require('openclaw/skills');

async function execute(params) {
  // 先调用天气Skill
  const weather = await callSkill('weather-query', { city: params.city });
  
  // 再调用穿衣建议Skill
  const suggestion = await callSkill('clothing-advice', { 
    temperature: weather.data.temperature 
  });
  
  return { weather, suggestion };
}

使用内置工具

OpenClaw提供丰富的内置工具函数：

const { 
  webSearch,      // 网页搜索
  fetchUrl,       // 获取网页内容
  executeCode,    // 执行代码
  saveFile,       // 保存文件
  readFile        // 读取文件
} = require('openclaw/tools');

// 在Skill中使用
const searchResults = await webSearch('OpenClaw latest news');

配置持久化存储

const { storage } = require('openclaw');

// 保存数据
await storage.set('user-preferences', { theme: 'dark' });

// 读取数据
const prefs = await storage.get('user-preferences');

📤 发布到ClawHub

开发完成后，可以发布到ClawHub与他人分享：

# 登录ClawHub
clawhub login

# 发布Skill
clawhub publish ./my-skill --name my-awesome-skill

# 更新Skill
clawhub update my-awesome-skill ./my-skill

🎯 推荐Skill：新手可以先研究官方Skills的源码，如web-search、browser、file-operations等，学习最佳实践。

🔗 相关链接

OpenClaw安装教程 ClawHub技能市场工作流编排教程 Skills术语百科 ClawHub官网官方Skills文档

❓ 常见问题

Q: Skill不生效怎么办？

检查SKILL.md语法是否正确
运行openclaw skills refresh刷新
查看日志排查错误

Q: 如何调试Skill？

# 启用调试模式
openclaw skills test my-skill --debug

# 查看详细日志
tail -f ~/.openclaw/logs/skills.log

Q: Skill可以调用外部API吗？

可以，但需要在SKILL.md中声明依赖，并在配置中设置相应的API密钥。