写你的第一个自定义技能

适用版本： OpenClaw v2026.4.11（stable） 验证日期： 2026-04-12 目标读者： 用过 ClawHub 社区技能，想自己写一个 难度： ⭐⭐⭐ 进阶——本篇涉及 Frontmatter 规范、触发机制和发布流程，建议先熟悉第 4 篇的技能基本概念 适合首次阅读： 有第 4 篇基础即可

目标

从零写一个自定义技能，让 OpenClaw 按照你定义的流程执行任务。

完成后你能为任何重复性工作创建自动化 SOP，真正把 OpenClaw 调教成专属助手。

前置条件

• 已完成本系列前面的章节，特别是第 4 篇《技能（Skills）与工具生态 · ClawHub 实战》
• openclaw daemon status 显示运行中
• 至少已经装过一个 ClawHub 技能，理解技能的基本运作方式

15 分钟最小可用路径

全文分三个阶段。如果你赶时间，只做阶段一就能得到一个可用的自定义技能：

阶段一：写出最小技能

SKILL.md 的两部分

一个技能就是一个包含 SKILL.md 的目录。SKILL.md 由两部分组成：

markdown
---
# Frontmatter（YAML 元数据）
name: my-skill
description: 一句话讲清楚能做什么、什么时候触发
---

# 指令正文（Markdown，直接给 AI 看）
当用户要求...时，按以下步骤操作：
1. 第一步
2. 第二步

OpenClaw 启动时把所有启用技能的 description 注入系统提示词（作为 XML 列表）。消息匹配到某个技能的描述时，AI 自动加载该技能的指令正文执行。

Frontmatter 字段：必填 vs 可选

必填字段（OpenClaw 读取用于技能发现）：

可选字段：

依赖门控字段（写在 metadata 的 JSON 中，缺失时技能不加载）：

yaml
metadata: {"openclaw": {"requires": {"bins": ["ffmpeg"], "env": ["MY_API_KEY"]}}}

缺少声明的依赖时，技能不会出现在可用列表中。

⚠️ 版本说明： Frontmatter 只支持单行键值。metadata 必须写成单行 JSON。多行 YAML 对象会导致解析失败。

让 OpenClaw 帮你写技能

不想从零手写？把下面的 prompt 发给 Bot，它会帮你生成初稿：

text
帮我创建一个自定义技能。按步骤来，每步确认后再进下一步：

[第 1 步：需求收集]
问我：
- 这个技能要解决什么问题（具体场景）
- 触发时机（什么时候 AI 应该自动调用）
- 需要调用哪些工具或外部服务
- 有没有依赖的系统命令或环境变量

[第 2 步：生成 SKILL.md]
根据收集的信息生成完整的 SKILL.md，包含：
- frontmatter：name / description（能做什么 + 什么时候用）
- 指令正文：用"第 1 步 / 第 2 步"明确分步，每步写具体动作
- 注意事项：输出格式、错误处理
把完整内容展示给我 review，不要直接写文件。

[第 3 步：Review]
我会逐条反馈。你对每条反馈回应：接受 / 反驳 / 需要更多信息。
修改后再展示一遍，直到我说"可以写入"。

[第 4 步：写入并验证]
mkdir -p ~/.openclaw/skills/<技能名>/
写入 SKILL.md
运行 openclaw skills list 确认加载
用斜杠命令触发一次，把输出展示给我

任何一步失败就停，不要自动修复。

动手写：每日天气播报

1. 创建技能目录：

bash
mkdir -p ~/.openclaw/skills/daily-weather

2. 编写 SKILL.md：

bash
vim ~/.openclaw/skills/daily-weather/SKILL.md

贴入以下内容：

markdown
---
name: daily-weather
description: 查询指定城市今天的天气，并给出出行和穿衣建议。当用户询问天气、需要出门、安排户外活动时触发。
user-invocable: true
---

你是一个天气播报助手。当用户询问天气时，严格按以下步骤执行：

## 第 1 步：确认城市

- 如果用户消息中包含城市名，直接使用
- 如果没有，主动询问用户

## 第 2 步：获取天气数据

调用 `web_browse` 工具访问 `https://wttr.in/{城市名}?format=j1`，解析 JSON，提取：
- 当前温度、体感温度、今日最高/最低温
- 天气状况、降雨概率、风力风向

## 第 3 步：输出播报

按以下格式输出（简体中文，不超过 10 行）：

📍 {城市} · {日期}
🌡️ {天气状况} · {当前温度}°C（体感 {体感温度}°C）
📊 今日 {最低温}° ~ {最高温}° · 降雨 {降雨概率}%

## 第 4 步：给出建议

基于数据给出 1-2 条具体建议（低温提醒穿衣、降雨提醒带伞、高温提醒防晒）。

## 注意事项

- 不要输出原始 JSON 数据
- 如果 wttr.in 无法访问，告知用户并建议手动查询

3. 确认技能加载：

bash
# 查看已安装技能列表，确认 daily-weather 出现
openclaw skills list

# 查看技能详情
openclaw skills info daily-weather

💡 提示： 大部分情况下技能文件放入 skills 目录后会被自动发现（hybrid 热重载）。如果没出现，跑一次 openclaw daemon restart。

到这里你已经有了一个可用的自定义技能。 下面进入测试阶段。

阶段二：测试与调试

三步快速验证

bash
# 1. 确认技能已加载
openclaw skills list
# 应该看到 daily-weather，状态 enabled

# 2. 用斜杠命令直接触发（绕过 AI 匹配）
# 在聊天中发送：/daily-weather 上海
# 如果能正确返回天气播报，说明技能本身没问题

# 3. 用自然语言触发（测试 AI 匹配）
# 在聊天中发送："帮我看下上海今天天气"
# 如果 AI 调用了 daily-weather 技能，说明 description 写得够精准

测试矩阵

前两类成功、第三类不误触发，说明 description 写得到位。

常见错误与排查

💡 建议： 修改 SKILL.md 后通常会自动热重载。如果改了没生效，跑一次 openclaw daemon restart。

让 AI 帮你生成技能初稿 📌 可选

写 SKILL.md 本身也是重复劳动。直接在聊天中告诉 Bot 需求：

text
帮我创建一个技能：总结 Obsidian 里今天新增的笔记，
输出三个最重要的想法。技能名字叫 obsidian-digest。

OpenClaw 会在 ~/.openclaw/skills/obsidian-digest/ 创建目录和 SKILL.md 初稿。拿到后一定要检查 description 是否精准、指令步骤是否可执行——不要直接用未审核的生成结果。

从任务经验提炼技能 🔬 进阶可选

思路来源： 借鉴 Hermes agent 的 closed-loop learning 设计——Agent 从真实执行轨迹中提炼可复用的技能，而不是从需求描述中猜测步骤。

比"事前描述需求"更准确的方式：先跑一次真实任务，再让 Agent 把成功经验结构化成 SKILL.md。这种方式基于真实执行轨迹，所有步骤和踩坑都是真跑过的。

适合场景：某个流程你手动跑过 3 次以上，觉得值得沉淀成技能。刚跑完任务时发这段 prompt（消息历史还热着，细节没丢）：

text
刚完成了一次任务。帮我把这次成功经验结构化成可复用的 SKILL.md。

[回顾阶段]
1. 回顾刚才从开始到完成的完整消息历史
2. 提炼"跳过就会失败"的关键步骤（不是所有步骤）
3. 列出这次用到的外部资源：命令、API、文件路径、环境变量
4. 列出这次踩过的坑和对应解决方式

[生成阶段]
5. 建议一个 kebab-case 的 skill 名字，等我确认
6. 生成 SKILL.md：frontmatter（name + description 能做什么 + 什么时候用）、执行步骤（第 1 步 / 第 2 步）、失败兜底（至少 2 条真实踩坑）
7. 不要直接落盘，把完整 SKILL.md 贴给我，等我逐条 review

[落地阶段]
8. 我确认后再 mkdir + 写文件
9. 写入后 openclaw skills list 确认加载
10. 用刚才任务的真实参数触发一次，对比手动执行结果

绝不硬编码个人信息（用户名、绝对路径、Token）。

💡 建议： 这种方式的收益在你想要把踩坑型流程（排障、数据迁移、部署经验）固化时最明显——事前生成容易漏掉坑，事后沉淀因为坑刚踩过所以会被明确记下来。

阶段三：打包发布到 ClawHub（可选）

📌 可选章节。 技能跑稳了想分享给社区再来。

发布前检查

• 技能已在本地稳定运行至少一周
• description 足够精准，AI 匹配度高
• 指令正文不含硬编码的个人信息（用户名、绝对路径、Token）
• 依赖声明完整
• 有 README.md（使用场景、配置方式、已知限制）

发布命令

使用 clawhub CLI 发布：

bash
# 全局安装 clawhub CLI（首次）
npm i -g clawhub

# 发布技能目录
# ⚠️ 请替换：slug 和 name 换成你的技能信息
clawhub skill publish ~/.openclaw/skills/daily-weather \
  --slug daily-weather \
  --name "Daily Weather" \
  --version 0.1.0 \
  --tags latest

快速体验方案： 也可以用 npx clawhub@latest 代替全局安装，但版本不固定。长期维护多个技能建议全局安装。

首次发布需要登录（GitHub 账号，至少注册一周）。发布成功后其他用户可以安装：

bash
# ⚠️ 请替换：your-name 换成你的 ClawHub 用户名
openclaw skills install your-name/daily-weather

更新已发布技能

修改 SKILL.md 后重新发布：

bash
# ⚠️ 请替换：版本号递增
clawhub skill publish ~/.openclaw/skills/daily-weather \
  --slug daily-weather \
  --version 0.2.0 \
  --tags latest

💡 建议： ClawHub 上技能的评价中，文档质量权重很大。发布前多花半小时打磨 README，性价比极高。

验证清单

bash
# 1. SKILL.md 已创建
ls ~/.openclaw/skills/daily-weather/SKILL.md

# 2. 技能出现在已安装列表中
openclaw skills list

# 3. 斜杠命令能触发
# 在聊天中发送：/daily-weather 北京

# 4. 自然语言能触发
# 在聊天中发送：「帮我看下北京天气」

# 5. 查看日志确认执行
openclaw logs --follow

常见问题

Q: 一个技能最多写多长？

没有硬限制，但建议控制在 200 行以内。过长的技能会挤压对话上下文空间，让 AI 注意力分散。超过 200 行考虑拆成多个子技能。

Q: 技能能调用外部 API 吗？

技能本身是指令文本，不能直接发 HTTP 请求。但可以在指令中让 AI 使用内置工具（web_browse、bash 等）间接调用。需要自定义协议或 WebSocket 等底层能力，就要写插件。

Q: 怎么让技能记住用户偏好？

SKILL.md 是静态的。需要记忆的话，在指令中引用用户偏好文件，或让技能在调用时读写 memory/ 目录下的文件。记忆系统详见第 6 篇《记忆系统、SOUL 与个性化进化》。

Q: 技能能调用其他技能吗？

可以。在指令中写「完成后调用 summarize 技能对结果做摘要」，AI 会自动串联。这是组合编排的基础。

Q: 修改已安装的 ClawHub 技能会怎样？

直接改 ~/.openclaw/skills/<name>/SKILL.md 即可生效。但 openclaw skills update 会覆盖你的修改——建议 fork 一份改名使用。

下一步

有了自定义技能，你的 OpenClaw 开始变成一个有独特能力的助手了。接下来去第 6 篇《记忆系统、SOUL 与个性化进化》，让它不仅能做事，还能记住你的偏好、积累经验。