技能开发完全指南

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

技能是 OpenClaw 最核心的扩展机制。本节从零开始，带你走完技能开发的完整流程——从理解技能结构、掌握设计原则，到动手创建第一个技能、打包发布。读完之后，你就能把自己的专业知识和工作流程封装成 AI 能力，让 OpenClaw 在你的领域里变成"专家"。

核心问题

完成本节学习后，你将能够：

1. 描述技能目录的标准结构和每个组成部分的作用
2. 编写规范的 SKILL.md 文件（元数据 + 指令正文）
3. 运用渐进式披露原则组织技能内容
4. 使用初始化和打包脚本完成技能开发流程
5. 配置技能的加载位置和条件加载规则

一、为什么需要自定义技能

OpenClaw 开箱就能用——接上 AI 模型，连上通信渠道，基本的对话能力就有了。但你会发现，AI 在很多专业场景下的表现并不理想：它不知道你们公司的报销流程，不了解你的代码库结构，不清楚你写报告的格式要求。

原因很简单：AI 模型的训练数据是通用的，它缺乏你的领域知识。

技能就是解决这个问题的。打个比方：

• 没有技能的 AI：像一个刚入职的实习生，脑子好使但对业务一无所知，每件事都要从头教
• 有技能的 AI：像一本翻开的操作手册摆在面前，遇到特定任务直接按手册执行

技能本质上就是给 AI 的"操作手册"——封装了特定领域的知识、工作流程和工具使用方法。

技能能覆盖的场景很广：

二、技能目录结构

一个标准的技能目录长这样：

图：技能加载流程

各组成部分的职责：

💡 提示：一个常见的误区是把所有内容都塞进 SKILL.md。记住，上下文窗口是公共资源——技能与系统提示、对话历史、其他技能共享 token 预算。SKILL.md 应该只放核心流程指引，详细的参考资料放到 references/ 目录，让 AI 在需要时再去读取。

三、SKILL.md 格式详解

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

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

# 技能名称

## 使用场景

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

## 核心功能

1. 功能一
2. 功能二

## 使用方法

具体操作步骤...
​

3.1 元数据字段

description 字段非常关键——它决定了 AI 什么时候会想到使用这个技能。好的 description 应该包含两个信息：这个技能做什么，以及在什么情况下使用它。

3.2 条件加载

通过 metadata 字段可以实现条件加载，只在满足特定条件时技能才会生效：

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

⚠️ 注意：如果条件加载配置有误，技能可能永远不会被触发。调试技能不生效的问题时，先检查 metadata 中的条件是否满足。

四、渐进式披露设计原则

渐进式披露是技能设计中最重要的原则。它的核心思想是：上下文窗口是公共资源，每一段内容都要证明它的 token 价值。

4.1 三层加载机制

4.2 三种内容组织模式

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

在 SKILL.md 中放基础操作指引，高级功能通过链接引用 references 目录下的文档：

# PDF 处理

## 快速开始

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

## 高级功能

- 表单填写：参见 references/FORMS.md
- API 参考：参见 references/REFERENCE.md
​

模式二：领域分治

把一个大技能按领域拆分成多个参考文档，AI 根据用户问题只读取相关的那个：

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

用户问销售指标时，AI 只读取 sales.md，不用把三个文件全加载进来。

模式三：渐进式细节

基础内容直接展示，高级内容链接到参考文档：

# DOCX 处理

## 创建文档
使用 python-docx 创建新文档。参见 references/DOCX-JS.md。

## 编辑文档
简单编辑直接修改 XML。
追踪修订：参见 references/REDLINING.md
OOXML 详情：参见 references/OOXML.md
​

五、从零创建一个技能

5.1 明确需求

不要急着写代码。先想清楚几个问题：

• 这个技能要解决什么问题？
• 用户会怎么触发这个技能？
• 哪些操作是每次都要重复做的？
• 哪些知识是 AI 本身不具备的？

以创建一个 PDF 旋转技能为例：

5.2 规划可复用资源

分析需求后，识别出可复用的部分：

5.3 初始化技能目录

使用初始化脚本快速创建模板：

scripts/init_skill.py pdf-rotator --path ~/.openclaw/workspace/skills --resources scripts,references
​

脚本会自动生成完整的目录结构和带有占位符的 SKILL.md 模板。

5.4 编写技能内容

先写可复用脚本：

# 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 页面：

    python scripts/rotate_pdf.py input.pdf output.pdf 90

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

## 批量旋转

对多页 PDF 中指定页面旋转：参见 references/BATCH_ROTATE.md
​

5.5 打包和验证

scripts/package_skill.py ~/.openclaw/workspace/skills/pdf-rotator
​

打包过程会自动验证元数据格式、目录结构和文件组织。验证通过后生成 .skill 文件（zip 格式）。

⚠️ 注意：打包过程不允许符号链接。如果技能目录中包含符号链接，打包会失败。请确保所有文件都是实际文件。

六、技能部署与分发

6.1 加载位置

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

6.2 ClawHub 技能市场

ClawHub 是 OpenClaw 的公共技能注册表，可以浏览、安装和更新社区贡献的技能：

# 安装技能
clawhub install weather-asker

# 更新所有技能
clawhub update --all

# 同步技能
clawhub sync --all
​

6.3 配置覆盖

通过配置文件可以控制技能的行为：

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

💡 提示：技能开发是一个迭代过程。第一版不需要做到完美——先跑起来，在真实任务中使用，观察 AI 在哪些地方做得不好，然后针对性地优化 SKILL.md 的指令或补充参考文档。

七、安全与最佳实践

7.1 设计原则

7.2 安全注意事项

• 第三方技能不可信——安装前务必阅读代码
• 不受信任的输入使用沙箱运行
• 密钥通过配置注入，不要硬编码在 SKILL.md 中
• 避免在日志中泄露敏感信息

7.3 Token 成本估算

技能对上下文的影响可以用以下公式估算：

总成本 = 195 + 每个技能(97 + name长度 + description长度 + location长度)
​

粗略估算：大约 4 个字符对应 1 个 token，每个技能的基础开销约 24 个 token（不含字段内容长度）。

本节要点

• 技能目录由 SKILL.md（必需）和 scripts/references/assets（可选）组成
• SKILL.md 的 description 字段决定了 AI 何时触发该技能，需要同时包含"做什么"和"何时用"
• 渐进式披露是核心设计原则：三层加载、按需消费、简洁至上
• 开发流程：明确需求 → 规划资源 → 初始化目录 → 编写内容 → 打包验证 → 部署使用
• 技能加载有三个位置，优先级从高到低分别是工作区、用户目录、安装目录