大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



摘要：本文系统讲解 OpenClaw Skills 的完整开发流程，从创建、编写 SKILL.md、配置触发机制到调试验证。适合希望扩展 AI Agent 能力、构建领域专用工具链的中高级开发者。读完后你将掌握 Skills 的核心机制、开发规范和实战调试方法。

【AI辅助创作声明：本文由 AI 辅助整理与撰写，内容已经过人工审校与调整。】

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（跨平台兼容性更好）

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) 

• 原因：PDF 使用非标准字体编码
• 解决：添加 encoding='utf-8' 参数或使用 PyMuPDF

• 原因：表格无明确边框线
• 解决：调整 table_settings 参数中的 vertical_strategy 和 horizontal_strategy

• 原因：一次性加载所有页面
• 解决：逐页处理，使用生成器模式

 编写原则： - 直接给出可执行代码，不写"你可以尝试"等废话 - 每个功能模块提供完整示例（输入 → 处理 → 输出） - 常见报错必须给出具体原因和解决方案 - 路径使用正斜杠 `/`（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 不会被加载到上下文中。

对于复杂逻辑，建议封装为独立脚本：

# scripts/extract_pdf.py import sys import pdfplumber def extract_text(pdf_path): with pdfplumber.open(pdf_path) as pdf: return " ".join(page.extract_text() for page in pdf.pages) if __name__ == "__main__": if len(sys.argv) < 2: print("Usage: python extract_pdf.py 
  
    
    
      ") 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 中使用了 < 或 >
• 解决：移除或替换为文字描述

验证通过后，使用注册脚本将 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 安装到 /skills/ ，注册后源目录会被删除
• 全局注册：Skill 安装到 ~/.easyclaw/skills/，源目录保留

7.1 验证 Skill 加载

启动 Agent 后检查 Skill 是否被识别：

easyclaw agent --message "list available skills" 

如果 Skill 未出现，检查：

1. 依赖项是否满足（bins、env、config）
2. description 是否过于模糊
3. 是否存在同名 Skill 冲突（优先级：workspace > ~/.easyclaw > 内置）

7.2 触发测试

使用包含触发关键词的指令测试：

easyclaw agent --message "extract text from report.pdf" 

观察 Agent 是否：

1. 正确识别需要使用此 Skill
2. 按照 SKILL.md 中的指令执行
3. 调用了正确的脚本或工具

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" } } } } } 

需要让 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;" 

• 检查 DATABASE_URL 格式：postgresql://user:pass@host:5432/dbname
• 确认网络可达性和防火墙规则

• 确保数据库用户有 SELECT 权限
• 使用 GRANT SELECT ON ALL TABLES IN SCHEMA public TO user;

• 设置客户端编码：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 ' 
  
    
    
      '") sys.exit(1) sql = sys.argv[1] results = execute_query(sql) for row in results: print(" ".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 张三  2026-04-10 14:23:11 1002 李四  2026-04-10 15:01:45 ... 

关键点：

• Agent 自动识别"查询"、"users 表"等关键词，激活 Skill
• 根据自然语言生成正确的 SQL 语句
• 调用脚本执行查询并格式化输出
• 处理错误情况（连接失败、权限不足等）

下载体验：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 / 扩展机制 / 模块化开发