OpenClaw 技能开发完全指南：从零打造你的第一个 AI 技能

OpenClaw 技能开发完全指南：从零打造你的第一个 AI 技能

打造专属 AI 能力，让智能体为你所用

前言：为什么需要自定义技能？

OpenClaw 是一个强大的自托管 AI 智能体网关，支持 WhatsApp、Telegram、Discord、QQ 等多渠道接入。但真正让它变得无往不利的，是**技能（Skills）**系统。

想象一下：

• 没有技能的 AI：就像一个刚毕业的实习生，聪明但缺乏领域知识，每次都要从头摸索
• 有技能的 AI：就像一个经验丰富的专家团队，每个技能都是该领域的"老司机"，拿来即用

技能是什么？简单来说，它是给 AI 的"操作手册"——封装了特定领域的知识、工作流程和工具使用方法，让 AI 能够快速胜任专业任务。

技能能做什么？

• 📄 文档处理：自动生成 Word 报告、转换 Excel 数据、提取 PDF 信息
• 🌐 云服务集成：一键上传腾讯云 COS、管理阿里云 OSS、调用百度 AI
• 🔍 智能搜索：多引擎并行搜索、微信文章检索、知识库问答
• 🎨 媒体生成：视频帧提取、图片处理、文字转语音
• 🤖 开发运维：Git 管理、GitHub PR 操作、CI/CD 监控
• 💼 企业办公：飞书文档、钉钉审批、企业微信通知

这些都是已经存在的技能。而你，可以创建属于自己的技能——将你的专业知识、业务流程、常用操作封装成 AI 能力，让它为你重复劳动。

第一部分：技能解剖

1.1 技能目录结构

一个标准的技能目录结构如下：

my-skill/
├── SKILL.md (必需)
└── 可选资源/
    ├── scripts/        # 可执行脚本（Python/Bash 等）
    ├── references/     # 参考文档（API 文档、业务逻辑等）
    └── assets/         # 输出资源（模板、图标、示例文件）
​

核心组件：

• SKILL.md：技能的"身份证"和"操作手册"，包含元数据和指令
• scripts/：需要确定性和可靠性的代码（避免重复生成）
• references/：领域知识、API 文档、业务规则（按需加载）
• assets/：输出文件使用的模板、图标、样例（不加载到上下文）

1.2 SKILL.md 格式

SKILL.md 采用 YAML 前置元数据 + Markdown 指令的结构：

---
name: my-skill
description: 简洁描述技能功能和使用场景。包含"做什么"和"何时用"。
---

# 技能名称

## 使用场景

当用户需要 XXX 时，使用此技能。

## 核心功能

1. 功能一
2. 功能二

## 使用方法

具体操作步骤...
​

元数据字段说明：

• name：技能名称，使用小写字母、数字和连字符（kebab-case）
• description：触发关键词，清晰描述技能功能和使用场景
  • 包含：功能 + 触发场景
  • 不包含：使用说明（这些在 body 里）

1.3 进阶元数据：条件加载

技能支持通过 metadata 字段实现条件加载，只在满足条件时才生效：

---
name: gemini-image-gen
description: 使用 Gemini 3 Pro 生成或编辑图片
metadata:
  {
    "openclaw": {
      "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
      "primaryEnv": "GEMINI_API_KEY"
    }
  }
---
​

条件字段：

• requires.bins：必须存在的可执行文件
• requires.env：必须存在的环境变量
• requires.config：必须为真的配置路径
• os：限定操作系统（darwin/linux/win32）

第二部分：渐进式披露设计原则

2.1 核心理念

上下文窗口是公共资源。技能与系统提示、对话历史、其他技能共享 token 预算。

设计原则：

1. 默认假设 AI 已经很聪明：只添加 AI 不具备的知识
2. 挑战每一句话：这段话是否值得它的 token 成本？
3. 简洁胜于冗长：用精炼的示例代替冗长的解释

2.2 三层加载机制

OpenClaw 技能采用三层加载，实现按需消费上下文：

2.3 内容组织模式

模式 1：高层指引 + 参考文档

# PDF 处理

## 快速开始

使用 pdfplumber 提取文本：
[代码示例]

## 高级功能

- **表单填写**：参见 [FORMS.md](references/FORMS.md)
- **API 参考**：参见 [REFERENCE.md](references/REFERENCE.md)
- **示例集合**：参见 [EXAMPLES.md](references/EXAMPLES.md)
​

AI 只在需要时加载参考文档，节省上下文。

模式 2：领域分治

bigquery-skill/
├── SKILL.md (概览和导航)
└── references/
    ├── finance.md (收入、账单指标)
    ├── sales.md (机会、管道)
    └── marketing.md (活动、归因)
​

用户问销售指标时，AI 只读取 sales.md。

模式 3：渐进式细节

# DOCX 处理

## 创建文档

使用 docx-js 创建新文档。参见 [DOCX-JS.md](references/DOCX-JS.md)。

## 编辑文档

简单编辑直接修改 XML。

**追踪修订**：参见 [REDLINING.md](references/REDLINING.md)
**OOXML 详情**：参见 [OOXML.md](references/OOXML.md)
​

基础内容展示，高级内容链接。

第三部分：从零创建技能

3.1 第一步：理解技能需求

不要急着写代码！先通过具体例子理解技能要解决什么问题。

关键问题：

• 技能应该支持什么功能？
• 用户会如何使用这个技能？
• 有哪些典型查询示例？
• 什么情况下应该触发这个技能？

示例：创建 image-editor 技能

• 功能需求：旋转、裁剪、红眼移除
• 使用示例："旋转这张图片"、"移除红眼"
• 触发场景：提到图片编辑操作

3.2 第二步：规划可复用资源

分析每个示例，识别可复用的脚本、参考文档和资源文件。

示例分析：

3.3 第三步：初始化技能目录

使用 skill-creator 的初始化脚本快速创建模板：

# 创建基础模板
scripts/init_skill.py my-skill --path ~/.openclaw/workspace/skills

# 包含 scripts 和 references 目录
scripts/init_skill.py my-skill --path ~/.openclaw/workspace/skills --resources scripts,references

# 包含示例文件
scripts/init_skill.py my-skill --path ~/.openclaw/workspace/skills --examples
​

脚本会自动生成：

• 完整的目录结构
• 带有 TODO 占位符的 SKILL.md 模板
• 可选的资源目录和示例文件

3.4 第四步：实现技能

编写可复用资源

从规划的 scripts、references、assets 开始实现：

• scripts/：必须实际运行测试，确保无 bug
• references/：领域知识、API 文档、业务规则
• assets/：模板、图标、样例文件

编写 SKILL.md

元数据（前置元数据）：

---
name: docx-processor
description: Word 文档创建、编辑和分析，支持追踪修订、批注、格式保留和文本提取。当 AI 需要：创建新文档、修改内容、处理追踪修订、添加批注时使用此技能。
---
​

正文（指令）：

使用命令式/不定式形式，描述使用方法和资源引用：

# Word 文档处理

## 创建文档

使用 python-docx 创建新文档：

\`\`\`python
from docx import Document
doc = Document()
doc.add_heading("标题", level=1)
doc.save("output.docx")
\`\`\`

## 编辑文档

### 简单编辑

直接修改文本内容。

### 追踪修订

参见 [REDLINING.md](references/REDLINING.md) 了解如何处理修订模式。

## 高级功能

- **OOXML 详情**：参见 [OOXML.md](references/OOXML.md)
- **批注处理**：参见 [COMMENTS.md](references/COMMENTS.md)
​

3.5 第五步：打包技能

使用 package_skill.py 验证并打包技能：

# 验证并打包
scripts/package_skill.py ~/.openclaw/workspace/skills/my-skill

# 指定输出目录
scripts/package_skill.py ~/.openclaw/workspace/skills/my-skill ./dist
​

打包过程：

1. 自动验证技能（元数据格式、目录结构、文件组织）
2. 创建 .skill 文件（zip 格式）
3. 验证失败时报告错误并退出

安全限制： 不允许符号链接，打包失败。

3.6 第六步：迭代优化

在真实任务中使用技能，观察问题并优化：

1. 使用技能处理实际任务
2. 记录遇到的困难
3. 识别 SKILL.md 或资源需要改进的地方
4. 实施变更并重新测试

第四部分：技能部署与分发

4.1 技能加载位置

OpenClaw 从三个位置加载技能（优先级从高到低）：

1. 工作区技能：<workspace>/skills
2. 托管技能：~/.openclaw/skills
3. 打包技能：OpenClaw 安装目录

同名冲突时，优先级高的覆盖优先级低的。

4.2 ClawHub 技能市场

ClawHub 是 OpenClaw 的公共技能注册表：

• 浏览：https://clawhub.com
• 安装：clawhub install <skill-slug>
• 更新：clawhub update --all
• 同步：clawhub sync --all

默认安装到工作区 ./skills 目录。

4.3 配置覆盖

通过 ~/.openclaw/openclaw.json 配置技能：

{
  skills: {
    entries: {
      "my-skill": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "API_KEY" },
        env: {
          API_KEY: "YOUR_KEY_HERE",
        },
        config: {
          endpoint: "https://api.example.com",
          model: "pro",
        },
      },
    },
  },
}
​

配置字段：

• enabled：启用/禁用技能
• env：注入环境变量
• apiKey：便捷配置主环境变量
• config：自定义配置

第五部分：最佳实践与安全

5.1 技能设计原则

1. 简洁至上：每一行都要证明其 token 价值
2. 适度自由度：
   • 高自由度（文本指令）：多种方法有效时
   • 中自由度（伪代码/脚本）：有首选模式时
   • 低自由度（精确脚本）：易错操作、一致性关键时
3. 渐进式披露：分层加载，按需消费
4. 避免重复：信息只在 SKILL.md 或 references 中存在，不可两者皆有

5.2 文件组织原则

• SKILL.md：只包含核心流程指导和选择建议
• references/：详细参考材料、模式、配置
• scripts/：可执行代码，避免重复生成
• assets/：输出资源，不加载到上下文

5.3 安全注意事项

• 第三方技能不可信：使用前阅读代码
• 沙箱运行：不受信任输入使用沙箱
• 密钥管理：使用 skills.entries.*.apiKey 而非硬编码
• 日志安全：避免在日志中泄露敏感信息

5.4 Token 成本估算

技能对上下文的影响：

• 基础开销（≥1 技能时）：195 字符
• 每个技能：97 字符 + name + description + location

公式（字符数）：

total = 195 + Σ (97 + len(name) + len(description) + len(location))
​

粗略估算：~4 字符/token，约 24 tokens/技能（不含字段长度）。

第六部分：实战案例

案例 1：简单脚本技能

需求：旋转 PDF 文档

实现：

# scripts/rotate_pdf.py
import sys
from pypdf import PdfReader, PdfWriter

def rotate_pdf(input_path, output_path, angle=90):
    reader = PdfReader(input_path)
    writer = PdfWriter()
    
    for page in reader.pages:
        page.rotate(angle)
        writer.add_page(page)
    
    with open(output_path, "wb") as f:
        writer.write(f)

if __name__ == "__main__":
    rotate_pdf(sys.argv[1], sys.argv[2], int(sys.argv[3]))
​

SKILL.md：

---
name: pdf-rotator
description: 旋转 PDF 文档。当用户需要旋转 PDF 页面时使用此技能。
---

# PDF 旋转器

## 使用方法

运行脚本旋转 PDF：

\`\`\`bash
python scripts/rotate_pdf.py input.pdf output.pdf 90
\`\`\`

支持角度：90、180、270 度。
​

案例 2：API 集成技能

需求：查询灏天文库文集

实现：

# scripts/list_collections.py
import requests

def list_collections(name=None):
    url = "https://api.example.com/collections"
    params = {"name": name} if name else {}
    response = requests.get(url, params=params)
    return response.json()

if __name__ == "__main__":
    import json
    result = list_collections()
    print(json.dumps(result, indent=2, ensure_ascii=False))
​

SKILL.md：

---
name: ht-collections
description: 查询灏天文库文集和文档。当用户需要查询文集列表、文档列表或详情时使用此技能。
metadata:
  {
    "openclaw": {
      "requires": { "env": ["HT_API_KEY"] },
      "primaryEnv": "HT_API_KEY"
    }
  }
---

# 灏天文库查询

## 查询文集

列出所有文集：

\`\`\`bash
python scripts/list_collections.py
\`\`\`

按名称搜索：

\`\`\`bash
python scripts/list_collections.py --name "关键词"
\`\`\`

## 查询文档

参见 [DOCUMENTS.md](references/DOCUMENTS.md) 了解文档查询方法。
​

案例 3：模板资源技能

需求：生成乔布斯风格演示文稿

实现：

assets/
└── jobs-style-template/
    ├── index.html
    ├── styles.css
    └── script.js
​

SKILL.md：

---
name: jobs-style-slides
description: 生成乔布斯风格极简科技感竖屏 HTML 演示稿。当用户需要生成 PPT、演示文稿、幻灯片或要求科技风/极简风时使用此技能。
---

# 乔布斯风格演示生成

## 快速开始

1. 复制模板：`cp -r assets/jobs-style-template/ output/`
2. 编辑 `output/index.html` 填充内容
3. 在浏览器中打开

## 自定义样式

参见 [STYLING.md](references/STYLING.md) 了解样式自定义方法。
​

第七部分：进阶技巧

7.1 多框架支持

组织技能支持多个框架：

cloud-deploy/
├── SKILL.md（工作流 + 提供商选择）
└── references/
    ├── aws.md（AWS 部署模式）
    ├── gcp.md（GCP 部署模式）
    └── azure.md（Azure 部署模式）
​

用户选择 AWS 后，AI 只读取 aws.md。

7.2 插件技能

插件可以自带技能，在 openclaw.plugin.json 中声明：

{
  "skills": ["./skills/telegram", "./skills/whatsapp"]
}
​

7.3 技能观察者

启用技能文件夹监控，自动热重载：

{
  skills: {
    load: {
      watch: true,
      watchDebounceMs: 250,
    },
  },
}
​

7.4 远程节点技能

Linux 网关 + macOS 节点时，macOS 专用技能自动可用（节点连接且 system.run 允许时）。

结语

OpenClaw 技能系统是一个强大的扩展机制，让你能够：

• 🎯 封装专业知识：将你的领域知识变成 AI 能力
• 🔄 自动化重复工作：让 AI 处理重复性任务
• 🌐 集成外部服务：连接任何 API 或工具
• 🚀 构建智能工作流：组合多个技能实现复杂自动化

从简单的脚本技能开始，逐步构建你的技能库。每个技能都是 AI 的"超能力"，让它在特定领域变得无所不能。

下一步行动：

1. 确定一个重复性任务或领域知识
2. 使用 init_skill.py 初始化技能目录
3. 编写 SKILL.md 和可复用资源
4. 用 package_skill.py 打包并测试
5. 发布到 ClawHub 或私享使用

祝你打造出独一无二的 AI 技能生态系统！ 🦞