OpenClaw Skill 实战：写真正可用的SKILL文件指南
AI 智能推荐
目标读者：计划亲手编写 Skill，希望将自身能力封装为可稳定复用的功能模块的开发者。
阅读时长：约 6 分钟
本文核心收获：
• Skill 并非简单提示词，而是一个可被检索、可过滤、可稳定执行的能力封装单元。
• 目录优先级与 gating 机制直接决定 Skill 是否能被 Agent 真正启用。
• 环境注入、依赖声明与热更新机制是维系 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 成本估算，这表明 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 记住，而不只是多轮聊天