OpenClaw Skill 实战：写一个真正可用的 SKILL.md

AI 推荐

适合读者：准备自己写 Skill，想把能力做成可被稳定调用单元的开发者。

预计阅读：6 分钟

你将看到：

•Skill 不是一段提示词，而是可发现、可筛选、可运行的能力单元。

•目录优先级和 gating 决定 Skill 是否真正可用。

•环境注入、依赖声明和热更新，是 Skill 稳定性的关键。

头图，适合正文开头和封面横图裁切。

核心示意图，帮助读者快速抓住本篇结构。

如果你已经按前几篇做到下面这些事：

• dashboard 能正常使用

• 至少已经接通了一个真实消息入口

• 也知道 openclaw.json 不是参数表，而是运行边界

那接下来最值得补的一步，不是继续堆配置，而是给 Agent 一项你以后不用每次重讲的固定能力。

这一篇只解决一个具体问题：

写一个最小但稳定的 Skill，让 Agent 在合适的时候真的会用，而不是把它当成一段摆设提示词。

一、先定本篇起点和完成标志

先不要急着背术语，先看这一篇结束时你应该得到什么。

你的起点状态

1. OpenClaw 已经在本机稳定运行

2. 你已经能在浏览器或真实通道里和 Agent 对话

3. 你有一个当前正在使用的 workspace

本篇完成标志

到最后，你至少应该完成这 3 件事：

1. 在当前 workspace 里新建一个 skills/<skill-name>/SKILL.md

2. 新开一个 session 后，Agent 能在合适任务里使用这个 Skill

3. 你知道为什么有些 Skill 看起来写好了，但系统就是不稳定

如果只记一句话，就是：

Skill 的目标不是“多一段提示词”，而是多一个可被发现、可被筛选、可被稳定调用的能力单元。

二、先别讲原理，先做一个最小 Skill

我们先做一个真实又足够小的例子：release-note-drafter。

它只负责一件事：

根据最近一次 Git 变更，帮你整理发布说明。

在当前 workspace 下，先建这个目录：

<workspace>/skills/release-note-drafter/SKILL.md

然后把下面这份最小版本写进去：

---

name: release-note-drafter

description: 根据最近一次 Git 提交和变更说明，生成结构化发布说明。

metadata:

{

"openclaw": {

"requires": {

"bins": ["git"],

"env": ["OPENAI_API_KEY"]

},

"primaryEnv": "OPENAI_API_KEY"

}

}

---

当用户需要生成版本发布说明、更新日志或变更摘要时使用此技能。

工作步骤：

1. 读取最近一次 tag 或 commit 范围

2. 提炼用户可见变更

3. 输出正式版发布说明和内部版变更摘要

注意事项：

- 不要编造不存在的改动

- 如果 Git 历史不完整，先说明证据不足

- 输出时区分“事实”和“推断”

这份模板有意保持简单，因为你现在最需要验证的不是“能写出多复杂的 Skill”，而是：

1. 目录结构对不对

2. SKILL.md 会不会被系统识别

3. 依赖条件有没有提前写清楚

三、怎么验证这个 Skill 真的生效

很多人写完 SKILL.md 就结束了，这一步其实还不够。

更稳的验证方法是：

1. 新开一个 session

2. 给 Agent 一个明确任务，比如“请根据最近一次提交整理一版 release note”

3. 观察它是不是沿着 Skill 里定义的边界工作

你想看到的不是“它提到了 release note 这个词”，而是下面这些行为：

• 会先找 Git 变更范围，而不是凭空开始写

• 如果缺少 git 或 API key，会先说明条件不足

• 输出会区分可确认事实和推断

如果你只在当前 session 里边改边试，结果很容易飘，因为 Skill 可用列表通常按 session 做快照。这个点后面会展开。

四、Skill 会从哪里被加载

现在再回头看原理，就容易多了。

官方文档给出了三层技能来源：

1. Bundled skills：随 OpenClaw 安装包自带

2. Managed / local skills：~/.openclaw/skills

3. Workspace skills：<workspace>/skills

优先级是：

<workspace>/skills > ~/.openclaw/skills > bundled skills

这条规则的实际意义非常直接：

• 你可以把项目专用 Skill 放在 workspace 内

• 你可以把跨项目复用的 Skill 放在 ~/.openclaw/skills

• 同名时，离当前 workspace 越近，优先级越高

这也是为什么我建议你第一版 Skill 先放到当前 workspace。因为它最可控，也最容易排查。

五、一个合格的 Skill，至少要写清三件事

1. 它是什么

也就是 name 和 description。

2. 它什么时候该被调用

这部分既体现在正文说明里，也体现在 metadata.openclaw.requires.* 这样的 gating 条件里。

3. 它是否真的可执行

如果这个 Skill 依赖某个二进制、某个 API key 或某个配置开关，就应该显式写出来，而不是把错误留到运行时。

上面那份例子里，最值钱的其实不是文案，而是：

• bins：声明二进制依赖

• env：声明环境变量依赖

• primaryEnv：帮助系统把主密钥注入到正确位置

这会直接影响 Skill 最终会不会进入可用列表。

六、为什么很多 Skill 看起来能用，实际上不稳定

通常不是因为它们不会写 Markdown，而是漏掉了 OpenClaw 的两个运行事实。

1. Skill eligibility 是动态筛选的

OpenClaw 在启动 agent run 时，会根据 skill metadata、环境变量、二进制存在情况、配置项等，决定哪些 Skill 真的可用。

所以不是目录里有文件，就一定会被注入到系统提示词里。

2. 技能列表通常按 session 做快照

官方文档明确写了：技能列表通常在 session 启动时做 snapshot，后续复用。也就是说：

• 你刚改完 SKILL.md

• 当前会话不一定立刻完整感知

• 新开一个 session 往往更可靠

如果启用了 watcher，下一次 agent turn 可能会热更新；但把所有调试都赌在热更新上，通常不稳。

这也是为什么排查 Skill 时，最稳的做法一直是：

改文件 -> 新开 session -> 再验证任务。

七、为什么说 Skill 不是越多越好，而是越“可被筛掉”越好

这是 OpenClaw 很工程化的一点。

如果一个 Skill 只在满足这些条件时才有意义：

• 某个二进制存在

• 某个配置项打开

• 某个 API key 已配置

那它就应该把这些条件写进 gating，而不是默认无条件可用。

这样做有两个直接好处：

1. 系统提示词里只注入真正可运行的 Skill

2. 模型不会在条件不足时误以为自己可以完成任务

官方文档甚至给了技能列表的 token 成本估算，这说明 Skill 注入在 OpenClaw 里不是“顺手拼进去”，而是明确当成 prompt 预算和稳定性问题来治理。

八、沙箱场景下，还要多想一步

文档里有个非常容易忽略，但很关键的点：

requires.bins 是在 host 上检查的，但如果 agent 跑在 sandbox 里，相关二进制也必须真实存在于容器内部。

这意味着：

1. host 上装了工具，不代表 sandbox 里能用

2. Skill 能被加载，不代表运行时一定成功

3. 如果某个 Skill 依赖外部 CLI，你要同时准备 host 和 sandbox 环境

所以成熟的 Skill，不只是把说明写清楚，还要把运行环境想完整。

九、给新手的 Skill 最小实践标准

如果你刚开始给 OpenClaw 写 Skill，我建议先用这套标准，不要一上来做“大而全助手”：

1. 只做一件事

2. 把适用场景写清楚

3. 把依赖条件写进 metadata

4. 把输出结构说清楚

5. 先在当前 workspace 里验证，再考虑全局复用

你会发现，真正让 Skill 稳定的，往往不是写得多花，而是边界写得多清楚。

十、这一篇之后，你该建立什么认知

到这里，你应该把 Skill 理解成：

它不是附加说明文档，而是 OpenClaw 运行时能力编排的一部分。

写得好的 Skill，会让系统在正确时机拿出正确能力；写得差的 Skill，只会让模型多读几段没法稳定执行的文字。

下一篇，我们继续讲另一个决定体验上限的模块：Memory 和 Session。

参考链接

• Skills： https://docs.openclaw.ai/tools/skills

• Creating Skills： https://docs.openclaw.ai/tools/creating-skills

• Multi-Agent Routing： https://docs.openclaw.ai/concepts/multi-agent

这一篇属于 OpenClaw 系列的「进阶」阶段。

上一篇：OpenClaw 配置实战：openclaw.json、workspace、tool policy 怎么配

下一篇：OpenClaw 会话与记忆：让 Agent 记住，而不只是多轮聊天