AI 推荐
适合读者：准备自行编写 Skill，希望将能力封装为可被稳定调用的功能单元的开发者。
预计阅读：6 分钟
你将看到：
• Skill 并非一段简单的提示词，而是可被发现、可筛选、可实际运行的能力模块。
• 目录优先级与 gating 条件直接决定 Skill 是否真正生效。
• 环境注入、依赖声明与热更新机制是保障 Skill 稳定运行的核心要素。
头图，适合正文开头和封面横图裁切。
核心示意图，帮助读者快速抓住本篇结构。
如果按照前几篇文章的节奏，你已经成功启动了 dashboard，至少接入了一个真实的消息入口，并且理解了 openclaw.json 并非简单的参数表，而是系统运行的边界。那么接下来最值得你投入时间的一步，不是继续堆砌配置，而是为你的 Agent 构建一项无需每次重复解释的固定能力。
本文聚焦一个具体问题：编写一个最小但稳定的 Skill，让 Agent 在合适的时机真正调用它，而不是将其当作一段无用的提示词。
一、先明确起点与完成标志
在深入术语之前，我们先确认本文结束时你应该具备的成果。
你的起点状态
1. OpenClaw 已在本机稳定运行。
2. 你已能在浏览器或真实通道中与 Agent 进行对话。
3. 你拥有一个当前正在使用的 workspace。
本篇完成标志
最终，你至少需要完成以下三项：
1. 在当前 workspace 下新建 skills/。
2. 新开一个 session 后，Agent 能在合适的任务中自动调用该 Skill。
3. 理解为什么有些 Skill 看似编写完成，但系统总是运行不稳定。
如果只记住一句话，那就是：
Skill 的目标不是“多一段提示词”，而是成为一个可被发现、可被筛选、可被稳定调用的能力单元。
二、先忽略原理，动手构建一个最小 Skill
我们以一个真实又足够简单的例子来实践：release-note-drafter。它只做一件事：根据最近的 Git 变更，自动整理发布说明。
在当前 workspace 下，首先创建目录：
然后将以下最小版本写入文件：
---
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：位于
优先级顺序为：
这条规则的实际意义非常直接：
• 你可以将项目专用的 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 启动时进行快照，后续重复使用。也就是说：
• 你刚修改完 SKILL.md。
• 当前会话不一定能立即完整感知。
• 新开一个 session 往往更加可靠。
如果启用了 watcher，下一次 agent turn 可能会触发热更新；但把所有调试都依赖热更新通常不稳定。因此最稳妥的 Skill 排查方式始终是：修改文件 → 新开 session → 再次验证任务。
七、为什么 Skill 不是越多越好，而是越“易被筛选”越好
这是 OpenClaw 非常工程化的设计。如果一个 Skill 只有在满足以下条件时才有意义：
• 某个二进制存在。
• 某个配置项开启。
• 某个 API key 已配置。
那么它就应该将这些条件写入 gating，而不是默认无条件可用。
这样做有两个直接好处：
1. 系统提示词中只注入真正可运行的 Skill。
2. 模型不会在条件不满足时误以为自己可以执行该任务。
官方文档甚至给出了技能列表的 token 成本估算，说明在 OpenClaw 中，Skill 注入并非“顺手拼进去”，而是被明确作为 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 记住，而不只是多轮聊天
