第 3 章:Skills 插件体系与批量开发
难度: ⭐ 入门 预计阅读: 20 分钟 前置章节: 第 1-2 章
📑 本章目录
- 3.1 Skills 插件体系概述
- 3.2 Skill 目录结构
- 文件作用速查表
- 3.3 SKILL.md 编写规范
- 快速开始
- 使用方法
- 配置
- 依赖
- 3.4 Skill 开发实战
- 使用方法
- 示例
- Step 5:验证注册
- 3.5 批量 Skill 管理
- 批量操作脚本
- 批量健康检查脚本
- 批量更新
- 3.6 调试与测试
- 调试问题排查流程
- 实操练习
- 练习 2:批量审计已安装 Skills
- 练习 3:为已有 Skill 编写测试
- 常见问题 (FAQ)
- 外部参考链接
- 本章小结
本章深入讲解 OpenClaw 的 Skills 插件体系——它是平台最核心的扩展机制。通过 Skills,Agent 可以获得搜索、办公集成、安全审查等各种能力。你将学会如何理解 Skill 结构、编写自己的 SKILL.md 并进行批量开发。
3.1 Skills 插件体系概述
OpenClaw 的 Skills 插件体系是平台的灵魂。每个 Skill 是一个独立目录,包含描述文件(SKILL.md)、元数据(_meta.json)、脚本和配置。
Agent 在运行时会自动加载 ~/.openclaw/workspace/skills/ 目录下的所有已安装 Skills,根据触发词或用户意图匹配合适的技能并调用。
Skills 体系架构
Agent 接收用户请求
↓
意图识别 → 匹配 Skill 触发词
↓
加载 SKILL.md → 解析指令/脚本/工具
↓
执行 Skill 逻辑(shell/python/MCP 等)
↓
返回结果给用户
当前内置分类
| 分类 | 数量 | 示例技能 | 典型使用场景 |
|---|---|---|---|
| 搜索引擎 | 5 | tavily-search, ddg-web-search, multi-search-engine | 联网搜索、信息检索 |
| Agent 框架 | 2 | proactive-agent, self-improving-agent | 主动执行、自我优化 |
| 办公集成 | 2 | gog (Google Workspace), notion | 文档协作、笔记管理 |
| 文件工具 | 2 | file-search, markdown-converter | 文件搜索、格式转换 |
| 任务自动化 | 1 | complex-task-automator | 多步骤工作流编排 |
| 安全审查 | 1 | skill-vetter | Skill 安全性扫描 |
| MCP 集成 | 1 | McPorter | MCP 服务器管理 |
| 记忆系统 | 1 | memory | 长期记忆存储与检索 |
3.2 Skill 目录结构
每个 Skill 遵循统一的目录规范:
~/.openclaw/workspace/skills/<skill-name>/
├── SKILL.md # 核心:技能描述与使用说明(必需)
├── _meta.json # 元数据(安装源、版本等)
├── scripts/ # 可执行脚本
│ ├── search.mjs # Node.js 脚本示例
│ └── core/ # Python 核心模块
├── templates/ # 配置模板
├── examples/ # 使用示例
└── hooks/ # 钩子脚本(可选)
关键文件说明
SKILL.md — 技能的入口文件,采用 YAML frontmatter + Markdown 正文:
---
name: my-skill
version: 1.0.0
description: "技能的简短描述"
author: your-name
metadata:
tags: [search, ai]
triggers:
- "搜索"
- "查找"
---
# My Skill
正文说明如何使用此技能...
_meta.json — 安装元数据:
{
"name": "my-skill",
"version": "1.0.0",
"source": "clawdhub",
"installedAt": "2026-03-01T00:00:00Z"
}
文件作用速查表
| 文件/目录 | 是否必需 | 作用 | Agent 使用方式 |
|---|---|---|---|
| SKILL.md | ✅ 必需 | 技能入口与使用说明 | 解析 frontmatter + 正文指令 |
| _meta.json | ✅ 必需 | 安装元数据 | 版本检查、来源追踪 |
| scripts/ | 可选 | 可执行脚本 | 按 SKILL.md 指令调用 |
| templates/ | 可选 | 配置模板 | 初始化时使用 |
| hooks/ | 可选 | 生命周期钩子 | 安装/卸载时触发 |
3.3 SKILL.md 编写规范
SKILL.md 是 Agent 理解和使用技能的唯一入口。编写质量直接影响技能的可用性。
Frontmatter 字段
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
name |
string | ✅ | 技能唯一标识符 |
version |
string | ✅ | 语义化版本号 |
description |
string | ✅ | 简短描述(一行) |
author |
string | ✅ | 作者名称 |
metadata.tags |
list | - | 分类标签 |
metadata.triggers |
list | - | 触发关键词 |
正文结构建议
# Skill Name
一句话说明用途。
## 快速开始
最小示例...
## 使用方法
### 命令/工具列表
详细 API 或命令...
## 配置
环境变量/参数...
## 依赖
- 系统要求: xxx
- 环境变量: xxx
编写技巧
- 触发词要准确:避免过于宽泛(如”帮我”),应使用明确的动作词
- 示例要可运行:给出完整的命令行示例
- 错误处理要说明:列出常见错误及解决方法
- 依赖要声明:明确需要哪些外部工具(如
node,python3等)
编写质量检查清单
在提交 SKILL.md 前,逐项检查:
# 1. 验证 YAML frontmatter 格式
python3 -c "
import yaml, sys
with open('SKILL.md') as f:
parts = f.read().split('---')
if len(parts) >= 3:
meta = yaml.safe_load(parts[1])
required = ['name', 'version', 'description', 'author']
missing = [k for k in required if k not in meta]
if missing:
print(f'❌ 缺少必填字段: {missing}')
sys.exit(1)
print(f'✅ frontmatter 有效: {meta[\"name\"]} v{meta[\"version\"]}')
"
# 2. 检查是否包含使用示例
grep -c '```' SKILL.md && echo "✅ 包含代码示例" || echo "⚠️ 建议添加代码示例"
# 3. 检查触发词是否定义
grep -q 'triggers' SKILL.md && echo "✅ 已定义触发词" || echo "⚠️ 建议添加触发词"
3.4 Skill 开发实战
以创建一个简单的天气查询 Skill 为例,展示完整开发流程。
Step 1:创建目录
mkdir -p ~/.openclaw/workspace/skills/weather-check
cd ~/.openclaw/workspace/skills/weather-check
Step 2:编写 SKILL.md
---
name: weather-check
version: 1.0.0
description: "查询指定城市的天气情况"
author: demo
metadata:
tags: [weather, utility]
triggers:
- "天气"
- "weather"
---
# Weather Check
查询指定城市的当前天气。
## 使用方法
\```bash
curl -s "https://wttr.in/Beijing?format=3"
\```bash
## 示例
- 查询北京天气: `curl -s "https://wttr.in/Beijing?format=3"`
- 查询上海天气: `curl -s "https://wttr.in/Shanghai?format=3"`
Step 3:创建元数据文件
cat > _meta.json << 'EOF'
{
"name": "weather-check",
"version": "1.0.0",
"source": "local",
"installedAt": "2026-03-06T00:00:00Z"
}
EOF
Step 4:测试运行
# 直接运行 Skill 中的命令
curl -s "https://wttr.in/Beijing?format=3"
# 输出: Beijing: ⛅️ +22°C
# 测试多个城市
for city in Beijing Shanghai Wuhan; do
echo -n "$city: "
curl -s "https://wttr.in/$city?format=3"
done
Step 5:验证注册
将 Skill 放入 ~/.openclaw/workspace/skills/ 后,Agent 会在下次会话中自动加载。
# 验证 Skill 目录结构完整性
ls -la ~/.openclaw/workspace/skills/weather-check/
# 预期输出: SKILL.md _meta.json
# 使用 doctor 检查加载状态
openclaw doctor
3.5 批量 Skill 管理
当拥有多个 Skills 时,需要高效的批量管理方法。随着项目规模增长,你可能会安装数十个甚至更多的 Skills,手动逐一管理既耗时又容易遗漏。本节介绍一系列脚本和命令,帮助你快速列出、检查、更新和清理所有已安装的 Skills,从而保证工作环境的一致性和稳定性。
列出已安装 Skills
ls -la ~/.openclaw/workspace/skills/
# 或使用 find-skills 工具
npx skills check
批量操作脚本
#!/bin/bash
# list-skills.sh — 列出所有 Skill 及其版本
for skill_dir in ~/.openclaw/workspace/skills/*/; do
skill_name=$(basename "$skill_dir")
if [ -f "$skill_dir/SKILL.md" ]; then
version=$(grep -oP 'version:\s*\K[\d.]+' "$skill_dir/SKILL.md" | head -1)
echo "$skill_name: v${version:-unknown}"
fi
done
批量健康检查脚本
#!/bin/bash
# check-skills.sh — 批量验证所有 Skill 的完整性
PASS=0; FAIL=0
for skill_dir in ~/.openclaw/workspace/skills/*/; do
name=$(basename "$skill_dir")
if [ ! -f "$skill_dir/SKILL.md" ]; then
echo "❌ $name: 缺少 SKILL.md"
((FAIL++))
elif [ ! -f "$skill_dir/_meta.json" ]; then
echo "⚠️ $name: 缺少 _meta.json"
((FAIL++))
else
echo "✅ $name"
((PASS++))
fi
done
echo "---"
echo "通过: $PASS 失败: $FAIL 总计: $((PASS+FAIL))"
批量更新
当 ClawHub 上的 Skill 发布了新版本时,你可以使用以下命令一键更新所有已安装的 Skills。更新前建议先运行健康检查脚本,确认当前环境无异常;更新后同样执行一次检查,确保新版本没有引入兼容性问题。对于生产环境,推荐先在测试工作空间中验证更新效果后再应用到主环境。
npx skills update # 检查并更新所有已安装 Skills
Skill 禁用与启用
在 ~/.openclaw/openclaw.json 中控制:
{
"skills": {
"entries": {
"tavily": { "enabled": true },
"ddg-search": { "enabled": false }
}
}
}
3.6 调试与测试
开发 Skills 时的调试方法和测试策略。
查看 Skill 加载状态
openclaw doctor # 包含 Skills 加载检测
常见调试方式
- 直接执行脚本:测试 Skill 中的脚本能否独立运行
node ~/.openclaw/workspace/skills/tavily-search/scripts/search.mjs "test query" - 检查 YAML frontmatter:确保格式正确
head -20 ~/.openclaw/workspace/skills/my-skill/SKILL.md - 查看 Agent 日志:观察 Skill 匹配和执行过程
openclaw logs --follow
单元测试建议
为 Skill 添加测试脚本:
# scripts/test.sh
#!/bin/bash
echo "Testing weather-check skill..."
RESULT=$(curl -s "https://wttr.in/Beijing?format=3" 2>/dev/null)
if [ -n "$RESULT" ]; then
echo "✅ PASS: Got result: $RESULT"
else
echo "❌ FAIL: No result"
exit 1
fi
调试问题排查流程
| 步骤 | 操作 | 预期结果 |
|---|---|---|
| 1 | ls ~/.openclaw/workspace/skills/<name>/SKILL.md |
文件存在 |
| 2 | head -5 SKILL.md,检查 --- 分隔符 |
YAML frontmatter 格式正确 |
| 3 | python3 -c "import yaml; ..." 验证 YAML |
无解析错误 |
| 4 | 直接执行脚本命令 | 脚本输出正常 |
| 5 | openclaw doctor |
Skill 显示已加载 |
| 6 | openclaw logs --follow + 发送测试请求 |
日志显示 Skill 被匹配 |
进阶:插件架构原理
深入理解 Skills 插件的内部机制,有助于开发更高质量的自定义插件:
- 插件加载机制:Gateway 启动时扫描
workspace/skills/下所有目录,解析manifest.json构建技能注册表,运行时通过正则匹配和语义相似度双重策略选择最佳 Skill。 - 执行沙箱:每个 Skill 脚本在独立子进程中执行,通过 stdin/stdout 与主进程通信,超时自动 kill,默认超时 30 秒可通过
timeout字段配置。 - 依赖隔离:每个 Skill 可拥有独立的
node_modules或 Python venv,避免不同插件之间的依赖冲突。 - 批量开发模式:使用
openclaw skill scaffold --batch可从模板批量生成多个 Skill 骨架,配合openclaw skill test --all进行批量验证。 - 热更新支持:修改 Skill 文件后无需重启 Gateway,系统自动检测变更并重新加载,开发调试效率高。
注意事项与常见错误
开发和管理 Skills 时需要注意以下常见陷阱:
| 常见错误 | 表现 | 排查方法 |
|---|---|---|
manifest.json 格式错误 |
Skill 未被加载 | 使用 openclaw doctor 检查,确认 JSON 语法正确 |
| 触发词冲突 | 错误的 Skill 被调用 | 检查多个 Skill 的 triggers 是否重叠,提高关键词区分度 |
| 脚本权限不足 | 执行报 Permission denied |
确认脚本有执行权限 chmod +x run.sh |
| 依赖未安装 | 运行时报 MODULE_NOT_FOUND |
在 Skill 目录下执行 npm install 安装依赖 |
⚠️ 最佳实践:开发新 Skill 前务必运行
openclaw skill list确认不与已有 Skill 冲突,每个 Skill 应包含完整的 README 和测试用例。
进阶:插件架构与加载原理
理解 Skills 的内部加载机制有助于开发高性能插件:
| 阶段 | 动作 | 时机 |
|---|---|---|
| 发现 | 扫描 skills/ 目录下所有 SKILL.md |
Gateway 启动时 |
| 注册 | 解析 frontmatter,注册工具和触发词 | Gateway 启动时 |
| 加载 | 读取 handler.ts/handler.js 并编译 |
首次调用时(懒加载) |
| 执行 | 调用 handler 导出函数,传入上下文 | 每次工具调用时 |
这种懒加载设计意味着安装大量 Skills 不会影响启动速度。
注意事项与常见错误
开发 Skills 时常见的错误:
| 常见错误 | 后果 | 正确做法 |
|---|---|---|
| SKILL.md 格式错误 | Skill 不被识别 | 使用 npx skills validate 验证 |
| handler 未导出默认函数 | 调用时报错 | 确保 export default 正确导出 |
| 未声明依赖 | 其他环境安装后报错 | 在 SKILL.md 中声明 dependencies |
进阶:插件架构与加载原理
理解 Skills 加载机制有助于开发高性能插件:
| 阶段 | 动作 | 时机 |
|---|---|---|
| 发现 | 扫描 skills 目录 SKILL.md | 启动时 |
| 注册 | 解析 frontmatter 和工具 | 启动时 |
| 加载 | 读取 handler 并编译 | 首次调用时 |
| 执行 | 调用导出函数 | 每次工具调用 |
注意事项与常见错误
开发 Skills 常见错误:
| 常见错误 | 后果 | 正确做法 |
|---|---|---|
| SKILL.md 格式错误 | 不被识别 | 使用 npx skills validate |
| handler 未导出默认函数 | 调用报错 | 确保 export default |
| 未声明依赖 | 环境迁移失败 | 在 SKILL.md 声明 |
实操练习
练习 1:创建一个 IP 查询 Skill
按照以下步骤创建一个查询公网 IP 的 Skill:
# 第 1 步:创建目录
mkdir -p ~/.openclaw/workspace/skills/ip-check
cd ~/.openclaw/workspace/skills/ip-check
# 第 2 步:编写 SKILL.md(使用 tee 创建文件)
tee SKILL.md << 'EOF'
---
name: ip-check
version: 1.0.0
description: "查询当前服务器的公网 IP 地址"
author: learner
metadata:
tags: [network, utility]
triggers:
- "IP"
- "公网地址"
---
查询当前服务器的公网 IP 地址和地理位置信息。
使用命令: curl -s https://ipinfo.io/json
示例输出: {"ip": "1.2.3.4", "city": "Wuhan", "country": "CN"}
EOF
# 第 3 步:创建 _meta.json
cat > _meta.json << 'METAEOF'
{"name":"ip-check","version":"1.0.0","source":"local","installedAt":"2026-03-06T00:00:00Z"}
METAEOF
# 第 4 步:测试
curl -s https://ipinfo.io/json | python3 -m json.tool
# 第 5 步:验证
openclaw doctor
练习 2:批量审计已安装 Skills
编写脚本检查所有已安装 Skill 的健康状态:
# 运行批量检查
for dir in ~/.openclaw/workspace/skills/*/; do
name=$(basename "$dir")
has_skill=$([ -f "$dir/SKILL.md" ] && echo "✅" || echo "❌")
has_meta=$([ -f "$dir/_meta.json" ] && echo "✅" || echo "❌")
echo "$name SKILL.md=$has_skill _meta.json=$has_meta"
done
练习 3:为已有 Skill 编写测试
选择一个已安装的 Skill,为其创建 scripts/test.sh 测试脚本:
# 示例:为 ddg-web-search 编写测试
cd ~/.openclaw/workspace/skills/ddg-web-search
mkdir -p scripts
cat > scripts/test.sh << 'EOF'
#!/bin/bash
echo "=== Testing ddg-web-search ==="
# 测试 1:检查 SKILL.md 存在
[ -f "../SKILL.md" ] && echo "✅ SKILL.md 存在" || echo "❌ SKILL.md 缺失"
# 测试 2:检查 frontmatter 格式
python3 -c "
import yaml
with open('../SKILL.md') as f:
parts = f.read().split('---')
meta = yaml.safe_load(parts[1])
assert 'name' in meta, 'Missing name'
print('✅ Frontmatter 有效:', meta['name'])
" || echo "❌ Frontmatter 格式错误"
# 测试 3:检查依赖命令
command -v curl >/dev/null && echo "✅ curl 可用" || echo "❌ curl 未安装"
echo "=== 测试完成 ==="
EOF
chmod +x scripts/test.sh
bash scripts/test.sh
常见问题 (FAQ)
Q1: SKILL.md 格式不对怎么办?
A: 运行 openclaw doctor 可自动检测格式问题。最常见的错误是 YAML frontmatter 没有用 --- 正确包裹,或者字段类型不对(如 tags 应该是列表而非字符串)。可以用以下命令快速验证:
python3 -c "import yaml; print(yaml.safe_load(open('SKILL.md').read().split('---')[1]))"
Q2: Skill 没有被 Agent 识别怎么排查?
A: 按以下顺序检查:
- 确认目录在
~/.openclaw/workspace/skills/下 - 确认
SKILL.md文件名大小写正确 - 检查
openclaw.json中是否被enabled: false禁用 - 运行
openclaw gateway reload重新加载 - 查看
openclaw logs --follow观察加载过程
Q3: 如何将 Skill 发布到 ClawHub?
A: 参见下一章《Skills 安装与管理实践》,使用 npx skills add 命令发布。发布前需确保 SKILL.md 包含完整的 frontmatter 字段和使用示例。
Q4: 脚本执行权限不足怎么办?
A: 为脚本添加可执行权限:
chmod +x ~/.openclaw/workspace/skills/<name>/scripts/*.sh
# 验证
ls -la ~/.openclaw/workspace/skills/<name>/scripts/
Q5: 多个 Skill 的触发词冲突了怎么办?
A: Agent 会按照匹配度和优先级选择最合适的 Skill。如果冲突严重,建议:
- 使用更具体的触发词(如”DDG 搜索”而非”搜索”)
- 在
openclaw.json中禁用不需要的 Skill - 在请求中明确指定 Skill 名称
外部参考链接
- OpenClaw GitHub 仓库 — 源码与文档
- YAML 语法规范 — SKILL.md frontmatter 所用格式
- 语义化版本 (SemVer) — 版本号命名规范
- ClawHub 技能市场 — 发现和分享 Skills
- MCP 协议规范 — 理解 MCP 集成型 Skill
参考来源
| 来源 | 链接 | 可信度 | 说明 |
|---|---|---|---|
| OpenClaw 官方文档 | https://docs.OpenClaw.com | A | 安装, 配置, 命令 |
| OpenClaw GitHub 仓库 | https://github.com/anthropics/OpenClaw | A | 源码, Issues, Release |
| ClawHub Skills 平台 | https://hub.OpenClaw.com | A | Skills, 市场, 安装 |
本章小结
本章系统讲解了 OpenClaw Skills 插件体系的核心知识:
- 体系架构:理解了 Skill 从意图匹配到执行返回的完整工作流
- 目录结构:掌握了 SKILL.md、_meta.json 等关键文件的规范
- 编写规范:学会了 YAML frontmatter 和正文的编写标准与质量检查方法
- 开发实战:通过天气查询 Skill 实例走通了完整开发流程
- 批量管理:掌握了列出、更新、禁用/启用等批量操作
- 调试测试:了解了 Skill 开发中的排错与测试策略
遇到问题时,善用 openclaw doctor 进行诊断,配合 openclaw logs --follow 追踪 Agent 加载与匹配 Skill 的过程。