官方创建 Skills 文档给出的路线非常清晰：先做一个最小可用 Skill，让 OpenClaw 能发现它、理解它、调用它，再考虑复杂逻辑。
很多人第一次做 Skill 时，脑子里会直接冒出“接 API”“做完整工作流”“搞成半个平台”这些想法。热情没问题，但成功率往往不高。更稳的方式，是先做一个能被发现、能被选中、能稳定返回结果的最小能力。
官方对 Skill 的定义
根据官方文档，一个 Skill 本质上是一个目录，其中至少包含：
- 一个
SKILL.md
可选还可以包含：
- 脚本
- 资源文件
- 辅助配置
- 示例输入输出
也就是说，Skill 不是一句提示词，也不是一段散落在别处的说明文档，而是一个有明确边界、可被系统索引和调用的能力目录。
第一步：先决定你的第一个 Skill 做什么
在创建目录之前，建议先给自己定一个非常小的目标。理想的第一个 Skill 最好满足：
- 单一输入
- 单一输出
- 没有复杂副作用
- 不依赖过多外部状态
- 成功与失败都容易判断
适合新手的题目通常像这样：
- 读取某个固定格式文件并总结
- 根据输入生成一段固定结构文本
- 调一个简单 API 并整理结果
- 执行一条低风险、可重复的本地命令
不太适合第一篇就做的，反而是：
- 需要多步状态管理的 Skill
- 依赖大量隐式环境变量的 Skill
- 一失败就可能改坏真实数据的 Skill
第二步：创建 Skill 目录
官方示例：
mkdir -p ~/.openclaw/workspace/skills/hello-world
这条路径说明了两个关键点：
- Skill 默认属于当前工作区
- 它不是随便丢一个 Markdown 到别处就能自动生效
如果你已经有自己的工作区结构，核心原则也是一样的：让 Skill 处在系统会扫描、会索引的位置。
第三步：写 SKILL.md
官方给出的最小示例是：
---
name: hello_world
description: A simple skill that says hello.
---
# Hello World Skill
When the user asks for a greeting, use the `echo` tool to say "Hello from your custom skill!".
这个例子看起来很简单，但它已经包含了 Skill 的核心：
- 元数据
- 用途描述
- 触发场景
- 对模型的明确指令
SKILL.md 到底在告诉模型什么
可以把 SKILL.md 理解成“给模型看的使用说明书”。它至少要回答这几个问题：
- 这个 Skill 是干什么的
- 什么时候应该用
- 不该在什么情况下用
- 需要什么输入
- 应该产出什么结果
如果这些信息写得太模糊，模型就算发现了你的 Skill，也未必会稳定选中它。
第一个 Skill 的文案该怎么写更稳
写说明时，建议尽量做到：
- 任务边界清楚
- 触发条件明确
- 动作步骤简洁
- 输出预期可判断
比如不要只写“这个 Skill 用来处理文件”，而应该更具体一点：
- 处理哪类文件
- 做什么处理
- 输出成什么形式
- 遇到缺文件或格式不对时怎么办
描述越接近“一个可执行说明”，模型的调用稳定性通常越高。
一个更实用的最小模板
如果你不想只照抄 hello world，可以从下面这种结构开始：
---
name: summarize_notes
description: Read a notes file and return a concise summary.
---
# Summarize Notes
Use this skill when the user asks to summarize a local notes file.
Requirements:
- The target file must exist in the workspace.
- If the file is missing, explain the problem clearly.
Expected output:
- A short summary
- Key bullet points
- Any obvious action items
这个模板的好处是，已经把“什么时候用”“前提是什么”“输出长什么样”都写进去了。
为什么不要一上来做“大 Skill”
因为你最先要验证的其实不是功能多不多，而是：
- 能不能被发现
- 能不能被调用
- 输入输出稳不稳定
- 是否容易调试
- 失败时能不能看懂问题
如果一开始就做很复杂的 Skill，你很容易分不清到底是索引有问题、描述有问题，还是执行逻辑本身有问题。
第四步：给 Skill 配最少的依赖
第一个 Skill 最好尽量少依赖外部环境。尤其要避免这种情况：
- 只有你自己电脑上能跑
- 依赖没写出来
- 需要额外登录状态却没说明
- 需要某个命令行工具却没注明
如果确实需要依赖，至少要在 SKILL.md 或配套文档里写明：
- 需要哪些环境变量
- 需要哪些命令或脚本
- 预期在哪个目录运行
这样后面调试时会轻松很多。
第五步：让新 Skill 生效
官方文档建议：
- 让智能体“刷新 skills”
- 或重启 Gateway
只要索引更新成功，新的 Skill 就会被发现。
如果刷新后依然看不到，优先排查：
- 目录位置对不对
SKILL.md是否存在- 元数据有没有明显格式错误
- 当前工作区是不是系统正在使用的那个工作区
第六步：用最小问题去测试它
不要一上来就把第一个 Skill 扔进复杂任务里。更好的做法是只问一个最小问题，例如：
- “请使用这个 Skill 总结我的笔记”
- “请调用这个 Skill 生成问候语”
- “请用这个 Skill 读取并整理这个文件”
测试时重点看三件事：
- 模型有没有选中它
- 结果是否符合你写的预期
- 出错时信息是否可读
第一个 Skill 常见失败原因
很多第一次失败，其实都不是“写错代码”，而是下面这些基础问题：
SKILL.md描述太空泛，模型不知道什么时候该用- 依赖没写，运行环境不完整
- 输出预期不明确，导致结果忽左忽右
- Skill 做得太大，一次调试信息太多
只要把这些基础项收紧，成功率会明显提升。
一个推荐节奏
如果你准备开始做自己的第一个 Skill，我建议按这个顺序：
- 先定一个单一目标
- 再创建目录和
SKILL.md - 再把触发条件和输出写清楚
- 再做最小测试
- 最后才慢慢加复杂逻辑
一个最实用的建议
第一个 Skill 不要追求“强大”，先追求“可重复、可验证、可调试”。只要第一个成功闭环跑通，后面的扩展会顺很多；反过来，如果第一步就做成半个平台，往往会在最基础的发现、调用和调试环节卡很久。