所谓Skill，不过是包装好的Prompt

先说清楚 Skill 长什么样

一个 Skill 就是一个文件夹。最简单的情况只有一个文件，复杂的可以带脚本和资源：

stock-price/                ← 文件夹名（就是 skill 的 ID）
├── SKILL.md               ← 【必须】唯一必须有的文件
├── scripts/               ← 【可选】脚本，干活用的代码
│   └── fetch_quote.py
├── references/            ← 【可选】参考资料，需要时加载到 context 里看
│   └── API_FORMAT.md
└── assets/                ← 【可选】模板、图标等输出用的素材
    └── report_template.html

各部分是干嘛的：

可选部分详细说明（带最简完整实例）

scripts/ — 放脚本，agent 直接跑

什么时候用： 同一个操作每次都一样，让 agent 重写一遍太蠢，不如直接跑现成脚本。

完整例子 — 一个 PDF 转图片的 skill：

文件夹结构：

pdf-to-image/
├── SKILL.md
└── scripts/
    └── convert.sh

完整 SKILL.md：

---
name: pdf-to-image
description: 把 PDF 的指定页转成 PNG 图片
metadata: {"openclaw": {"requires": {"bins": ["pdftoppm"]}}}
---

# PDF 转图片

用户想把 PDF 某一页变成图片时，按以下步骤操作：

1. 确认用户提供了 PDF 文件路径，如果没提供就问
2. 确认要转第几页（默认第 1 页）
3. 执行脚本：

exec: bash {baseDir}/scripts/convert.sh <PDF路径><页码><输出路径>

输出路径默认用 PDF 同目录下的 `output.png`。

4. 完成后告诉用户图片保存在哪

完整 scripts/convert.sh：

#!/bin/bash
# 用法: convert.sh input.pdf page_number output.png
PDF="$1"
PAGE="${2:-1}"
OUT="$3"

pdftoppm -png -f "$PAGE" -l "$PAGE" "$PDF" > "$OUT"
echo "已转换: 第${PAGE}页 → ${OUT}"

对比不用脚本： 如果不放脚本，agent 每次都得自己拼 pdftoppm -png -f 1 -l 1 ... 这行命令。参数顺序容易记混，有脚本就一句话搞定。

references/ — 放参考资料，需要时才看

什么时候用： 有些信息太长不适合全塞进 SKILL.md（会让正文太臃肿），但 agent 干活时可能需要查。

完整例子 — 一个查股价的 skill，API 返回格式复杂：

文件夹结构：

stock-price/
├── SKILL.md
└── references/
    └── response_format.md

完整 SKILL.md：

---
name: stock-price
description: 查询股票实时价格
metadata: {"openclaw": {"requires": {"env": ["STOCK_API_KEY"]}}}
---

# 查股价

当用户问某只股票的价格时：

1. 拼接请求 URL：https://api.stockdata.com/v1/quote?symbol={股票代码}&token=$STOCK_API_KEY
2. 用 web_fetch 访问该 URL
3. 从返回的 JSON 中提取 price 字段
4. 告诉用户："{股票名} 当前价格 {price} {currency}"

常见股票代码：
- 腾讯: 0700.HK
- 阿里: BABA
- 茅台: 600519.SS

如果用户问涨跌幅、成交量等更多信息，先 read {baseDir}/references/response_format.md 了解全部可用字段。

完整 references/response_format.md：

# API 返回格式

返回示例：
{
  "symbol": "0700.HK",
  "name": "腾讯控股",
  "price": 388.2,
  "currency": "HKD",
  "open": 390.0,
  "high": 392.5,
  "low": 386.0,
  "close_yesterday": 389.7,
  "change": -1.5,
  "change_pct": -0.38,
  "volume": 12345678,
  "market_cap": 3720000000000,
  "timestamp": "2026-05-09T14:30:00Z"
}

字段说明：
- price: 最新价（延迟约 15 分钟）
- change_pct: 涨跌百分比，已经乘过 100（-0.38 表示跌了 0.38%）
- volume: 成交量（股）
- market_cap: 总市值（当地货币）
- 港股 symbol 格式: XXXX.HK
- A股 symbol 格式: XXXXXX.SS（沪）/ XXXXXX.SZ（深）

为什么拆开： 大部分时候用户只问"腾讯多少钱"，agent 只要提取 price 就行，那段 15 行的格式说明根本用不到。拆到 references 里 = 90% 的情况下省掉这些 token，需要时再 read 进来。

assets/ — 放模板和素材，生成结果时用

什么时候用： agent 要输出固定格式的东西，与其让它每次凭空编，不如给个模板让它填空。

完整例子 — 生成工作日报的 skill：

文件夹结构：

daily-report/
├── SKILL.md
└── assets/
    └── template.md

完整 SKILL.md：

---
name: daily-report
description: 按固定模板生成工作日报
---

# 生成工作日报

当用户说"写日报"或"生成今天的日报"时：

1. 读取模板：read {baseDir}/assets/template.md
2. 问用户今天做了什么（如果用户已经说了就不用问）
3. 按模板格式填充内容
4. 输出填好的日报

规则：
- 日期自动填当天
- "风险/阻塞"栏如果用户没提，就填"无"
- 每条事项用 - 开头，不编号
- 保持模板的标题结构不变

完整 assets/template.md：

# {日期} 工作日报

**姓名：** {姓名}

## 今日完成
{逐条列出}

## 明日计划
{逐条列出}

## 风险/阻塞
{没有填"无"}

为什么不让 agent 自己编格式： 不用模板的话，周一生成的日报有"姓名"栏，周二就忘了加；周三多了个"备注"栏，周四又没了。用模板 = 确保每次输出结构一样，交给领导不会一天一个样。

三者的核心区别

scripts/    → agent 去"跑"的东西（执行代码）
references/ → agent 去"看"的东西（查资料理解）
assets/     → agent 去"填"的东西（套模板输出）

大部分简单 skill 只需要一个 SKILL.md 就够了。只有当你发现：

• 同样的命令 agent 老写错 → 抽成 script
• 正文太长影响阅读 → 拆到 references
• 输出格式不稳定 → 做个 asset 模板

才需要加可选文件夹。别过度设计。

SKILL.md 的结构

这个文件分两部分：

---
name: stock-price
description: 查股票实时价格
metadata: {"openclaw": {"requires": {"env": ["STOCK_API_KEY"]}}}
---

# 查股价

当用户问某只股票的价格时：
1. 用 web_fetch 访问 https://api.example.com/quote?symbol={股票代码}
2. 从返回的 JSON 里提取 price 字段
3. 告诉用户当前价格

如需详细格式说明，read {baseDir}/references/API_FORMAT.md

上面两个 --- 之间的部分叫前置元数据（frontmatter），下面是正文指令。

各字段含义：

metadata 里可以写什么条件

metadata: {"openclaw":{
"requires":{
    "bins":["python3"],        # 系统上必须有这个命令
    "env":["STOCK_API_KEY"],   # 必须设了这个环境变量
    "config":["browser.enabled"]# openclaw.json 里这个配置必须为 true
},
"os":["darwin","linux"],    # 只在这些操作系统上生效
"primaryEnv":"STOCK_API_KEY"# 告诉系统这个 skill 的核心 API key 是哪个
}}

所有条件都是"不满足就自动隐藏"，不会报错，agent 根本看不到这个 skill 存在。

用一个例子说清楚

假设你想让 agent 有"查股价"的能力。需要告诉它的核心就一句话：

"用户问股票价格时，调 API 拿到实时报价，报给用户。"

下面看同一个需求的两种实现。

做法一：直接写进 AGENTS.md（裸 prompt）

打开 AGENTS.md，加一段：

## 查股价
当用户问股票价格时，用 web_fetch 访问 https://api.example.com/quote?symbol={代码}，
从返回 JSON 提取 price 字段，告诉用户当前价格。

实际发生了什么：

用户: "帮我看个代码bug"

系统 prompt 里有：
  ├── SOUL.md（200字）
  ├── AGENTS.md（500字，包含查股价那段）  ← 占着位子
  ├── USER.md（100字）
  └── ...

→ 查股价那段话跟着进了 context，即使这轮根本没人问股票
→ 下一轮还是跟着进
→ 每一轮都跟着进
→ 白白烧 token

用户: "腾讯现在多少钱"

系统 prompt 里有：
  ├── SOUL.md（200字）
  ├── AGENTS.md（500字，包含查股价那段）  ← 这次终于用上了
  └── ...

→ agent 看到指令，调 API，汇报结果 ✅

感受： 就像你把菜谱贴在冰箱门上。不管你今天做不做饭，每次开冰箱都看到那张纸。纸少还行，贴满了就烦了。

做法二：包成 Skill

创建文件夹和文件：

skills/stock-price/SKILL.md

内容：

---
name: stock-price
description: 查股票实时价格
---

# 查股价

当用户问股票价格时，用 web_fetch 访问 https://api.example.com/quote?symbol={代码}，
从返回 JSON 提取 price 字段，告诉用户当前价格。

实际发生了什么：

用户: "帮我看个代码bug"

系统 prompt 里有：
  ├── SOUL.md（200字）
  ├── AGENTS.md（400字，没有查股价内容了）
  ├── 可用技能列表：
  │     └── stock-price: "查股票实时价格"  ← 只有这一行摘要！
  └── ...

→ agent 看到列表里有个 stock-price skill，但这轮不需要
→ 不读，不加载，那段指令根本不进 context
→ 省了

用户: "腾讯现在多少钱"

系统 prompt 里有：
  ├── SOUL.md（200字）
  ├── AGENTS.md（400字）
  ├── 可用技能列表：
  │     └── stock-price: "查股票实时价格"  ← agent 判断：这次跟股票有关，加载它
  └── ...

→ agent 调用 read("skills/stock-price/SKILL.md")
→ 读到完整指令
→ 调 API，汇报结果 ✅

感受： 就像你把菜谱收进抽屉。要做饭的时候拉开抽屉看一眼，不做饭的时候桌面干干净净。

同一段文字，两种命运

Skill 多出来的"壳"给你什么

那层包装不只是省 token，还附赠了几个好处：

1. 条件加载（用不了就别显示）

metadata: {"openclaw": {"requires": {"env": ["STOCK_API_KEY"]}}}

没配 API key？这个 skill 自动从列表里消失。agent 根本不知道有这个能力存在，也就不会试着用它然后报错。

裸 prompt 做不到——写进 AGENTS.md 就永远在那儿，不管环境有没有准备好。

2. 开关（一行配置禁用）

{"skills": {"entries": {"stock-price": {"enabled": false}}}}

不想要了？改一行配置。不用去 AGENTS.md 里翻半天找哪段是查股价的然后小心翼翼删掉。

3. 可分享

你写的 skill 可以发到 ClawHub，别人 clawhub install stock-price 一键用上。AGENTS.md 里的内容没法这么分享。

4. 隔离

改 skill 不影响你的核心 prompt；改核心 prompt 不影响 skill。各管各的，互不干扰。

什么时候别包成 Skill

有些东西必须每轮都在：

• "用中文回复" → 不能按需加载，时刻生效
• "简洁，别说废话" → 同上
• "你叫小助手" → 身份不能选择性加载
• "遇到不确定的先问我" → 安全规则必须常驻

这些就该写在 SOUL.md / AGENTS.md 里。如果 agent 某一轮"忘了"自己该用中文，那就出事了。

判断方法很简单：这段话如果某一轮 agent 没看到，它会不会做出不对的行为？

• 会 → 写 prompt，常驻
• 不会 → 包成 skill，按需加载

最后打个比方

AGENTS.md / SOUL.md = 你脑子里时刻记着的东西
                      （你叫什么、在哪上班、基本三观）

Skill = 你书架上的那些工具书
        （要用的时候翻一下，不用的时候不占脑子）

本质都是"知识"，区别只是：常驻内存 vs 放硬盘按需读取。

Skill 就是被包了个壳的 prompt，仅此而已。