Skip to content
OpenClaw 书稿预览

第12章 写第一个Skill：日报生成器

🎯 本章目标：学完这章，你能按官方规范写出一个可运行、可检查、可发布的 Skill

⏱️ 预计时间：35分钟

📋 前置要求：已完成第11章（安装现成 Skills）

本章你将学会什么

Section titled “本章你将学会什么”
  • 官方定义下，Skill 到底是什么
  • SKILL.md 的最小必需结构
  • metadata.openclaw.requires（加载前体检规则）怎么写
  • 如何在本地验证（list/info/check）
  • 如何发布与后续维护（publish/sync）

12.1 先统一概念：Skill 不是“代码包”，是“执行说明书”

Section titled “12.1 先统一概念：Skill 不是“代码包”，是“执行说明书””

官方口径下，一个 Skill 本质是一个目录，核心文件是 SKILL.md。
你可以把它理解成“给 Agent 的操作手册”（写清步骤，它就按步骤干）。

12.1.1 Skill 目录长什么样

Section titled “12.1.1 Skill 目录长什么样”
<workspace>/skills/
  └── daily-report/
      └── SKILL.md

常见默认 workspace：~/.openclaw/workspace。
所以完整路径常见是：~/.openclaw/workspace/skills/daily-report/SKILL.md。

12.1.2 本章目标成果

Section titled “12.1.2 本章目标成果”

我们要做一个最小可用的日报 Skill：

  • 输入：可选日期（默认今天）
  • 输出：一份结构化日报草稿（Markdown）
  • 工具依赖：文件读写工具（group:fs 覆盖）

12.2 SKILL.md 官方最小模板（先跑通再加料）

Section titled “12.2 SKILL.md 官方最小模板（先跑通再加料）”

先给你一个实操建议（真的很实用）：
先复制最小模板跑通，再做“进阶美化”。
不要一开始就堆高级字段，不然很容易出现“写了很多但不在可用清单里（--eligible）”。

12.2.1 最小可运行版本

Section titled “12.2.1 最小可运行版本”
---
name: daily-report
description: 根据给定日期生成日报草稿
---


# Daily Report


## Use when


用户希望生成当日或指定日期的工作日报草稿。


## Inputs


- date（可选）：格式 `YYYY-MM-DD`，不传则使用当天日期。


## Steps


1. 解析 `date`，若缺失则使用当天日期。
2. 生成日报模板（今日完成 / 明日计划 / 阻塞问题）。
3. 将结果写入 `reports/daily-{date}.md`。
4. 回复输出文件路径与摘要。


## Output


返回生成文件路径和简短预览。

先从这个模板开始，别上来就写 200 行“史诗级 Skill”。

操作提醒：SKILL.md 请用 UTF-8 保存，文件名大小写要准确；写完第一时间跑 openclaw skills list 看它是否被识别到。

12.2.2 官方格式要点（容易踩坑）

Section titled “12.2.2 官方格式要点（容易踩坑）”
  1. frontmatter 至少需要 name + description。
  2. frontmatter 键值用单行写法（别在 frontmatter 里玩复杂多行结构）。
  3. metadata 建议写成单行 JSON 对象（官方解析器兼容性更好）。
  4. 优先写清楚 Use when / Inputs / Steps / Output，这是可维护关键。
  5. 只写当前必需能力，别提前塞未来需求（YAGNI）。
  6. 需要引用 Skill 目录时，用 {baseDir} 变量，避免写死绝对路径。

12.3 进阶版：加“门禁”与调用方式（官方推荐）

Section titled “12.3 进阶版：加“门禁”与调用方式（官方推荐）”

12.3.1 为什么要加“门禁”

Section titled “12.3.1 为什么要加“门禁””

你不希望一个 Skill 在“依赖没装好”时也硬上。
官方推荐通过 metadata.openclaw.requires 做加载前检查。
你可以把它理解成：依赖没装好，技能就先别上场。

12.3.2 带门控的示例

Section titled “12.3.2 带门控的示例”
---
name: daily-report
description: 生成日报草稿并写入文件
user-invocable: true
metadata: {"openclaw":{"requires":{"bins":["rg"]},"skillKey":"daily-report"}}
---


# Daily Report


## Use when


用户说“生成日报”“按今天任务整理日报”等场景。


## Inputs


- date（可选，YYYY-MM-DD）


## Steps


1. 确认日期。
2. 汇总当日任务输入（由用户提供或上下文已有）。
3. 生成 Markdown 日报。
4. 写入 `{baseDir}/../../reports/daily-{date}.md`。
5. 返回路径并提醒用户复核内容。


## Output


- 文件路径
- 100 字以内摘要

说明（翻成人话）：

  • user-invocable: true：允许你手动点名触发这个 Skill（默认就是 true）。
  • requires.bins：依赖命令没装好时，Skill 不会进入可用清单。
  • skillKey：用于映射 skills.entries.<key> 的配置键（可选，不写则默认用 name）。

12.3.3 可选高级项（先知道，不急着上）

Section titled “12.3.3 可选高级项（先知道，不急着上）”
  • disable-model-invocation: true：不让模型自动调用，仅用户触发。
  • command-dispatch: tool + command-tool：斜杠命令直达工具，走确定性路径。

12.4 从创建到验证：完整实操

Section titled “12.4 从创建到验证：完整实操”

12.4.1 创建目录与文件

Section titled “12.4.1 创建目录与文件”
Terminal window
mkdir -p ~/.openclaw/workspace/skills/daily-report

把 SKILL.md 写到：

~/.openclaw/workspace/skills/daily-report/SKILL.md

如果你不确定当前 workspace 路径，可以先看一眼：

Terminal window
openclaw config get agents.defaults.workspace

拿到路径后，再在那个路径下建 skills/daily-report。

12.4.2 让 OpenClaw 识别新 Skill

Section titled “12.4.2 让 OpenClaw 识别新 Skill”

优先推荐：开一个新会话。
如果你开了 skills.load.watch: true，也可在当前会话后续轮次刷新到。

操作提醒：遇到“改了没生效”，先新开会话复现；不要同时改模型、配置、Skill 三件事，不然很难定位。

12.4.3 官方检查三件套

Section titled “12.4.3 官方检查三件套”
Terminal window
openclaw skills list
Terminal window
openclaw skills list --eligible
Terminal window
openclaw skills info daily-report

再补一条巡检：

Terminal window
openclaw skills check

12.4.4 如何解读检查结果

Section titled “12.4.4 如何解读检查结果”
  • 在 list 能看到：说明被发现了。
  • 在 --eligible（可用清单）能看到：说明依赖和门控都满足。
  • info 里能看到 requirements/路径：说明可排障。
  • skills check 通过：说明整体技能环境健康。

如果可用清单（--eligible）里缺席，先查：

  1. frontmatter 是否合法；
  2. metadata 是否单行 JSON；
  3. requires 对应依赖是否真的存在。

12.5 发布与维护：别只会“写”，还要会“养”

Section titled “12.5 发布与维护：别只会“写”，还要会“养””

12.5.1 发布单个 Skill

Section titled “12.5.1 发布单个 Skill”
Terminal window
clawhub publish ~/.openclaw/workspace/skills/daily-report \
  --slug daily-report \
  --name "Daily Report Skill" \
  --version 1.0.0 \
  --changelog "first stable release" \
  --tags latest

12.5.2 扫描并批量同步

Section titled “12.5.2 扫描并批量同步”
Terminal window
clawhub sync --dry-run

确认无误后：

Terminal window
clawhub sync --all

12.5.3 维护纪律（给未来的你省时间）

Section titled “12.5.3 维护纪律（给未来的你省时间）”
  1. 每次更新写清版本与变更点。
  2. 先本地过“可用清单（--eligible）”，再发布。
  3. 遇到不稳定版本，先回滚到上一个稳定版本，不要硬扛。

本章小结

Section titled “本章小结”
  1. Skill 的最小核心是 SKILL.md，不是复杂工程脚手架。
  2. 写好 Use when / Inputs / Steps / Output，比“炫技语法”更重要。
  3. metadata.openclaw.requires 是稳定性关键。
  4. openclaw skills list --eligible 是上线前必跑项。
  5. publish/sync 让你的 Skill 可共享、可追踪、可维护。

下一步：第13章，学习把 Skill 做成“生产级”的工程化实践。

动手试试

Section titled “动手试试”
  1. 创建 daily-report 目录与 SKILL.md。
  2. 加上最小 frontmatter 和四段结构。
  3. 跑 list / list --eligible / info 三连检查。
  4. 在会话里触发一次日报生成。
  5. 用 clawhub sync --dry-run 看发布预览。