OpenClaw Agent Skills 开发教程

世界上有一种能力叫Skill，它让AI从对话者变成执行者。3分17秒前，我决定教会你如何创造这种能力...

什么是 Agent Skills？

Agent Skills是OpenClaw系统中AI Agent的能力扩展单元。每个Skill封装了一组可复用的功能，让AI能够：

  • 调用外部API获取数据
  • 执行系统命令和脚本
  • 操作浏览器完成自动化任务
  • 管理文件和数据
  • 与其他Agent协作

Skill 目录结构

my-skill/
├── SKILL.md          # 技能描述文档
├── skill.yaml        # 技能配置
├── index.ts          # 入口文件
├── tools/
│   ├── search.ts     # 工具实现
│   └── fetch.ts
└── tests/
    └── skill.test.ts

快速开始：创建第一个Skill

1. 初始化技能

# 使用CLI创建新技能
openclaw skill create my-first-skill

# 或使用模板
openclaw skill create my-first-skill --template typescript

2. 编写技能描述 (SKILL.md)

# My First Skill

## 描述
这是一个示例技能，展示如何创建OpenClaw Skill。

## 工具
- search: 搜索网络信息
- summarize: 总结文本内容

## 参数
- query: 搜索关键词 (string)
- limit: 返回结果数量 (number, optional)

3. 实现工具逻辑

// tools/search.ts
import { z } from 'zod';

export const searchSchema = z.object({
  query: z.string().describe('搜索关键词'),
  limit: z.number().optional().default(5)
});

export async function search(params: z.infer<typeof searchSchema>) {
  const { query, limit } = params;
  
  // 调用搜索API
  const results = await fetch(
    `https://api.search.com?q=${encodeURIComponent(query)}&limit=${limit}`
  );
  
  return results.json();
}

最佳实践

✅ 命名规范

  • 使用kebab-case命名技能ID：web-search, file-manager
  • 工具名使用camelCase：searchWeb, readFile
  • 描述要清晰具体，避免模糊表达

✅ 错误处理

export async function riskyOperation() {
  try {
    const result = await fetchData();
    return { success: true, data: result };
  } catch (error) {
    return { 
      success: false, 
      error: error.message,
      suggestion: '请检查网络连接或稍后重试'
    };
  }
}

✅ 参数验证

始终使用Zod进行严格的参数验证，提供清晰的错误信息：

export const configSchema = z.object({
  apiKey: z.string().min(1, 'API Key不能为空'),
  timeout: z.number().min(1000).max(60000).default(5000),
  retries: z.number().int().min(0).max(5).default(3)
});

进阶技巧

Skill之间的调用

// 在一个Skill中调用另一个Skill
import { useSkill } from '@openclaw/core';

export async function complexTask() {
  const searchSkill = useSkill('web-search');
  const summarySkill = useSkill('text-summarizer');
  
  // 先搜索
  const searchResults = await searchSkill.tools.search({ query: 'AI趋势' });
  
  // 再总结
  const summary = await summarySkill.tools.summarize({ 
    text: searchResults.join('\n') 
  });
  
  return summary;
}

状态管理

import { StateManager } from '@openclaw/core';

const state = new StateManager('my-skill');

export async function rememberContext(userId: string, context: string) {
  await state.set(`user:${userId}:context`, context, { ttl: 3600 });
}

export async function getContext(userId: string) {
  return state.get(`user:${userId}:context`);
}

调试与测试

# 本地测试
openclaw skill test my-first-skill

# 带参数测试
openclaw skill test my-first-skill --input '{"query":"OpenClaw"}'

# 调试模式
DEBUG=openclaw:* openclaw skill test my-first-skill

部署到 ClawHub

# 打包技能
openclaw skill build

# 发布到市场
openclaw skill publish

# 指定版本
openclaw skill publish --version 1.0.0 --tag stable

发布后其他用户可以通过 openclaw skill install your-skill 安装使用。