OpenClaw 自定义 Skills 创建指南

weixin_39306154

1204人浏览 · 2026-03-19 15:22:03

weixin_39306154 · 2026-03-19 15:22:03 发布

OpenClaw 自定义 Skills 创建指南

🎯 适用人群：新手友好 | 零基础入门 | 中文详细注释 | 含完整示例

📖 什么是 Skills？

Skills（技能） 是 OpenClaw 的"能力扩展包"，本质上是一个包含说明文件的文件夹。

想象一下：

📱 手机安装 APP → 获得新功能
🧩 OpenClaw 安装 Skills → AI 助手学会新能力

Skills 能做什么？

🌤️ 查询天气
📅 管理日历
📧 处理邮件
🔍 搜索信息
🎨 生成图片
🔧 执行自定义脚本
… 任何你能想到的功能！

🗂️ Skills 文件结构

一个最简单的 Skills 长这样：

my-skill/                 # Skills 文件夹（名称自定义）
└── SKILL.md              # 必须的！Skills 的核心文件

复杂的 Skills 可能有：

my-skill/
├── SKILL.md              # 核心说明文件（必须）
├── scripts/              # 可选：脚本文件夹
│   ├── run.sh
│   └── process.py
├── templates/            # 可选：模板文件
│   └── report.txt
└── config.yaml           # 可选：配置文件

🚀 第一步：创建你的第一个 Skills

1️⃣ 创建 Skills 文件夹

打开终端，运行：

# 方法 1：在工作区创建（推荐新手）
mkdir -p ~/.openclaw/workspace/skills/hello-world

# 方法 2：在全局目录创建（所有会话可用）
mkdir -p ~/.openclaw/skills/hello-world

💡 两个位置的区别：

workspace/skills - 只对当前工作区有效

~/.openclaw/skills - 对所有工作区有效（全局）

2️⃣ 创建 SKILL.md 文件

在刚创建的文件夹中创建 SKILL.md：

# 进入文件夹
cd ~/.openclaw/workspace/skills/hello-world

# 创建文件（使用你喜欢的编辑器）
code SKILL.md        # VS Code
nano SKILL.md        # Nano 编辑器
vim SKILL.md         # Vim 编辑器

3️⃣ 编写 SKILL.md 内容

复制以下内容到 SKILL.md：

---
name: hello_world
description: 一个简单的问候技能，用于测试和学习
---

# Hello World Skills

这是一个示例 Skills，用于演示如何创建自定义 Skills。

## 什么时候使用

当用户说以下类似的话时使用此技能：
- "打个招呼"
- "问个好"
- "测试一下技能"
- "运行 hello world"

## 如何响应

使用简单的问候语回复用户，例如：
- "你好！Hello World Skills 运行成功！👋"
- "嗨！我是你的自定义 Skills，很高兴见到你！"

## 示例

**用户：** 打个招呼
**助手：** 你好！Hello World Skills 运行成功！👋

4️⃣ 重启 OpenClaw 会话

创建完成后，需要重启会话让 OpenClaw 发现新 Skills：

# 在 OpenClaw 中输入
/new
# 或
/reset

5️⃣ 测试你的 Skills

在新会话中尝试：

用户：打个招呼

如果 AI 用你设定的方式回复，恭喜你！第一个 Skills 创建成功！ 🎉

📝 SKILL.md 文件详解

SKILL.md 是 Skills 的核心，由两部分组成：

第一部分：YAML Frontmatter（元数据）

位于文件最顶部，用 --- 包裹：

---
name: my_skill_name          # Skills 名称（必填，英文，无空格）
description: 技能的描述       # 技能描述（必填，中文或英文）
homepage: https://example.com # 可选：主页链接
metadata: { ... }             # 可选：高级配置
---

必填字段

字段	说明	示例
`name`	Skills 名称，只能使用英文、数字、下划线、连字符	`weather_query`, `hello-world`
`description`	技能描述，说明这个技能做什么	“查询天气信息”

可选字段

字段	说明	示例
`homepage`	技能的主页链接	`https://wttr.in`
`metadata`	高级配置（见下文）	`{ "openclaw": {...} }`

metadata 详解（高级）

metadata: { "openclaw": { "emoji": "🌤️", "requires": { "bins": ["curl"] } } }

常用配置：

{
  "openclaw": {
    "emoji": "🌤️",                    // 显示的表情符号
    "requires": {
      "bins": ["curl", "node"],       // 需要的命令行工具
      "env": ["API_KEY"],             // 需要的环境变量
      "config": ["browser.enabled"]   // 需要的配置项
    },
    "primaryEnv": "API_KEY",          // 主要的环境变量名
    "os": ["darwin", "linux"],        // 支持的操作系统
    "always": true,                   // 始终启用（跳过检查）
    "install": [...]                  // 自动安装配置
  }
}

第二部分：Markdown 说明（指令）

Frontmatter 之后是给 AI 的指令，用 Markdown 格式编写：

# 技能名称

这里是技能的详细说明...

## 什么时候使用

列出使用场景...

## 如何使用

说明具体步骤...

## 示例

用户：...
助手：...

🎯 实战案例：创建天气查询 Skills

完整示例

---
name: weather_query
description: 查询任意城市的实时天气和预报
homepage: https://wttr.in/
metadata: { "openclaw": { "emoji": "🌤️", "requires": { "bins": ["curl"] } } }
---

# 天气查询技能

使用 wttr.in 服务查询全球任意城市的天气信息。**无需 API 密钥**。

## 什么时候使用

✅ **使用此技能当：**
- "今天天气怎么样？"
- "北京会下雨吗？"
- "上海周末的天气"
- "纽约的温度"
- 旅行前查询目的地天气

❌ **不要使用当：**
- 需要历史天气数据
- 需要极端天气预警
- 需要航空/海洋专业天气

## 查询命令

### 实时天气（简洁版）
```bash
curl "wttr.in/城市名？format=3"

实时天气（详细版）

curl "wttr.in/城市名？0"

3 天预报

curl "wttr.in/城市名"

指定城市示例

curl "wttr.in/Beijing?format=3"
curl "wttr.in/Shanghai?format=3"
curl "wttr.in/New+York?format=3"

输出格式说明

format=3 输出示例：

Beijing: ☀️ +25°C, 西北风 3 级

格式代码：

%c — 天气状况表情
%t — 温度
%f — 体感温度
%w — 风速
%h — 湿度
%p — 降水概率

快速响应模板

用户： 北京天气怎么样？
助手：

curl -s "wttr.in/Beijing?format=%l:+%c+%t+(体感+%f),+%w 风，+%h 湿度"

然后解读结果。

用户： 周末会下雨吗？
助手：

curl -s "wttr.in/Beijing?format=%p"

降水概率 > 50% 提示可能下雨。

注意事项

城市名用拼音或英文：Beijing, Shanghai, New+York
空格用 + 替代：New+York
不要频繁请求（有速率限制）
支持机场代码：wttr.in/PEK（北京首都机场）

### 安装和使用

```bash
# 1. 创建文件夹
mkdir -p ~/.openclaw/workspace/skills/weather-query

# 2. 创建 SKILL.md（复制上面的内容）
cd ~/.openclaw/workspace/skills/weather-query
code SKILL.md

# 3. 重启会话
# 在 OpenClaw 中输入 /new

# 4. 测试
用户：北京天气怎么样？

🔧 实战案例：创建文件备份 Skills

---
name: file_backup
description: 备份指定文件夹到备份目录
metadata: { "openclaw": { "emoji": "💾", "requires": { "bins": ["rsync"] } } }
---

# 文件备份技能

使用 rsync 工具备份重要文件。

## 什么时候使用

✅ **使用此技能当：**
- "备份我的工作文档"
- "把照片备份到移动硬盘"
- "创建项目文件的备份"
- "定期备份配置"

## 备份命令

### 基本备份
```bash
rsync -av --progress /源目录/ /备份目录/

增量备份（推荐）

rsync -av --delete --progress /源目录/ /备份目录/

排除特定文件

rsync -av --exclude='*.tmp' --exclude='node_modules/' /源目录/ /备份目录/

远程备份（SSH）

rsync -avz -e ssh /本地目录/ 用户@远程主机:/远程目录/

常用示例

用户： 备份我的工作文档到移动硬盘
助手：

# 先确认目标路径
# 假设移动硬盘挂载在 /Volumes/Backup
rsync -av --progress ~/Documents/Work/ /Volumes/Backup/Work-Backup/

用户： 备份项目文件，排除 node_modules
助手：

rsync -av --exclude='node_modules/' --exclude='dist/' --exclude='.git/' ~/Projects/my-project/ ~/Backups/my-project-backup/

验证备份

备份完成后，验证文件数量：

# 源目录文件数
find /源目录/ -type f | wc -l

# 备份目录文件数
find /备份目录/ -type f | wc -l

注意事项

⚠️ 执行前确认路径，避免误删
建议先运行** dry-run** 测试：rsync -av --dry-run ...
大文件备份显示进度：加 --progress 参数
网络备份用 -z 压缩传输

---

## 🎨 实战案例：创建待办事项管理 Skills

```markdown
---
name: todo_manager
description: 创建、查看、管理待办事项清单
metadata: { "openclaw": { "emoji": "✅" } }
---

# 待办事项管理技能

帮助用户管理日常任务和待办事项。

## 数据存储

待办事项保存在：`~/.openclaw/workspace/todos.md`

## 什么时候使用

✅ **使用此技能当：**
- "添加一个待办"
- "查看我的任务"
- "标记任务为完成"
- "删除已完成的任务"
- "今天有什么要做的"

## 命令操作

### 查看待办列表
```bash
cat ~/.openclaw/workspace/todos.md

添加新任务

echo "- [ ] 任务描述 $(date '+%Y-%m-%d %H:%M')" >> ~/.openclaw/workspace/todos.md

标记任务完成

编辑 todos.md，将 [ ] 改为 [x]

删除已完成任务

# 显示未完成的任务
grep '^\- \[ \]' ~/.openclaw/workspace/todos.md > ~/.openclaw/workspace/todos-new.md
mv ~/.openclaw/workspace/todos-new.md ~/.openclaw/workspace/todos.md

文件格式

todos.md 格式示例：

# 待办事项

## 进行中
- [ ] 完成项目报告 2026-03-19
- [ ] 回复邮件 2026-03-19

## 已完成
- [x] 晨会 2026-03-18
- [x] 提交代码 2026-03-18

快速响应

用户： 添加一个待办：完成项目报告
助手：

echo "- [ ] 完成项目报告 $(date '+%Y-%m-%d %H:%M')" >> ~/.openclaw/workspace/todos.md

然后确认：“已添加：完成项目报告”

用户： 查看我的待办
助手：

cat ~/.openclaw/workspace/todos.md

然后总结未完成的任务数量。

用户： 标记第一个任务为完成
助手：
使用编辑器或 sed 命令修改第一个 [ ] 为 [x]

高级功能

按优先级排序

在任务前加优先级标记：

- [ ] 🔴 紧急：完成报告
- [ ] 🟡 重要：回复邮件
- [ ] 🟢 普通：整理文件

设置截止日期

- [ ] 任务描述 📅 2026-03-25

分类管理

## 工作
- [ ] ...

## 个人
- [ ] ...

## 购物
- [ ] ...

---

## 🛠️ 高级功能：添加自定义脚本

### 在 Skills 中包含脚本

my-skill/
├── SKILL.md
└── scripts/
└── process.sh

### SKILL.md 中引用脚本

```markdown
---
name: data_processor
description: 处理数据文件
metadata: { "openclaw": { "emoji": "📊", "requires": { "bins": ["bash"] } } }
---

# 数据处理技能

## 使用脚本处理

执行 Skills 目录下的处理脚本：

```bash
# 获取 Skills 目录路径
SKILL_DIR="{baseDir}"

# 运行脚本
bash "$SKILL_DIR/scripts/process.sh" 参数

脚本示例

scripts/process.sh：

#!/bin/bash
# 数据处理脚本

INPUT_FILE="$1"
OUTPUT_FILE="$2"

echo "处理文件：$INPUT_FILE"
# ... 处理逻辑
echo "输出到：$OUTPUT_FILE"

注意事项

{baseDir} 会被替换为 Skills 的实际路径
确保脚本有执行权限：chmod +x scripts/process.sh

---

## ⚙️ 配置 Skills（可选）

某些 Skills 需要配置 API 密钥或环境变量。

### 编辑配置文件

```bash
# 打开配置
code ~/.openclaw/openclaw.json

配置示例

{
  "skills": {
    "entries": {
      "weather_query": {
        "enabled": true,
        "env": {
          "WEATHER_API_KEY": "你的 API 密钥"
        }
      },
      "my_custom_skill": {
        "enabled": true,
        "apiKey": "GEMINI_KEY_HERE",
        "config": {
          "endpoint": "https://api.example.com",
          "timeout": 30
        }
      }
    }
  }
}

字段说明

字段	说明
`enabled`	`true` 启用，`false` 禁用
`env`	环境变量键值对
`apiKey`	API 密钥（便捷字段）
`config`	自定义配置项

🧪 调试和测试 Skills

1. 检查 Skills 是否被识别

# 列出所有 Skills
openclaw skills list

# 只列出可用的 Skills
openclaw skills list --eligible

# 查看某个 Skills 详情
openclaw skills info hello_world

2. 检查依赖是否满足

# 检查所有 Skills 的依赖
openclaw skills check

输出示例：

✅ weather_query - 所有依赖满足
⚠️  gemini - 缺少：gemini 命令
⚠️  my_skill - 缺少环境变量：API_KEY

3. 测试 Skills

# 在新会话中测试
/new

# 尝试触发技能
用户：使用 hello_world 技能

4. 查看日志

# 查看 Gateway 日志（问题排查）
# 位置因安装方式而异

📋 Skills 开发最佳实践

✅ 推荐做法

名称规范
- 使用小写字母
- 用下划线或连字符分隔单词
- 示例：weather_query, file-backup
描述清晰
- 一句话说明技能用途
- 让用户一眼看懂
指令明确
- 告诉 AI 什么时候使用
- 告诉 AI 怎么使用
- 提供具体示例
错误处理
- 说明可能的错误
- 提供解决方案
测试充分
- 创建后立刻测试
- 覆盖各种使用场景

❌ 避免的做法

不要在指令中包含敏感信息

❌ 错误：使用 API 密钥 abc123xyz
✅ 正确：使用配置中的 API_KEY 环境变量

不要过于复杂
- 一个 Skills 专注一个功能
- 复杂功能拆分成多个 Skills
不要忽略依赖
- 明确声明需要的工具
- 提供安装说明

不要硬编码路径

❌ 错误：读取 /Users/张三/file.txt
✅ 正确：读取 ~/file.txt 或 $HOME/file.txt

🎓 常见问题 FAQ

Q1: Skills 创建后不生效？

A: 需要重启 OpenClaw 会话：

# 在 OpenClaw 中输入
/new

Q2: 如何禁用某个 Skills？

A: 两种方法：

方法 1：配置文件

{
  "skills": {
    "entries": {
      "my_skill": { "enabled": false }
    }
  }
}

方法 2：重命名文件夹

mv ~/.openclaw/workspace/skills/my_skill ~/.openclaw/workspace/skills/my_skill.disabled

Q3: Skills 名称冲突怎么办？

A: OpenClaw 按以下优先级加载：

工作区 Skills > 全局 Skills > 内置 Skills

重名时，高优先级的会覆盖低优先级的。

Q4: 如何分享我的 Skills？

A: 三种方式：

发布到 ClawHub（推荐）

clawhub publish ./my-skill --slug my-skill --name "My Skill"

分享文件夹
- 打包整个 Skills 文件夹
- 发送给朋友
发布到 GitHub
- 创建公开仓库
- 分享仓库链接

Q5: Skills 可以调用外部 API 吗？

A: 可以！在 SKILL.md 中说明如何使用 API：

## API 调用

```bash
curl -X POST "https://api.example.com/endpoint" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"key": "value"}'

在配置文件中设置 API_KEY 环境变量。

### Q6: 如何调试 Skills 问题？

**A:** 逐步排查：

1. 检查 `SKILL.md` 格式是否正确
2. 运行 `openclaw skills check` 查看依赖
3. 在新会话中测试 `/new`
4. 查看 AI 是否正确理解指令
5. 必要时添加更详细的说明

---

## 📚 参考资源

### 官方文档

| 资源 | 链接 |
|------|------|
| OpenClaw 文档 | https://docs.openclaw.ai |
| ClawHub | https://clawhub.com |
| AgentSkills 规范 | https://agentskills.io |

### 内置 Skills 示例

查看系统自带的 Skills 学习：

```bash
# 查看内置 Skills 位置
ls ~/.npm-global/lib/node_modules/openclaw/skills/

# 查看某个 Skills 的 SKILL.md
cat ~/.npm-global/lib/node_modules/openclaw/skills/weather/SKILL.md

配置参考

完整配置 schema 参考：

cat ~/.npm-global/lib/node_modules/openclaw/docs/zh-CN/tools/skills-config.md

🎯 快速命令参考

# ===== Skills 管理 =====
openclaw skills list           # 列出所有 Skills
openclaw skills list --eligible # 列出可用的 Skills
openclaw skills info <名称>     # 查看 Skills 详情
openclaw skills check          # 检查依赖

# ===== ClawHub 操作 =====
clawhub search "关键词"         # 搜索 Skills
clawhub install <名称>          # 安装 Skills
clawhub update --all           # 更新所有 Skills
clawhub publish ./my-skill     # 发布 Skills

# ===== 会话管理 =====
/new 或 /reset                 # 重启会话

# ===== 文件操作 =====
mkdir -p ~/.openclaw/workspace/skills/<名称>  # 创建 Skills 目录
code ~/.openclaw/workspace/skills/<名称>/SKILL.md  # 编辑