Skip to content
OpenClaw 书稿预览

写第一个技能：从“自动化小助手”到“可复用工具”

这一章就干一件事：带你从 0 写出第一个“能长期用”的 Skill。
我们按官方文档一步步来，不靠玄学、不靠拍脑袋（Creating Skills、Skills、Skills Config、openclaw skills、ClawHub）。

本章你将学会什么

Section titled “本章你将学会什么”
  • 选一个对新手安全、好上手、可验证的 Skill 题目。
  • 把“模糊需求”拆成固定输入、固定输出、固定失败处理。
  • 在 workspace/skills 下完成第一个 SKILL.md 并通过命令验收。
  • 给 Skill 加上最小稳态保护（重复执行不乱套、重试、限流）。
  • 按 ClawHub 的流程做“可分享发布”。

读者前置

Section titled “读者前置”
  • 你已完成第 2 章和第 9 章，知道 openclaw.json 与 workspace 在哪里。
  • 你本机可以正常执行：
Terminal window
openclaw --version
Terminal window
openclaw skills list

10.1 选题与边界

Section titled “10.1 选题与边界”

10.1.1 选题标准：先稳住，再升级

Section titled “10.1.1 选题标准：先稳住，再升级”

第一个 Skill，别上来就挑战“高风险外部动作”（比如转账、批量删改线上数据）。
建议用这三个标准筛题：

  1. 可跟做：任何同学按步骤都能跑出来；
  2. 可验证：成功与失败都能一眼判断；
  3. 可回滚：出错时最多影响本地文件，且能恢复。

10.1.2 本章示例：日报草稿 Skill

Section titled “10.1.2 本章示例：日报草稿 Skill”

我们用“日报草稿生成”做示例：
输入当天要点，输出统一 Markdown 模板，不直接发送到外部平台。

这样选的好处：

  • 学到的结构能迁移到周报、会议纪要、复盘总结；
  • 没有外部 API 依赖，不会因为网络或配额卡住；
  • 失败成本低（最多重跑一次）。

10.1.3 先定边界，避免功能蔓延

Section titled “10.1.3 先定边界，避免功能蔓延”

第一版只做四件事：

  • 接收 date 与 highlights；
  • 按固定模板生成文本；
  • 写入 workspace/reports/ 目录；
  • 返回“成功/失败 + 下一步建议”。

本章不做：

  • 自动发飞书/钉钉；
  • 跨系统拉取数据；
  • 多步骤审批流。

10.2 需求拆解（输入/输出/失败）

Section titled “10.2 需求拆解（输入/输出/失败）”

10.2.1 输入：尽量少，且必填项明确

Section titled “10.2.1 输入：尽量少，且必填项明确”

第一个 Skill 建议输入控制在 2~3 项：

  • date（必填）：如 2026-02-17
  • highlights（必填）：当天完成事项（列表）
  • blockers（可选）：阻塞项

输入项一多，新手基本第一步就会卡住。
先让输入项“短小确定”，跑通后再加料。

10.2.2 输出：固定骨架，便于复用

Section titled “10.2.2 输出：固定骨架，便于复用”

建议输出采用固定结构：

status: ok|error
summary: 一句话结果
data: {
  file: 输出文件路径
  content: 生成内容
}
nextAction: 下一步建议

同时，写入文件内容使用固定模板：

# 日报（{{date}}）


## 今日完成
- ...


## 阻塞与风险
- ...


## 明日计划
- ...

10.2.3 失败：先定义错误语义，再写实现

Section titled “10.2.3 失败：先定义错误语义，再写实现”

至少覆盖这三类失败：

  1. 缺少必填参数（如 date 为空）；
  2. 目标目录不可写；
  3. 输入格式异常（例如 highlights 不是列表）。

错误提示统一三段式（这会直接影响读者能不能自己排错）：

  • 发生了什么；
  • 系统已做了什么；
  • 你下一步该做什么。

10.3 实现最短跑通路径

Section titled “10.3 实现最短跑通路径”

10.3.1 创建目录与 SKILL.md

Section titled “10.3.1 创建目录与 SKILL.md”

按官方 Creating Skills 文档，先在工作区创建目录：

Terminal window
mkdir -p ~/.openclaw/workspace/skills/daily-report-writer

然后创建 SKILL.md。注意两点（官方 Skills 文档明确）：

  • frontmatter 必须有 name、description；
  • metadata 建议写成单行 JSON，避免解析歧义。

示例：

---
name: daily-report-writer
description: 根据输入生成日报 Markdown 草稿并写入 reports 目录
user-invocable: true
metadata: {"openclaw":{"emoji":"📝"}}
---


# Daily Report Writer


## Use when
- 用户要求生成“日报/工作总结草稿”


## Inputs
- date（必填，YYYY-MM-DD）
- highlights（必填，数组）
- blockers（可选，数组）


## Steps
1. 校验参数是否齐全。
2. 读取（或创建）`reports/{{date}}-daily-report.md`。
3. 按固定模板写入内容。
4. 返回 `status/summary/data/nextAction`。


## Failure
- 缺参数：明确指出缺哪一项，并给示例输入。
- 写文件失败：返回目录权限检查建议。

10.3.2 frontmatter 进阶键（官方字段）

Section titled “10.3.2 frontmatter 进阶键（官方字段）”

当你从“能跑”走向“可维护”时，建议尽早把这几个字段补上：

  • disable-model-invocation：true 时，不把技能注入模型提示词（但仍可手动调用）；
  • command-dispatch / command-tool / command-arg-mode：把斜杠命令直接派发给指定工具；
  • requires.anyBins：声明“至少存在一个可执行文件”才允许该技能变为 eligible；
  • metadata.openclaw.primaryEnv：把技能 API Key 绑定到固定环境变量名；
  • metadata.openclaw.skillKey：给技能稳定键名，避免后续重命名造成配置漂移。

示例（演示字段组合，按需删减）：

---
name: daily-report-writer
description: 根据输入生成日报 Markdown 草稿并写入 reports 目录
user-invocable: true
disable-model-invocation: false
command-dispatch: tool
command-tool: your_tool_name
command-arg-mode: raw
requires:
  anyBins: [node, python3]
metadata: {"openclaw":{"skillKey":"daily-report-writer","primaryEnv":"MINIMAX_API_KEY","emoji":"📝"}}
---

如果会话在 sandbox 中运行，requires.anyBins 里依赖的二进制也必须在容器内存在。
否则 openclaw skills list --eligible 里会看不到它。

10.3.3 刷新与验收

Section titled “10.3.3 刷新与验收”

写完后，别直接“凭感觉”就上。先跑命令做验收：

Terminal window
openclaw skills check
Terminal window
openclaw skills list --eligible
Terminal window
openclaw skills info daily-report-writer

如果 --eligible 里没出现它，先看 info 里的 requires，再回头改配置。
这一步别省，省了通常会在后面排障时补票。

10.3.4 首次调用（最小验证）

Section titled “10.3.4 首次调用（最小验证）”

在 Control UI 或 TUI 里发一条明确请求（别让模型自己猜）：

请使用 daily-report-writer，日期 2026-02-17，
highlights 为 ["完成渠道配置文档","修复安装指引"]，
blockers 为 ["等待测试环境开通"]。

你应该看到：

  1. 返回 status: ok；
  2. 给出输出文件路径；
  3. 本地文件存在且结构完整。

10.4 让技能更稳（重复执行不乱套 / 重试 / 限流）

Section titled “10.4 让技能更稳（重复执行不乱套 / 重试 / 限流）”

10.4.1 重复执行不乱套（幂等）：同一输入重复执行，结果可预测

Section titled “10.4.1 重复执行不乱套（幂等）：同一输入重复执行，结果可预测”

最省事的做法：
用 date 作为文件名的一部分，例如 reports/2026-02-17-daily-report.md。

执行前先读文件：

  • 若已存在：选择“覆盖”或“追加”，并在返回里说明；
  • 若不存在：创建新文件。

这样可避免重复运行导致随机文件名、内容难追踪。

10.4.2 重试：只重试可恢复错误

Section titled “10.4.2 重试：只重试可恢复错误”

建议规则：

  • 参数错误：不重试，直接返回修复建议；
  • 临时 I/O 错误：最多重试 1~2 次；
  • 每次重试间隔递增（例如 1s、2s）。

不要无上限重试，否则小问题会被你重试成大问题。

10.4.3 限流：先限制工具集合，再限制调用频率

Section titled “10.4.3 限流：先限制工具集合，再限制调用频率”

对新手最稳的做法是：先把工具权限收紧：

{
  tools: {
    profile: "coding",
    deny: ["group:runtime", "group:web"],
  },
}

含义：

  • 允许文件读写等基础能力；
  • 禁止执行任意命令与外网抓取，降低误用风险。

10.5 文档化与发布

Section titled “10.5 文档化与发布”

10.5.1 最小文档清单

Section titled “10.5.1 最小文档清单”

准备发布前，至少有这三份内容：

  1. SKILL.md（能力与步骤）；
  2. README.md（快速开始与示例输入）；
  3. CHANGELOG.md（版本变化）。

10.5.2 用 ClawHub 发布

Section titled “10.5.2 用 ClawHub 发布”

先登录：

Terminal window
clawhub login

发布单个 Skill：

Terminal window
clawhub publish ~/.openclaw/workspace/skills/daily-report-writer --slug daily-report-writer --name "Daily Report Writer" --version 1.0.0 --tags latest

后续批量同步：

Terminal window
clawhub sync --all

10.5.3 发布前最后检查

Section titled “10.5.3 发布前最后检查”
  • openclaw skills check 通过；
  • openclaw skills list --eligible 可见；
  • 示例输入可稳定复现；
  • 失败提示不是“只报错不指路”。

本章小结

Section titled “本章小结”
  • 第一个 Skill 的关键不是“看起来聪明”，而是“边界清晰、输出稳定、失败可解释”。
  • 官方推荐的最小结构是“技能目录 + SKILL.md”；用 openclaw skills 命令做验收。
  • 可靠性应在第一版就加上：重复执行不乱套（幂等）、可恢复重试、能力限流。
  • 发布不是“把文件一传”就结束，版本号和变更记录一定要配套。