全新OpenClaw Skills 开发实战：从零构建 AI Agent 能力模块
摘要：本文系统讲解 OpenClaw Skills 的完整开发流程，从创建、编写 SKILL.md、配置触发机制到调试验证。适合希望扩展 AI Agent 能力、构建领域专用工具链的中高级开发者。读完后你将掌握 Skills 的核心机制、开发规范和实战调试方法。
【AI辅助创作声明：本文由 AI 辅助整理与撰写，内容已经过人工审校与调整。】
OpenClaw Skills 是一套模块化的能力扩展机制，允许开发者为 AI Agent 注入领域知识、工具集成和专用工作流。与传统插件系统不同，Skills 通过结构化的 Markdown 文档（SKILL.md）向 LLM 提供上下文指令，使 Agent 在特定场景下自动激活相应能力。
这套机制解决了三个核心问题：领域知识注入（如企业内部 API 规范）、工具链集成（如 PDF 处理、数据库操作）、复杂工作流封装（如多步骤的数据分析流程）。对于需要构建垂直领域 Agent 或自动化复杂任务的开发者，Skills 提供了比 Prompt Engineering 更稳定、可维护的解决方案。
常见痛点包括：Agent 无法理解企业特定术语、重复性任务需要每次手动指导、跨工具协作流程难以标准化。Skills 通过将这些知识固化为可复用模块，让 Agent 在遇到相关场景时自动加载正确的上下文和工具。
Skills 开发完整流程
步骤 1：创建 Skill 目录结构
Skills 默认存放在工作区的 skills/ 目录下。创建新 Skill 时需遵循标准目录结构：
mkdir -p ~/.easyclaw/workspace/skills/my-skill
cd ~/.easyclaw/workspace/skills/my-skill
标准目录布局：
my-skill/
├── SKILL.md # 必需，核心指令文件（<200行）
├── scripts/ # 可选，可执行脚本
├── references/ # 可选，详细文档（按需加载）
└── assets/ # 可选，模板、配置等静态资源
关键约束：
SKILL.md文件名必须全大写- 主文件控制在 200 行以内（超出部分拆分到 references/）
- 脚本优先使用 Python 或 Node.js（跨平台兼容性更好）
步骤 2：编写 SKILL.md 核心文件
SKILL.md 由两部分组成：YAML Frontmatter（元数据）和 Markdown 指令（执行逻辑）。
2.1 定义 Frontmatter
---
name: pdf-processor
description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when users mention PDFs, forms, or document extraction.
metadata: {"easyclaw": {"requires": {"bins": ["python"]}, "primaryEnv": "PDF_API_KEY"}}
---
字段说明：
- name：kebab-case 格式，最多 64 字符，作为 Skill 唯一标识
- description：触发条件描述，最多 1024 字符，直接影响 Agent 是否激活此 Skill
- metadata.easyclaw.requires：依赖声明（二进制工具、环境变量、配置项）
触发机制核心：description 字段是 Agent 判断是否使用 Skill 的主要依据。需包含：功能描述 + 触发场景 + 关键词。避免模糊表述如"帮助处理文档"，应写明具体能力和使用时机。
2.2 编写指令内容
# PDF Processing Skill
## 文本提取
使用 pdfplumber 提取 PDF 文本：
```python
import pdfplumber
with pdfplumber.open("input.pdf") as pdf:
text = pdf.pages[0].extract_text()
print(text)
表格提取
with pdfplumber.open("input.pdf") as pdf:
tables = pdf.pages[0].extract_tables()
for table in tables:
print(table)
常见问题
问题 1：中文乱码
- 原因：PDF 使用非标准字体编码
- 解决：添加 encoding='utf-8' 参数或使用 PyMuPDF
问题 2：表格识别不准确
- 原因：表格无明确边框线
- 解决：调整 table_settings 参数中的 vertical_strategy 和 horizontal_strategy
问题 3：大文件内存溢出
- 原因：一次性加载所有页面
- 解决：逐页处理，使用生成器模式
**编写原则**：
- 直接给出可执行代码，不写"你可以尝试"等废话
- 每个功能模块提供完整示例（输入 → 处理 → 输出）
- 常见报错必须给出具体原因和解决方案
- 路径使用正斜杠 `/`（Windows 兼容）
### 步骤 3：配置依赖和门控规则
通过 `metadata.easyclaw.requires` 声明 Skill 的运行前置条件：
```yaml
metadata: {
"easyclaw": {
"requires": {
"bins": ["python", "pdfplumber"],
"env": ["PDF_API_KEY"],
"config": ["pdf.enableOcr"]
},
"primaryEnv": "PDF_API_KEY",
"os": ["darwin", "linux"]
}
}
门控字段说明：
- bins：必需的命令行工具（在 PATH 中检查）
- anyBins：至少存在一个即可
- env：必需的环境变量
- config：必需的配置项（在 ~/.easyclaw/easyclaw.json 中）
- os：限定操作系统（darwin/linux/win32）
加载时机：Agent 启动时会检查所有 Skills 的 requires 条件，不满足的 Skill 不会被加载到上下文中。
步骤 4：实现可执行脚本（可选）
对于复杂逻辑，建议封装为独立脚本：
# scripts/extract_pdf.py
import sys
import pdfplumber
def extract_text(pdf_path):
with pdfplumber.open(pdf_path) as pdf:
return "\n".join(page.extract_text() for page in pdf.pages)
if __name__ == "__main__":
if len(sys.argv) < 2:
print("Usage: python extract_pdf.py <pdf_file>")
sys.exit(1)
result = extract_text(sys.argv[1])
print(result)
在 SKILL.md 中引用：
## 批量提取
运行脚本提取所有页面文本：
```bash
python {baseDir}/scripts/extract_pdf.py input.pdf
**注意**：{baseDir} 会在运行时替换为 Skill 目录的绝对路径。
### 步骤 5：结构验证
使用官方验证工具检查 Skill 结构：
```bash
python scripts/quick_validate.py ~/.easyclaw/workspace/skills/my-skill
验证项：
- SKILL.md 文件存在性
- YAML Frontmatter 格式正确性
- name 字段符合 kebab-case 规范
- description 长度不超过 1024 字符
- 无非法 frontmatter 字段
常见报错：
错误 1：Invalid YAML frontmatter
- 原因：YAML 语法错误（缩进、引号不匹配）
- 解决：使用 YAML 在线校验工具检查格式
错误 2：name must be kebab-case
- 原因：name 包含大写字母或下划线
- 解决：改为小写字母 + 连字符，如 pdf-processor
错误 3：description contains angle brackets
- 原因：description 中使用了 < 或 >
- 解决：移除或替换为文字描述
步骤 6：注册 Skill
验证通过后，使用注册脚本将 Skill 安装到系统：
工作区 Skill（单 Agent 使用）：
python scripts/easyclaw_register_skill.py ~/.easyclaw/workspace/skills/my-skill --workspace ~/.easyclaw/workspace
全局 Skill（所有 Agent 共享）：
python scripts/register_imported_skill.py ~/.easyclaw/workspace/skills/my-skill
区别：
- 工作区注册：Skill 安装到
<workspace>/skills/，注册后源目录会被删除 - 全局注册：Skill 安装到
~/.easyclaw/skills/，源目录保留
步骤 7：调试与测试
7.1 验证 Skill 加载
启动 Agent 后检查 Skill 是否被识别：
easyclaw agent --message "list available skills"
如果 Skill 未出现，检查：
- 依赖项是否满足（bins、env、config）
- description 是否过于模糊
- 是否存在同名 Skill 冲突（优先级：workspace > ~/.easyclaw > 内置）
7.2 触发测试
使用包含触发关键词的指令测试：
easyclaw agent --message "extract text from report.pdf"
观察 Agent 是否：
- 正确识别需要使用此 Skill
- 按照 SKILL.md 中的指令执行
- 调用了正确的脚本或工具
7.3 日志分析
查看详细执行日志：
tail -f ~/.easyclaw/logs/agent.log
关键日志标识：
[Skills] Loaded: pdf-processor— Skill 加载成功[Skills] Filtered out: pdf-processor (missing bin: pdfplumber)— 依赖不满足[Agent] Using skill: pdf-processor— Skill 被激活
常见调试问题：
问题 1：Skill 加载但不触发
- 原因：description 与用户指令关键词不匹配
- 解决：在 description 中补充更多触发场景和同义词
问题 2：脚本执行失败
- 原因：路径错误或权限不足
- 解决：检查 {baseDir} 替换是否正确，确保脚本有执行权限（chmod +x）
问题 3：环境变量未生效
- 原因：配置文件中未设置或 Agent 未重启
- 解决：在
~/.easyclaw/easyclaw.json中添加：
{
"skills": {
"entries": {
"pdf-processor": {
"enabled": true,
"env": {
"PDF_API_KEY": "your-key-here"
}
}
}
}
}
实战案例：构建数据库查询 Skill
场景描述
需要让 Agent 能够查询 PostgreSQL 数据库，自动生成 SQL、执行查询并格式化结果。
实现步骤
1. 创建目录
mkdir -p ~/.easyclaw/workspace/skills/postgres-query
cd ~/.easyclaw/workspace/skills/postgres-query
2. 编写 SKILL.md
---
name: postgres-query
description: Queries PostgreSQL databases, generates SQL from natural language, formats results as tables. Use when users ask to query databases, check data, or mention PostgreSQL/SQL.
metadata: {"easyclaw": {"requires": {"bins": ["psql"], "env": ["DATABASE_URL"]}}}
---
# PostgreSQL Query Skill
## 连接数据库
使用环境变量 `DATABASE_URL` 连接：
```bash
psql $DATABASE_URL -c "SELECT version();"
查询数据
psql $DATABASE_URL -c "SELECT * FROM users LIMIT 10;"
格式化输出
使用 -t 去除表头，-A 去除对齐：
psql $DATABASE_URL -t -A -c "SELECT id, name FROM users;"
常见问题
问题 1：连接超时
- 检查 DATABASE_URL 格式：postgresql://user:pass@host:5432/dbname
- 确认网络可达性和防火墙规则
问题 2：权限不足
- 确保数据库用户有 SELECT 权限
- 使用
GRANT SELECT ON ALL TABLES IN SCHEMA public TO user;
问题 3：中文显示乱码
- 设置客户端编码：
SET client_encoding TO 'UTF8';
#### 3. 创建查询脚本
```python
# scripts/query.py
import os
import sys
import psycopg2
def execute_query(sql):
conn = psycopg2.connect(os.environ['DATABASE_URL'])
cur = conn.cursor()
cur.execute(sql)
results = cur.fetchall()
cur.close()
conn.close()
return results
if __name__ == "__main__":
if len(sys.argv) < 2:
print("Usage: python query.py '<SQL>'")
sys.exit(1)
sql = sys.argv[1]
results = execute_query(sql)
for row in results:
print("\t".join(str(col) for col in row))
4. 配置环境变量
编辑 ~/.easyclaw/easyclaw.json：
{
"skills": {
"entries": {
"postgres-query": {
"enabled": true,
"env": {
"DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
}
}
}
}
}
5. 验证与注册
python scripts/quick_validate.py ~/.easyclaw/workspace/skills/postgres-query
python scripts/easyclaw_register_skill.py ~/.easyclaw/workspace/skills/postgres-query --workspace ~/.easyclaw/workspace
6. 测试执行
easyclaw agent --message "查询 users 表中最近注册的 10 个用户"
预期输出：
使用 postgres-query Skill 执行查询...
执行 SQL: SELECT * FROM users ORDER BY created_at DESC LIMIT 10;
结果：
ID Name Email Created At
1001 张三 zhangsan@example.com 2026-04-10 14:23:11
1002 李四 lisi@example.com 2026-04-10 15:01:45
...
关键点：
- Agent 自动识别"查询"、"users 表"等关键词，激活 Skill
- 根据自然语言生成正确的 SQL 语句
- 调用脚本执行查询并格式化输出
- 处理错误情况（连接失败、权限不足等）
如果你不想操作以上步骤，可以试试Easyclaw，它有自己的技能库，可一键调用。
下载体验：https://easyclaw.cn/?f=209
两者的定位互补：OpenClaw 适合个人开发者快速验证想法，EasyClaw 适合需要稳定性、安全性和协作能力的企业场景。
总结
- Skills 是 OpenClaw 的能力扩展机制，通过 SKILL.md 向 Agent 注入领域知识和工具集成
- 核心开发流程：创建目录 → 编写 SKILL.md（frontmatter + 指令）→ 配置依赖 → 验证 → 注册 → 调试
- 触发机制依赖 description 字段，需明确写出功能、场景和关键词
- 调试重点：检查依赖满足情况、验证触发关键词匹配、分析执行日志
- 生产环境建议使用 EasyClaw，获得更好的管理和调试体验
掌握 Skills 开发后，你可以将任何领域知识或工具链封装为可复用模块，让 Agent 在特定场景下自动激活正确的能力，从而构建真正实用的垂直领域 AI 助手。
标签：OpenClaw Skills / OpenClaw / EasyClaw / 技能开发 / AI Agent / 扩展机制 / 模块化开发
浙公网安备 33010602011771号