# 第三章：Skills 开发与文献管理实战

## 3.1 本章导读

Skills 是 OpenClaw 的核心扩展机制——通过它，你可以为 Agent 赋予几乎任意能力。本章将带你了解：

- **前半部分**（3.2–3.6）：Skills 的工作原理、ClawHub 技能市场、热门推荐、自建方法与安全注意事项
- **后半部分**（3.7–3.8）：进入科研场景，以文献检索为例，运用 Skills 知识构建实用的 Agent 能力

## 3.2 Skills 工作原理

### 3.2.1 什么是 Skill？

Skill 是 Agent 的能力扩展单元。每个 Skill 本质上是一个目录，包含一个必需的 `SKILL.md` 文件和其他可选的代码、配置文件。Skill 定义了 Agent 在特定场景下能做什么、怎么做。

### 3.2.2 三层优先级

OpenClaw 的 Skill 有三个来源，按优先级从高到低排列：

| 优先级 | 位置 | 说明 |
|--------|------|------|
| 最高 | `<workspace>/skills/` | 项目级 Skills，只对当前工作区生效，适合针对特定项目定制的能力 |
| 中 | `~/.openclaw/skills/` | 用户级 Skills，全局生效，通过 ClawHub 安装或手动放置的 Skills 都在这里 |
| 最低 | bundled skills | 内置的 55 个 Skills，随 OpenClaw 版本发布，开箱即用 |

当同名 Skill 存在于不同层级时，高优先级的会覆盖低优先级的。这意味着你可以在工作区层面定制某个 Skill 的行为，而不影响全局配置。

### 3.2.3 Skill 加载过程

当 OpenClaw 启动或收到消息时，Skills 的加载遵循以下流程：

1. **读取元数据** — 扫描三层目录，读取每个 Skill 的 `SKILL.md` 文件，解析名称、描述、触发条件、所需环境变量等元信息
2. **应用环境变量** — 如果 Skill 声明了需要的 API Key 或环境变量，系统会从 `.env` 的 `<env>` 段中注入。缺少必要变量的 Skill 会被静默跳过
3. **构建 System Prompt** — 将所有可用 Skills 的描述注入到 system prompt 中，告知模型当前可以调用哪些能力。这是模型「知道自己能做什么」的关键步骤
4. **运行后恢复** — Skill 执行完毕后，恢复原始环境变量和上下文状态，避免 Skill 之间互相干扰

## 3.3 ClawHub 技能市场

### 3.3.1 市场概况

ClawHub 是 OpenClaw 的官方 Skill 注册表，定位为「AI Agent 的 npm」。

| 指标 | 数值 |
|------|------|
| 总注册技能 | 13,729+ |
| 精选技能（awesome 列表筛选） | 5,494 |
| 被过滤技能（垃圾/重复/恶意） | 6,940 |
| 日安装量 | 15,000+ |
| 被标记为恶意的 | 800+ |

超过一半的 Skills 你不应该安装。学会甄别质量是使用 ClawHub 的必备技能。

### 3.3.2 搜索与安装

ClawHub 支持向量搜索——你可以用自然语言描述需求来搜索 Skill，不必精确匹配名称。

```bash
# 搜索 Skill
openclaw skill search "文献检索"

# 安装 Skill
openclaw skill install <skill-name>

# 查看已安装 Skills
openclaw skill list

# 更新 Skill
openclaw skill update <skill-name>
```

也可以访问腾讯的国内镜像：[https://skillhub.cn/](https://skillhub.cn/)

也可以直接让 Agent 帮你搜索和安装。比如：「帮我找一个可以搜索 arXiv 论文的 Skill」。

如果想查看已经安装的skills，直接对龙虾输入 `/skills`

### 3.3.3 安装位置与生效范围

| 方式 | 位置 | 生效范围 |
|------|------|----------|
| 项目级 | `<workspace>/skills/my-skill/` | 仅当前工作区 |
| 全局 | `~/.openclaw/skills/my-skill/` | 所有会话 |
| ClawHub | 自动安装到全局目录 | 所有会话 |

## 3.4 热门 Skills 推荐

### 3.4.1 热门Skills

![alt text](../images/ch03/image.png)

我目前安装的跟科研相关的是：

| | Skill 名称 | 用途 |
|------|-----------|------|
| 1 | tavily search | 网页搜索，注册后可享受免费额度 |
| 2 | arxiv search | arXiv 论文搜索 |
| 3 | Summarize | 视频、网页、邮件内容的自动摘要，日常使用频率最高的 Skill 之一 |
| 4 | GitHub | 仓库管理、Issue 处理、PR 审查，技术用户标配 |
| 5 | Data Analysis | 数据分析与可视化 |
| 6 | self-improving | 自我改进 |
| 7 | Thinking Partner | 通过提问探索复杂问题的协作思考伙伴 |


还有更多的skills可以去市场搜索尝试。

### 3.4.2 内置 55 个技能分类

OpenClaw 自带 55 个内置 Skills，覆盖以下类别：

- **通讯与社交**：iMessage、WhatsApp CLI
- **笔记与知识管理**：各类笔记工具集成
- **开发工具**：代码编辑、调试、版本管理
- **媒体处理**：图片、视频、音频处理
- **AI 与模型**：模型调用、推理辅助
- **搜索与浏览**：Google 搜索、网页抓取
- **系统工具**：邮件 CLI、文件操作
- **智能家居**：Philips Hue 灯光控制等
- **生态工具**：ClawHub 客户端、skill-creator、mcporter（MCP 桥接）

### 3.4.3 精选资源推荐

| 资源 | 地址 | 说明 |
|------|------|------|
| awesome-openclaw-skills | github.com/VoltAgent/awesome-openclaw-skills | 5,494 个精选 Skill，31.4K Stars |
| awesome-openclaw-usecases | github.com/hesamsheikh/awesome-openclaw-usecases | 社区用例合集，21K Stars |

建议优先使用精选列表中的 Skill，而不是在 ClawHub 上随意搜索。精选列表已经过滤掉了大量垃圾和恶意 Skill。

## 3.5 自建 Skill 指南

***写在前面：自建Skills不需要自己编辑md文件，可以全部让龙虾帮你编辑，只需要告诉他过程是什么样。或者通过指令一步步让他操作后（带着他走一遍），让他总结成一个skill。在使用skill的过程中，可以让他随时修改步骤并且更新skill。***

### 3.5.1 最小 Skill 结构

一个 Skill 的最小单位就是一个目录加一个 `SKILL.md` 文件：

```
skills/
└── my-skill/
    └── SKILL.md       # 唯一必需的文件
```

是的，一个 Skill 甚至可以不需要任何代码。`SKILL.md` 本身就是 Skill 的完整定义——它告诉 Agent 在什么条件下触发、应该怎么行动。

### 3.5.2 SKILL.md 格式

`SKILL.md` 是一个 Markdown 文件，包含以下关键段：

```markdown
---
name: my-skill
description: 这个 Skill 的简短描述
triggers:
  - 用户说"帮我XXX"时触发
---

# My Skill

## Description

详细描述这个 Skill 的功能和用途。

## Instructions

当触发条件满足时，按以下步骤执行：
1. 第一步：...
2. 第二步：...
3. 第三步：...

## Environment Variables

- MY_API_KEY: 需要的 API Key（可选）

## Examples

用户：帮我搜索最新的 LLM 论文
Agent：好的，我来帮你搜索...
```

### 3.5.3 包含代码的 Skill

如果 Skill 需要执行具体操作（如调用 API、处理文件），可以在目录中添加代码文件：

```
skills/
└── literature_search/
    ├── SKILL.md            # Skill 定义（必需）
    ├── skill.yaml          # Skill 配置（可选）
    ├── main.py             # 主要业务逻辑
    ├── prompts/
    │   └── system.txt      # 提示词模板
    ├── tools/
    │   └── arxiv_search.py # 工具实现
    └── tests/
        └── test_skill.py   # 单元测试
```

### 3.5.4 安装方式

| 方式 | 命令/操作 | 说明 |
|------|-----------|------|
| 直接放置 | 将文件夹放到 `workspace/skills/` | 项目级，手动管理 |
| 全局安装 | 复制到 `~/.openclaw/skills/` | 所有会话生效 |
| ClawHub | `openclaw skill install <name>` | 自动安装到全局目录 |
| 对话安装 | 告诉 Agent「帮我安装 XXX Skill」 | Agent 代为操作 |

### 3.5.5 分享到 ClawHub

如果你开发了一个有用的 Skill，可以分享到 ClawHub：

1. 确保 `SKILL.md` 格式正确，包含清晰的 Description 和 Instructions
2. 在 ClawHub 上登录账号
3. 提交 Skill 发布

发布后其他用户可以通过 `openclaw skill install` 安装。ClawHub 会自动进行基础安全扫描，但不保证完全可靠（详见 3.6 节）。

***注意，分享或者发布skill前，需要让你的龙虾Review下skill文件是否包含了你的隐私信息，比如API KEY等。***

## 3.6 Skills 安全

### 3.6.1 ClawHavoc 供应链攻击

2026 年 1 月底到 2 月初，OpenClaw 社区遭遇了一场大规模供应链攻击，被安全研究机构 Koi Security 命名为「ClawHavoc」。

**时间线**：

| 日期 | 事件 |
|------|------|
| 1月27日 | 首个恶意 Skill 出现在 ClawHub 上，伪装成专业工具 |
| 1月28-30日 | 攻击者快速上传大量恶意 Skill，利用 ClawHub 缺乏审查机制的漏洞 |
| 1月31日 | 攻击全面爆发，多名用户报告异常行为 |
| 2月1日 | Koi Security 正式命名该攻击为「ClawHavoc」 |
| 2月上旬 | 社区展开大规模审计和清理 |

**攻击规模**：

| 指标 | 数值 |
|------|------|
| 当时 ClawHub 技能总数 | 约 2,857 个 |
| 初步确认恶意 Skills | 341 个（约 12%） |
| 后续扫描发现的恶意 Skills | 800+（约 20%） |
| 受影响设备 | 135,000+ |

**攻击手法**：

攻击者的手法相当精密：

- 上传看似专业的 Skill，名称和描述都很正常（如「advanced-code-review」「smart-scheduler」）
- 诱导用户安装后，Skill 会建议安装一个「helper agent」来增强功能
- 实际植入的是 Atomic macOS Stealer（AMOS）信息窃取木马
- 更危险的是：攻击专门针对 OpenClaw 的持久记忆文件（`SOUL.md` 和 `MEMORY.md`），篡改 Agent 的长期行为
- 篡改 SOUL.md 意味着你的 Agent 被「洗脑」了，它的核心行为准则被改写，可能在后续所有交互中执行恶意操作，而你完全不知情

### 3.6.2 安全建议

结合第二章的安全配置（skill-vetter 和 SAFETY.md），以下针对 Skills 安装的具体建议：

**1. 安装前审查源码** — 永远不要盲目安装 ClawHub 上的 Skill。去 GitHub 查看源码，确认 SKILL.md 中没有可疑的指令。特别注意任何要求额外安装「helper」或「agent」的内容。

**2. 使用 SecureClaw 扫描** — 社区推出了开源安全工具 SecureClaw，可以扫描已安装的 Skills 检查恶意内容。虽然不能 100% 防护，但能拦住已知的攻击模式。

**3. 优先使用精选列表** — 参考 awesome-openclaw-skills 项目的精选列表，而不是直接在 ClawHub 上随意搜索。

**4. 定期检查 SOUL.md 和 MEMORY.md** — 养成习惯，定期检查这两个文件有没有被异常修改。如果发现不认识的内容，立即回滚并排查所有已安装的 Skill。

**5. 安装 skill-vetter** — 详见第二章 2.11 节，让 Agent 在安装任何 Skill 前自动进行安全审查。

## 3.7 实战：自动文献检索汇总 Skill

前面我们了解了 Skills 的原理、市场和安全性。现在进入实战——为科研场景构建一个文献检索 Skill。


### 3.7.1 需求分析

我们将创建一个「自动文献检索汇总 Skill」，实现以下功能：

- 根据关键词搜索近期 arXiv 的论文
- 返回论文标题、作者、摘要等信息
- 根据作者的研究方向，推荐相关论文，并且进行分析
- 给出分析报告和研究建议

### 3.7.2 先带着OpenClaw走一遍

比如，我就直接把这个任务发给了龙虾：
![alt text](../images/ch03/image1.png)

第一遍过程中肯定有各种问题，比如：
![alt text](../images/ch03/image-0.png)

然后又出现了检索的时间并不符合要求：

![alt text](../images/ch03/image-1.png)

我让他严格限制到一周，
![alt text](../images/ch03/image-2.png)

结果太少了，最后还是让他扩大范围
![alt text](../images/ch03/image-3.png)

执行完成，如果结果不满意再让他调整

![alt text](../images/ch03/image-4.png)

### 3.7.3 生成skill
可以直接命令他：“能否把上面的过程和注意事项整理成一个skill，然后放入定时任务，每周执行一次？”

![alt text](../images/ch03/image-5.png)

生成完成后可以再让他运行这个skill，如果有问题可以直接让他更新。


## 3.8 本章小结

本章我们从 Skills 的基本概念出发，完整了解了 OpenClaw 的扩展体系：

| 模块 | 内容 | 关键收获 |
|------|------|----------|
| **3.2 工作原理** | 三层优先级、加载过程 | 理解 Skill 的加载机制和优先级规则 |
| **3.3 ClawHub** | 技能市场概况、搜索安装 | 学会使用 ClawHub 发现和安装 Skills |
| **3.4 热门推荐** | 必装 Top 10、内置技能 | 了解社区主流 Skills 的用途 |
| **3.5 自建指南** | SKILL.md 格式、目录结构 | 掌握创建自定义 Skill 的方法 |
| **3.6 安全** | ClawHavoc 事件、安全建议 | 建立安全意识，学会甄别恶意 Skill |
| **3.7 文献检索** | 实战 Skill 开发 | 将理论运用到科研场景 |

### 关键设计理念

1. **极简主义** — 一个 Skill 最少只需要一个 `SKILL.md` 文件
2. **分层管理** — 项目级、用户级、内置三层优先级，灵活控制
3. **安全优先** — ClawHavoc 事件警示我们，Skill 安装必须审查

### 课后思考

1. 为什么 OpenClaw 的 Skill 要设计三层优先级？这种设计在什么场景下特别有用？
2. 如果你需要一个 Skill 来管理每日待办事项，你会选择纯 SKILL.md（无代码）还是带代码的实现？各自适合什么场景？
3. ClawHavoc 攻击中，为什么篡改 SOUL.md 比窃取 API Key 更危险？
4. 如何为文献检索 Skill 添加 Semantic Scholar 等更多数据源？需要修改哪些文件？

## 3.9 延伸阅读

- [OpenClaw Skills 开发官方文档](https://docs.openclaw.dev/skills)
- [awesome-openclaw-skills 精选列表](https://github.com/VoltAgent/awesome-openclaw-skills)
- [awesome-openclaw-usecases 社区用例](https://github.com/hesamsheikh/awesome-openclaw-usecases)
- [arXiv API 官方文档](https://info.arxiv.org/help/api/index.html)
- [装好 OpenClaw 之后，这些安全配置你必须做](https://mp.weixin.qq.com/s/vMWwV-ra9nHD08yOadRrWg)
- [腾讯 Skillhub.cn](https://skillhub.cn/)
