【技能篇】OpenClaw Skill 详解：给 AI 装上“专业外挂“

如果说 OpenClaw 是一个 AI 员工，那 Skill 就是它的岗位培训手册。没有 Skill，它只是个聪明但啥也不会干的"嘴强王者"；装上 Skill，它就变成了能写文档、做报表、处理邮件、操控浏览器的全能打工人。这篇文章从零讲透 Skill 是什么、怎么运作、怎么选、怎么写。

一、先说人话：Skill 到底是什么？

你买了个新手机，开箱之后能干嘛？打电话、发短信、上网。就这么多了。

但你装了微信，它就能聊天；装了美团，它就能点外卖；装了抖音，它就能刷视频。

手机 = OpenClaw，APP = Skill。

就是这么简单。Skill 就是 OpenClaw 的"App"，每一个 Skill 给 AI 加一个新能力。

二、Skill 的三个核心能力

能力一：告诉 AI “什么时候该用我”

每个 Skill 都有一个 description（描述），就像 APP 的功能介绍。当你对 OpenClaw 说话时，它会扫描所有 Skill 的描述，找到最匹配的那个。

你：帮我合并这两个 PDF
OpenClaw：扫描 Skill 列表……找到了！pdf 技能匹配，加载中……

这个过程完全自动，你不需要手动选择。

类比：你跟手机说"我要打车"，手机自动打开滴滴，而不是让你在 200 个 APP 里翻。

能力二：给 AI 一份"操作手册"

Skill 加载后，会给 AI 提供详细的操作指南——用哪个库、走什么流程、注意什么坑。就像新员工入职时的 SOP 文档。

比如 pdf 技能会告诉 AI：

1. 读取 PDF 用 pypdf
2. 合并 PDF 用 PdfMerger
3. 加水印用 page.merge_page()
4. 中文 PDF 可能乱码，需要用 pdfplumber 替代

AI 本身"知道"这些库的存在，但不一定知道最佳实践和避坑方法。Skill 就是把"踩过的坑"固化下来，让每次操作都走最优路径。

能力三：提供可复用的脚本和模板

有些操作太复杂，光靠"告诉 AI 怎么做"不够，还需要提供现成的代码。

比如 docx 技能自带了这些脚本：

docx/
├── SKILL.md ← 操作手册
├── scripts/
│ ├── accept_changes.py ← 接受 Word 修订
│ ├── comment.py ← 添加批注
│ └── office/ ← 底层工具库
│ ├── pack.py ← 打包 docx 文件
│ ├── unpack.py ← 解包 docx 文件
│ └── validate.py ← 校验 XML 结构

AI 不需要每次从零写代码，直接调用脚本，速度快、稳定性高。

三、Skill 的内部结构：一个 Skill 长什么样？

每个 Skill 就是一个文件夹，最核心的文件是 SKILL.md，再配上可选的脚本、参考资料和模板：

skill-name/
├── SKILL.md ← 【必须】技能的"灵魂"
│ ├── YAML 头部 ← name + description（触发条件）
│ └── Markdown 正文 ← 操作指南和流程说明
├── scripts/ ← 【可选】可执行脚本
│ └── xxx.py / xxx.sh
├── references/ ← 【可选】参考资料（按需加载）
│ └── api_docs.md
└── assets/ ← 【可选】输出资源（模板、图片等）
└── template.docx

三层加载机制（关键！）

Skill 不是一次性全塞进 AI 脑子的，而是分三层按需加载：

┌─────────────────────────────────────────┐
│ 第 1 层：元数据（永远在记忆中） │
│ 只有 name + description，约 100 字 │
│ 作用：判断"该不该触发这个 Skill" │
├─────────────────────────────────────────┤
│ 第 2 层：SKILL.md 正文（触发后加载） │
│ 操作手册、流程指南，< 5000 字 │
│ 作用：告诉 AI "具体怎么做" │
├─────────────────────────────────────────┤
│ 第 3 层：脚本和参考（按需读取） │
│ scripts/、references/、assets/ │
│ 作用：提供代码、文档、模板等具体资源 │
└─────────────────────────────────────────┘

为什么分三层？ 因为 AI 的"工作记忆"（上下文窗口）是有限的。如果把所有 Skill 的所有内容全塞进去，AI 就没有空间思考了。分层加载，只在需要的时候加载需要的内容，既高效又省 Token。

类比：你不需要把整本《新华字典》背下来，只需要知道"遇到不认识的字去查字典"就够了。第一层就是"字典目录"，第二层是"查到的那个字的解释"，第三层是"例句和用法"。

四、SKILL.md 详解：一个 Skill 的灵魂

每个 Skill 都有且只有一个 SKILL.md，它决定了这个 Skill 的一切行为。让我们拆解一个真实的例子：

YAML 头部：告诉 AI “我是什么，什么时候找我”

—
name: pdf
description: Use this skill whenever the user wants to do anything with PDF files.
This includes reading or extracting text/tables from PDFs, combining or merging
multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks,
creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images,
and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file
or asks to produce one, use this skill.
—

这段话是给 AI 看的"招聘启事"，AI 每次收到你的消息，都会扫一遍所有 Skill 的 description，看谁最匹配。

写好 description 的要点：

• 说清楚"做什么"（处理 PDF）
• 列举触发场景（合并、拆分、加水印……）
• 明确边界（用户提到 .pdf 文件时触发）

Markdown 正文：手把手教 AI 怎么做

# PDF Processing Guide

## Quick Start

​```python
from pypdf import PdfReader, PdfWriter

# 读取 PDF
reader = PdfReader("document.pdf")
print(f"Pages: {len(reader.pages)}")
​```

## 合并 PDF

使用 PdfMerger：
​```python
from pypdf import PdfMerger
merger = PdfMerger()
merger.append("file1.pdf")
merger.append("file2.pdf")
merger.write("merged.pdf")
​```

## 常见问题

– 中文 PDF 乱码 → 改用 pdfplumber
– 加密 PDF → 先用 decrypt() 解密

正文里写的是 AI 需要"按图索骥"的操作步骤。核心原则：只写 AI 不知道的东西。 AI 本身就会写 Python，不需要你教语法；但 AI 不知道"中文 PDF 用 pypdf 会乱码，得用 pdfplumber"——这种实战经验才是 Skill 的价值。

五、scripts/、references/、assets/ 的区别

很多人搞不清这三个目录的用途，一张图说清楚：

┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ scripts/ │ │ references/ │ │ assets/ │
│ 可执行代码 │ │ 参考文档 │ │ 输出模板 │
├──────────────┤ ├──────────────┤ ├──────────────┤
│ AI 直接执行 │ │ AI 阅读理解 │ │ AI 复制使用 │
│ │ │ │ │ │
│ rotate_pdf.py│ │ api_docs.md │ │ template.docx│
│ merge.sh │ │ schema.md │ │ logo.png │
│ convert.py │ │ policy.md │ │ slides.pptx │
├──────────────┤ ├──────────────┤ ├──────────────┤
│ 像厨师的菜刀 │ │ 像厨师的食谱 │ │ 像厨师的模具 │
│ 拿来就用 │ │ 看了就会 │ │ 照着做就行 │
└──────────────┘ └──────────────┘ └──────────────┘

scripts/ —— 可执行脚本

什么时候用：某个操作每次都要写重复代码，或者步骤很脆弱容易出错。

例子：pdf 技能的 rotate_pdf.py，每次旋转 PDF 都走同一套逻辑，不需要 AI 每次重新写。

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

input_pdf = sys.argv[1]
output_pdf = sys.argv[2]
angle = int(sys.argv[3])

reader = PdfReader(input_pdf)
writer = PdfWriter()
for page in reader.pages:
page.rotate(angle)
writer.add_page(page)
writer.write(output_pdf)

AI 直接调用：python scripts/rotate_pdf.py input.pdf output.pdf 90

references/ —— 参考文档

什么时候用：有些信息 AI 需要知道，但不常用，不需要每次都加载。

例子：docx 技能有 FORMS.md（表单填充指南），只有用户要求填 PDF 表单时才需要看。

# references/FORMS.md

## PDF 表单字段类型
– 文本框 (Text) → fill()
– 复选框 (Checkbox) → check()
– 下拉框 (Dropdown) → select()
– 签名 (Signature) → 不支持自动填充

好处：SKILL.md 保持精简，只在需要时才加载详细文档，节省上下文空间。

assets/ —— 输出模板

什么时候用：Skill 需要基于模板生成文件。

例子：docx 技能有 letterhead.docx（公司信纸模板），AI 不需要从零创建，直接复制模板再修改内容就行。

六、实战案例：5 个热门 Skill 详解

案例 1：pdf —— PDF 全能选手

pdf/
├── SKILL.md ← 支持：读取、合并、拆分、旋转、水印、OCR、加密
├── scripts/
│ └── rotate_pdf.py ← 旋转脚本
└── references/
├── FORMS.md ← 表单填充详细指南
└── REFERENCE.md ← 完整 API 参考

使用场景：

• “把这 3 个 PDF 合并成一个”
• “给这个 PDF 加个’机密’水印”
• “这个扫描件太糊了，帮我 OCR 一下”
• “把这个 PDF 的第 5-10 页单独提取出来”

案例 2：xlsx —— Excel 处理专家

xlsx/
├── SKILL.md ← 支持：读写、公式、图表、格式化
├── scripts/
│ ├── recalc.py ← 公式重算
│ └── office/ ← 底层 XML 操作库
└── references/
└── CHARTS.md ← 图表类型参考

使用场景：

• “把这个 CSV 转成漂亮的 Excel”
• “帮我在这个表里加一列算同比增长”
• “把这个数据画成折线图”

案例 3：docx —— Word 文档大师

docx/
├── SKILL.md ← 支持：创建、编辑、修订、批注、格式
├── scripts/
│ ├── accept_changes.py ← 接受所有修订
│ ├── comment.py ← 添加批注
│ └── office/ ← 打包/解包/校验工具
└── references/
├── DOCX-JS.md ← docx-js 库指南
├── REDLINING.md ← 修订标记详解
└── OOXML.md ← OOXML 格式参考

使用场景：

• “帮我写一份项目周报，用公司模板”
• “接受这个文档里的所有修订”
• “在这个段落旁边加个批注”

案例 4：xbrowser —— 浏览器自动化

xbrowser/
├── SKILL.md ← 支持：打开网页、点击、填表、截图、爬取
└── scripts/
└── (CDP 协议控制)

使用场景：

• “帮我在 CSDN 上发篇文章”
• “截个图，看看这个网页长什么样”
• “自动填一下这个表单”

⚠️ 浏览器类 Skill 需要本地有 Chrome/Edge，且比较吃资源（约 1.8GB），轻量用户可以先不装。

案例 5：weather —— 天气查询

weather/
├── SKILL.md ← 支持：当前天气、7 天预报
└── (无额外文件，纯 API 调用)

使用场景：

• “今天深圳什么天气？”
• “明天出门要带伞吗？”
• “下周北京冷不冷？”

这是一个典型的"轻量 Skill"——没有脚本、没有参考文档，SKILL.md 里只有 API 调用方法，够用就行。

七、Skill 的三层加载：为什么这么设计？

你可能好奇，为什么不把所有内容全塞进 SKILL.md，而要搞 scripts/、references/、assets/ 三个目录？

原因只有一个：上下文窗口是有限的。

AI 的"工作记忆"就像一张桌子，桌面空间有限。如果桌上堆满了文件，AI 就没地方"思考"了。

上下文窗口 = 桌面空间

┌─────────────────────────────────────────────┐
│ │
│ [系统提示] [对话历史] [Skill 内容] │
│ ───────── ────────── ─────────── │
│ 必须占 必须占 占得越少越好！ │
│ │
│ ← 留给 AI "思考"的空间 → │
│ │
└─────────────────────────────────────────────┘

所以 Skill 的设计哲学是：

AI 不需要知道所有细节，它只需要知道"去哪里找"。

八、怎么安装 Skill？

方法一：SkillHub 一键安装（推荐）

你：帮我安装 weather 技能
OpenClaw：正在从 SkillHub 安装 weather……完成！

一行话搞定，SkillHub 会自动处理依赖和环境配置。

方法二：手动安装

如果你有别人分享的 .skill 文件（本质是 zip 包），直接放到 ~/.qclaw/skills/ 目录下解压即可。

方法三：自己写

后面会详细讲。

安装后去哪了？

~/.qclaw/skills/ ← 用户自己安装的 Skill（更新不丢失）
~/.openclaw/skills/ ← 同上（另一个可能的路径）

内置 Skill（应用自带，更新会覆盖）：
D:\\application\\QClaw\\resources\\openclaw\\config\\skills\\

重要：自己创建的 Skill 一定要放在 ~/.qclaw/skills/，别放到内置目录，否则应用更新时会被覆盖丢失。

九、怎么写一个自己的 Skill？

写 Skill 不需要会编程！核心就是一个 Markdown 文件。让我们从零写一个"每日新闻摘要"技能。

第 1 步：确定 Skill 做什么

目标：每天早上自动抓取科技新闻，生成摘要推送给用户。

第 2 步：创建目录结构

daily-tech-news/
├── SKILL.md ← 必须有
└── references/ ← 可选
└── sources.md ← 新闻源列表

第 3 步：写 SKILL.md

—
name: daily–tech–news
description: 每日科技新闻摘要。当用户要求查看今日科技新闻、
获取新闻摘要、或设置每日新闻推送时触发此技能。
—

# 每日科技新闻摘要

## 工作流程

1. 从配置的新闻源获取最新文章
2. 提取标题、摘要、链接
3. 按重要度排序
4. 生成 Markdown 格式摘要

## 新闻源

参见 [sources.md](references/sources.md)

## 输出格式

​```markdown
# 📰 今日科技新闻摘要 (YYYY-MM-DD)

## 🔥 头条
– **标题**：摘要
[阅读全文](url)

## 📌 关注
– **标题**：摘要
[阅读全文](url)

## 💡 趣闻
– **标题**：摘要
[阅读全文](url)
​```

## 注意事项

– 每条新闻不超过 50 字摘要
– 总条数不超过 15 条
– 优先选择过去 24 小时内的新闻

第 4 步：写参考文档

# references/sources.md

## 新闻源列表

### 科技媒体
– 36氪：https://36kr.com
– 少数派：https://sspai.com
– InfoQ：https://www.infoq.cn

### 国际科技
– Hacker News：https://news.ycombinator.com
– TechCrunch：https://techcrunch.com
– The Verge：https://www.theverge.com

第 5 步：测试

你：帮我看看今天的科技新闻
OpenClaw：扫描到 daily-tech-news 技能……加载 SKILL.md……
正在从 36氪、少数派等源抓取新闻……
生成摘要完成！

就这样！一个 Skill 就写完了。不需要写一行代码，核心就是"告诉 AI 做什么、怎么做、去哪找资料"。

十、写好 Skill 的 5 个原则

原则一：只写 AI 不知道的东西

❌ "Python 是一种编程语言，用 def 定义函数……"
→ AI 知道这些，不需要你教

✅ "中文 PDF 用 pypdf 会乱码，改用 pdfplumber"
→ 这是实战经验，AI 不知道

原则二：description 要写清楚触发条件

❌ "处理文件" → 太模糊，AI 不知道什么时候该触发

✅ "当用户要求合并、拆分、旋转 PDF 文件，或提到 .pdf 文件时触发"
→ 精确、无歧义

原则三：正文保持精简（< 500 行）

SKILL.md 不是百科全书，是操作手册。详细内容放 references/，需要时再加载。

❌ SKILL.md 写了 2000 行，包含所有 API 细节
→ 每次触发都占大量上下文，AI 思考空间被压缩

✅ SKILL.md 200 行核心流程，详细 API 放 references/API.md
→ 触发时轻量加载，需要细节时按需读取

原则四：用脚本封装脆弱操作

❌ 每次让 AI 从零写 PDF 旋转代码
→ 容易出错，不同 AI 模型写法不同

✅ 提供 scripts/rotate_pdf.py
→ 确定性执行，稳定可靠

原则五：避免 Skill 之间描述重叠

❌ Skill A: "处理所有办公文档"
Skill B: "处理 Word 文档"
→ 重叠了，AI 不知道该用哪个

✅ Skill A: "处理 PDF 文件 (.pdf)"
Skill B: "处理 Word 文档 (.docx)"
→ 边界清晰，各司其职

十一、Skill vs 插件 vs MCP：别搞混了

简单记忆：

• Skill = 培训手册（教 AI 怎么做）
• Plugin = 工具箱（给 AI 新工具）
• MCP = 外包服务（让 AI 调用外部系统）

十二、常见问题 FAQ

Q1：Skill 会占很多磁盘空间吗？

大多数 Skill 很小（几 KB 到几十 KB），主要就是 Markdown 文件。少数带脚本的会大一些（如 docx 技能约几 MB），但总体不大。浏览器类 Skill（如 xbrowser）因为包含 Chrome 缓存，可能到 1.8GB。

Q2：Skill 会影响 AI 的响应速度吗？

第一层（元数据）始终在上下文中，但每个只占约 100 字，几十个 Skill 加起来也就几千字，对速度影响可以忽略。只有触发的那个 Skill 会加载正文，所以响应速度基本不受影响。

Q3：可以同时触发多个 Skill 吗？

可以。比如你说"把这个 Excel 的数据整理一下，然后生成 PDF 报告"，OpenClaw 会依次触发 xlsx 和 pdf 两个 Skill。

Q4：Skill 更新后会丢失我的自定义吗？

取决于你把 Skill 放在哪：

• ~/.qclaw/skills/ → 应用更新不影响，你的自定义安全
• 内置目录 → 应用更新会覆盖，自定义会丢失

Q5：Skill 可以分享给别人吗？

可以！用打包命令生成 .skill 文件（本质是 zip），别人解压到自己的 skills 目录就能用。

Q6：我完全不会编程，能写 Skill 吗？

能！Skill 的核心就是 Markdown 文本。你只需要：

不需要写一行代码。只有当你需要重复执行某个复杂操作时，才考虑加 scripts/。

十三、Skill 的未来

OpenClaw 的 Skill 生态正在快速生长。目前已有 50+ 内置 Skill 和社区贡献的技能包，覆盖：

• 📄 文档处理（PDF、Word、Excel、PPT）
• 🌐 网络操作（浏览器、搜索、爬虫）
• 📧 通信（邮件、微信、Telegram）
• 🛠️ 开发（GitHub、代码审查、CI/CD）
• 🎨 创意（PPT 设计、前端生成）
• 📊 数据（财务查询、新闻摘要）

随着社区壮大，Skill 会越来越多、越来越专业。OpenClaw 的上限，取决于 Skill 生态的上限。

写在最后

Skill 是 OpenClaw 最核心的设计理念之一：让 AI 不只是"知道"，而是"会做"。

• 一个没有 Skill 的 OpenClaw，就像一台没装 APP 的手机——硬件很强大，但啥也干不了
• 一个装满 Skill 的 OpenClaw，就像一台精心配置的手机——每个需求都有对应的工具

而最棒的是，你不需要等别人开发，自己写一个 Skill 就像写一篇 Markdown 笔记一样简单。

下一篇预告：《【记忆篇】OpenClaw 记忆系统详解：让 AI 真正"记住"你》

👨‍💻 H先生出品 | 专注 AI 工具与效率提升