OpenClaw Skills 开发实战笔记

什么是 Skill简单说Skill 是一个文件夹里面包含SKILL.md核心指令文件和配套脚本。它的作用是给 Agent 赋予特定的工作流程能力而不是零散的、每次都要重新解释的指令。Skill vs Memory最根本的差别是精度。Memory 是模糊检索——Agent 每次都要理解存储的内容时间长了还会衰减、遗忘。Skill 是精确的文本合约SKILL.md白纸黑字地写清楚什么时候用、怎么做、不能怎么做Agent 不需要理解和解释只需要执行。什么时候用 Skill当你需要 Agent重复、稳定地执行同一类任务时比如定时生成报告、按流程处理数据、自动巡检系统。一个任务如果要跑 3 次以上流程相对稳定就值得做成 Skill。我开发了几个 Skills踩了不少坑。下面分享几个主要问题、解决方案和相关经验。踩坑记录起因靠 memory 执行重复任务不稳定最初的想法很简单让 OpenClaw 执行一个任务然后告诉它记住这个流程存到 memory 里。想着以后再让它跑同样的任务就直接用 memory 里的流程。但实际上很快就出现了问题多跑几次输出质量飘忽不定第二天再让它做要么格式全变、完全不符合要求要么直接失忆更离谱的是有时候它还会否认自己之前做过这个任务。根本原因是 OpenClaw 的 memory 是模糊检索不是精确存储。它记住的是大概的意思不是逐字逐步的流程。每次回忆时重新理解一遍自然每次理解不一样。而且 memory 会被新信息冲刷时间一长早期存的内容权重就下降了。所以我最后的结论是要让 Agent 稳定重复执行同一个任务不能靠 memory不精确必须靠 Skill精确的文本指令。SKILL.md 是白纸黑字的不存在忘了或理解偏差的问题。在开发 Skill 的过程中我遇到了几个问题。下面逐一记录。问题 1OpenClaw 找不到刚部署的 Skill现象把新 Skill 部署到workspace/skills目录下但 OpenClaw 找不到这个 Skill不会自动触发。原因OpenClaw 似乎不会主动扫描workspace/skills下的新 Skill新部署的 Skill 不会自动加载 (原因不明)。解决方案先执行命令确认 Skill 状态为readyopenclaw skills list告诉 OpenClaw刷新 skill 列表如果刷新后还没有识别到新 Skill告诉它我在 workspace 下加了新的 [abc] skill然后要求它读取新 Skill读一下 [abc] skillOpenClaw 会读取该 Skill 的 SKILL.md 文件并描述其内容证明 Skill 已被成功加载OpenClaw Skill 加载优先级官方文档OpenClaw 从多个位置加载 Skills优先级从高到低优先级位置说明1最高workspace/skills工作区 Skill2workspace/.agents/skills项目 Agent 的 Skill3~/.agents/skills用户个人 Skill4~/.openclaw/skills本地全局 Skill5Bundled skillsOpenClaw 安装包自带的内置 Skill6最低skills.load.extraDirs配置文件指定的额外目录同名 Skill 出现在多个位置时高优先级覆盖低优先级。注这部分内容参考自 OpenClaw 官方文档。问题 2修改 SKILL.md 后 Agent 还在用旧版本现象改了 SKILL.md 的内容但 Agent 下次执行时还是按旧逻辑走。原因OpenClaw 宣称支持热重载配置里也开了watch: true但实际上 Skill 更改后并不一定会自动更新原因不明。这个坑特别隐蔽 — 你可能测了半天最后才意识到 Agent 根本没用新版本。我的配置watch 已开启skills: { load: { watch: true, // 已设为 true但不一定生效 watchDebounceMs: 250 } }解决方案修改 SKILL.md 后告诉 OpenClaw[abc] skill 已更新重新加载通常 OpenClaw 会总结一下变化点新增/删除/修改了什么确认一下总结是否正确确保新版本已被加载如果发现还是用旧逻辑让 OpenClaw 清除记忆清除和 [abc] skill 相关的记忆然后重新加载 Skill教训不要假设热重载生效了。每次在测试 Skill 的改动前要确保 Skill 已经更新。问题 3黑盒创建 Skill 可能行不通现象最开始我让 OpenClaw 用skill-creator把任务执行的过程直接写成 Skill我并没有检查 SKILL.md 的内容纯黑盒测试 — 跑一遍看结果不行就让skill-creator改改完再跑反复循环。但这种做法总有各种问题而且效率很低。原因不管是 OpenClaw 对需求的理解、它设计的方案还是它做的改动都可能存在偏差。它以为自己改好了实际上问题还在。而我在不清楚 Skill 内容的情况下做出的判断也不一定对 — 双方都在猜。Agent 对什么是好的 Skill缺乏判断力 — 它能写出语法正确的 SKILL.md但不懂什么样的指令能让自己严格执行。它的修改本质上是猜测不是反思。解决 — 用写代码的方式写 Skill(可以用 coding agent 写)先开发依赖脚本scripts— 抓取、解析、数据处理等脚本要先测通确保这层没问题再写 SKILL.md— 这一步要仔细检查 SKILL.md 内容确保描述准确、步骤严谨最后放到 OpenClaw 里集成测试— 测试 Skill 是否能按预期工作固化有效版本— 一旦某个版本工作正常通过版本控制 (例如git) 管理起来。能用的版本及时 commit后续改坏了可以随时回退这样做效率高了很多。更重要的是出了问题我知道该查哪一层 — 因为我了解 Skill 内部是怎么回事。教训Skill 的核心设计还是需要由人来做 (尤其对于复杂的)。Skill Creator 适合生成初稿不适合迭代打磨。问题 4定时任务不执行或者执行了但不调用 Skill现象我需要一个定时任务按照 Skill 执行操作并把结果发送到飞书 DM。但实际情况是要么任务没按时执行要么没调用 Skill要么执行出错。原因定时任务有两种做法1系统 cron job2OpenClaw 内置的定时任务机制。应该使用方案 2并正确配置。解决在 OpenClaw 的 Web UI 上配置配置文件位于~/.openclaw/cron/jobs.json。以我的定时任务为例基本信息名称填任务名称调度调度选Cron配置好 Cron 表达式时区填Asia/Shanghai执行会话选隔离会话唤醒模式选立即执行内容选运行助手任务隔离超时填一个合理的超时时间助手任务提示填具体的任务描述 — 这里要写得能够触发你的 Skill投递结果投递选发布摘要默认频道选飞书注意Skill 里不需要写发送飞书的步骤只需返回执行结果即可。隔离会话的结果会通过 Inter-session Message 回传到主会话再由主会话投递到飞书。教训定时任务要用 OpenClaw 内置机制不要用系统 cron。最关键的是助手任务提示那段话必须能触发 Skill否则 Agent 不知道该调用什么。问题 5Agent 不严格执行 Skill生成质量差现象Skill 里写了明确的步骤和格式要求但 Agent 并不严格执行输出质量不稳定。原因SKILL.md 里的指令太建议性不够强制。Agent 天然倾向于偷懒和走捷径。解决方案用强制约束代替建议— 用MUST、MUST NOT、NEVER明确规则## 约束 - MUST 严格按模板输出NEVER 省略内容 - MUST 保留具体数字、数据、关键信息 - NEVER 改原意或自由发挥 - NEVER 跳过任何步骤明确输出模板和数据指标— 不是参考而是必须### 输出模板MUST 严格遵守 - **[项目名称]** — [数据来源](URL) [用自己的话写 N 字核心内容] 数据指标MUST 满足 - 类别A MUST ≥ X - 类别B MUST ≥ Y - 类别C MUST Z每项 M-N 字用决策树而非文字描述流程— 让 Agent 按逻辑分支执行而非自由理解## 执行流程决策树 ① 数据获取 IF 成功 → 进入② IF 失败 → 回退排查错误通知用户 ② 数据过滤 IF 符合条件 → 进入③ IF 不符合 → 回退调整参数重新过滤 ③ 内容提取与分析 IF 质量指标满足 → 进入④ IF 不满足 → 回退扩大范围重新提取 ④ 报告组装 [按模板输出] ⑤ 自检清单 □ 所有指标都满足□ 所有链接前置 □ 无省略内容 □ 格式正确强制自检清单— 明确哪些必须检查哪些必须 NEVERMUST 逐项检查后才能返回 □ 所有数据按照规则处理过 □ 所有内容用自己的话写过不是直接复制 □ 所有必填项都有吗 NEVER - NEVER 输出模板占位符文字 - NEVER 省略任何数据 - NEVER 等待用户确认ALWAYS 直接执行教训SKILL.md 是给 Agent严格执行的代码不是建议文档。用MUST/NEVER 决策树 自检清单效果比应该强 100 倍。总结写合约不写建议— SKILL.md 是执行代码用MUST/NEVER的强制规则替代应该的建议。决策树、自检清单、明确格式是让 Agent 严格执行的关键。工程方法— 像开发代码产品一样开发 Skill。先把脚本逻辑搞定并测通再精心设计 SKILL.md流程、格式、验证点最后在 OpenClaw 中集成测试。别用黑盒 反复试错。好的 Skill 的稳定性和质量取决于你是否把它当成代码产品来开发。