📑 目录

1. Skills 是什么？
2. Skills 的结构
3. 开发一个 Skill（实战）
4. 安装和使用 Skill
5. 技能自动激活原理
6. 技能进阶
7. 完整示例代码
8. 最佳实践
9. 调试技巧
10. 常见问题
11. 快速开始
12. 总结

---

一、Skills 是什么？

概念

Skills 就像是 OpenClaw 的"小程序"或"插件"，每个技能给贾斯汀增加特殊能力。

隐喻

贾斯汀（AI助手）
    ↓
Skills（技能包）
    ├── 发邮件技能 → 能发邮件
    ├── GitHub技能 → 能管理仓库
    ├── 飞书技能 → 能操作飞书
    ├── 天气技能 → 能查天气
    └── ...

核心特性

1. 关键词自动激活 - 贾斯汀根据对话中的关键词自动激活相应技能
2. 模块化设计 - 每个技能专注于特定领域
3. ClawHub 市场 - 统一的技能分发平台
4. 版本管理 - 支持技能的安装、更新、卸载

技能分类

类别	说明	示例
通信集成	WhatsApp、Telegram、微信等消息平台	x-twitter, email
云服务	飞书、Notion、Slack等云服务	feishu-doc, notion
开发工具	GitHub、GitLab、CI/CD等	github, pr-reviewer
容器运维	Kubernetes、Docker、OpenShift等	kubernetes, docker-essentials
项目管理	Trello、Jira、Asana等	trello, jira
实用工具	邮件、天气、数据库等	weather, database

---

二、Skills 的结构

文件结构

my-skill/                     # 技能文件夹
├── SKILL.md                   # 技能信息（名称、描述、作者）
├── index.js                    # 核心代码（工具定义）
├── package.json                # 依赖和版本
└── README.md                   # 使用说明

SKILL.md 示例

---
name: weather
description: 查询天气信息
version: 1.0.0
author: Your Name

这是天气查询技能。

index.js 示例

import { Tool } from "@openclaw/tool";

export default {
  create: (options) => {
    return new Tool({
      name: "get_weather",           // 工具名称
      description: "查询指定城市的天气",  // 工具描述
      parameters: {                 // 定义需要的参数
        city: {
          type: "string",
          description: "城市名称",
          required: true
        }
      },
      execute: async (toolCallId, args) => {
        // 实际执行逻辑
        const weather = await fetchWeather(args.city);
        return {
          result: `${args.city}的天气：${weather}`
        };
      }
    });
  }
};

---

三、开发一个 Skill（实战）

步骤 1：创建技能文件夹

# 进入工作空间
cd ~/.openclaw/workspace/skills

# 创建新技能
mkdir my-first-skill
cd my-first-skill

步骤 2：创建 SKILL.md

# 创建 SKILL.md
cat > SKILL.md << 'EOF'
---
name: my-first-skill
description: 我的第一个技能
version: 1.0.0
author: Your Name

这是一个简单的技能示例。
EOF

步骤 3：创建 package.json

# 初始化 package.json
npm init -y

# 安装必要依赖
npm install @openclaw/tool

步骤 4：创建 index.js

cat > index.js << 'EOF'
import { Tool } from "@openclaw/tool";

export default {
  create: (options) => {
    return new Tool({
      name: "hello",
      description: "打招呼",
      parameters: {
        name: {
          type: "string",
          description: "名字",
          required: false
        }
      },
      execute: async (toolCallId, args) => {
        const userName = args.name || "朋友";
        return {
          result: `你好，${userName}！这是我的第一个技能。`
        };
      }
    });
  }
};
EOF

步骤 5：创建 README.md

cat > README.md << 'EOF'
# My First Skill

这是一个简单的 OpenClaw 技能示例。

## 使用方法

在对话中说：
- "打个招呼"
- "对张三打招呼"

## 功能

简单的问候功能。
EOF

---

四、安装和使用 Skill

方式 1：本地安装（适合开发）

# 将技能放入 skills 目录
mv my-first-skill ~/.openclaw/workspace/skills/

# 重启 Gateway 让新技能生效
openclaw gateway restart

方式 2：通过 ClawHub 安装（适合分享）

# 1. 注册 ClawHub 账号
clawhub login

# 2. 发布技能
clawhub publish ./my-first-skill

# 3. 其他人可以安装
clawhub install my-first-skill

查看已安装技能

# 列出所有已安装技能
clawhub list

# 查看特定技能
clawhub inspect my-first-skill

---

五、技能自动激活原理

工作流程

用户在群里说："打个招呼"
            ↓
    ┌─────────────────┐
    │  贾斯汀        │
    └─────────────────┘
            ↓
    分析消息中的关键词
            ↓
    识别："打招呼" → 可能匹配 hello 工具
            ↓
    查找哪个技能有 hello 工具
            ↓
    找到：my-first-skill
            ↓
    自动激活该技能
            ↓
    执行工具逻辑
            ↓
    返回结果

关键词匹配

用户说	识别关键词	激活的技能	工具
“打个招呼”	打招呼	my-first-skill	hello
“天气怎么样”	天气	weather	get_weather
“查看飞书文档”	飞书、文档	feishu-doc	read

---

六、技能进阶

添加多个工具

// index.js
export default {
  create: (options) => {
    // 返回多个工具
    return [
      new Tool({ name: "tool1", ... }),
      new Tool({ name: "tool2", ... }),
      new Tool({ name: "tool3", ... })
    ];
  }
};

调用其他技能

export default {
  create: (options) => {
    return new Tool({
      name: "call_other_skill",
      description: "调用其他技能",
      execute: async (toolCallId, args) => {
        // 在工具代码中调用其他 API
        const result = await fetchFeishuDoc(args.doc_token);
        return { result };
      }
    });
  }
};

添加配置选项

export default {
  create: (options) => {
    const config = options.config || {};
    return new Tool({
      name: "my_tool",
      description: "我的工具",
      execute: async (toolCallId, args) => {
        // 读取配置
        const apiKey = config.apiKey;
        return { result };
      }
    });
  }
};

---

七、完整示例代码

天气技能完整实现

// weather-skill/index.js
import { Tool } from "@openclaw/tool";

export default {
  create: (options) => {
    return new Tool({
      name: "get_weather",
      description: "获取指定城市的天气信息",
      parameters: {
        city: {
          type: "string",
          description: "城市名称，如：北京、上海",
          required: true
        },
        unit: {
          type: "string",
          description: "温度单位：celsius/fahrenheit",
          required: false,
          default: "celsius"
        }
      },
      execute: async (toolCallId, args) => {
        // 这里调用真实的天气 API
        // 示例：使用模拟数据
        const weatherData = await fetchWeather(args.city);
        
        return {
          result: `🌍 ${args.city} 天气：\n` +
                   `🌡️ 温度：${weatherData.temp}°\n` +
                   `💧 湿度：${weatherData.humidity}%\n` +
                   `🌬 风向：${weatherData.wind}`
        };
      }
    });
  }
};

// 模拟天气 API
async function fetchWeather(city) {
  // 实际项目中这里会调用真实的天气 API
  return {
    temp: Math.floor(20 + Math.random() * 10),
    humidity: Math.floor(40 + Math.random() * 40),
    wind: ["东南", "西北", "南风", "东风"][Math.floor(Math.random() * 4)]
  };
}

---

八、最佳实践

开发规范

1. 错误处理

execute: async (toolCallId, args) => {
  try {
    // 执行逻辑
    return { result: "成功" };
  } catch (error) {
    return { 
      error: `执行失败：${error.message}`,
      result: null
    };
  }
}

2. 输入验证

execute: async (toolCallId, args) => {
  if (!args.city) {
    return { 
      error: "城市名称不能为空",
      result: null
    };
  }
  // 执行逻辑
}

3. 日志记录

execute: async (toolCallId, args) => {
  console.log(`[${new Date().toISOString()}] 执行工具：${args.city}`);
  // 执行逻辑
}

---

九、调试技巧

查看技能是否加载

# 查看 Gateway 状态
openclaw gateway status

# 检查技能是否在列表中
clawhub list | grep my-first-skill

测试技能

# 使用 OpenClaw CLI 测试
openclaw chat --message "打个招呼"

# 或直接在群里说消息

查看工具定义

// 在技能代码中输出工具定义
export default {
  create: (options) => {
    const tool = new Tool({...});
    console.log("工具定义：", JSON.stringify(tool, null, 2));
    return tool;
  }
};

---

十、常见问题

Q1：技能修改后不生效？

A： 需要重启 Gateway

openclaw gateway restart

Q2：技能无法被激活？

A： 检查：

1. SKILL.md 中的 description 是否清晰
2. 工具的 parameters 定义是否正确
3. 关键词是否能匹配到工具名称

Q3：如何查看技能的错误日志？

A：

# 查看 Gateway 日志
openclaw gateway status

# 查看 Gateway 日志文件
tail -f /tmp/openclaw/openclaw-*.log

Q4：技能可以调用其他 API 吗？

A： 可以，在 execute 函数中使用 fetch、http-client 等调用任何 HTTP API。

---

十一、快速开始

30秒创建你的第一个技能

# 1. 进入技能目录
cd ~/.openclaw/workspace/skills

# 2. 创建文件夹
mkdir hello-skill
cd hello-skill

# 3. 创建文件（复制以下内容）
cat > SKILL.md << 'EOF'
---
name: hello
description: 打招呼技能
version: 1.0.0
author: Your Name
EOF

cat > package.json << 'EOF'
{
  "name": "hello-skill",
  "version": "1.0.0",
  "main": "index.js"
}
EOF

cat > index.js << 'EOF'
import { Tool } from "@openclaw/tool";

export default {
  create: (options) => {
    return new Tool({
      name: "say_hello",
      description: "打个招呼",
      execute: async (toolCallId, args) => {
        return {
          result: "你好！这是我的第一个技能。"
        };
      }
    });
  }
};
EOF

# 4. 安装依赖
npm install @openclaw/tool

# 5. 重启 Gateway
openclaw gateway restart

# 6. 测试
# 在群里说："打个招呼"

---

十二、总结

Skills 开发流程

1. 创建技能文件夹
    ↓
2. 编写 SKILL.md（元信息）
    ↓
3. 编写 package.json（依赖）
    ↓
4. 编写 index.js（核心逻辑）
    ↓
5. 编写 README.md（使用说明）
    ↓
6. 放入 skills 目录或发布到 ClawHub
    ↓
7. 重启 Gateway
    ↓
8. 在对话中使用

自动激活机制

用户消息 → 关键词识别 → 匹配技能 → 执行工具 → 返回结果

---

这就是 OpenClaw Skills 的完整创建和使用教程！有任何问题随时问我。🚀