SKILL.md 是 Skill 的入口文件。你可以把它理解成“给 OpenClaw 和模型共同看的任务说明书”。这一篇不做字段百科，而是给你一条可执行路径：先写最小版，再加约束，再做发布前自检。
本章完成标准
你完成后应该能独立写出一个结构清楚、触发条件清楚、依赖说明清楚的 SKILL.md，并知道什么时候该加 metadata，什么时候不该过度复杂化。
先记住 4 条规则
SKILL.md需要 frontmatter，最少包含name和description。- 正文要写“何时用、怎么做、失败时怎么处理”，不要只写口号。
- 有依赖时再加
metadata.openclaw，无依赖时不要硬加。 - 路径引用优先用
{baseDir}，避免写死绝对路径。
步骤一：先写最小可用模板
先写能跑通的版本，不要一上来就堆很多字段：
---
name: hello_world
description: 用于返回简短问候的最小示例 Skill
---
# Hello World Skill
适用场景：
- 用户需要一句简短问候
- 用于验证 Skill 是否被正确加载
执行规则：
- 返回一句简洁问候
- 不输出冗长说明
只要这个模板写对，模型基本就能判断该不该调用它。
步骤二：把必填字段写“能触发”
name 和 description 是最关键的两个字段：
name：建议用英文小写，短横线或下划线都可以，保持稳定不频繁改名。description：一句话写清楚“解决什么问题”，不要写“一个很好用的 Skill”。
好的描述示例：
description: 对长文档进行结构化总结，输出结论、行动项和风险点不好的描述示例：
description: 一个很强的智能助手步骤三：按需加入 metadata.openclaw
当 Skill 依赖 CLI、环境变量、配置项时，再加 metadata.openclaw。在当前版本里，官方示例使用单行 JSON，实践中也更稳：
metadata: {"openclaw":{"requires":{"bins":["summarize"],"env":["SUMMARIZE_API_KEY"]},"primaryEnv":"SUMMARIZE_API_KEY","homepage":"https://example.com"}}最常用字段：
requires.bins：必须存在的命令。requires.anyBins：多个命令满足其一即可。requires.env：必须存在的环境变量。requires.config：必须满足的配置项。primaryEnv：主密钥变量名，便于定位配置入口。os：限定系统加载范围。
步骤四：正文按“场景-规则-失败处理”写
正文不是写人设，而是写任务执行说明。建议固定 3 段：
- 适用场景：什么时候触发。
- 执行规则：怎么做、输出什么格式。
- 失败处理：缺依赖、缺权限、缺密钥时怎么反馈。
同时，把目录资源引用写成：
使用 {baseDir}/templates/summary.md 作为输出模板。这样换机器、换 workspace、换安装位置都不容易失效。
步骤五：发布前做一次自检
发布到 ClawHub 前，至少过这份清单：
- frontmatter 能被正常解析（分隔线、冒号、缩进无误）。
description能让人一眼看懂用途。- 依赖项都写在
metadata.openclaw.requires里。 - 正文没有泄漏密钥、Token、私有地址。
- 路径全部用
{baseDir}或相对路径策略。 - 至少做过一次真实触发测试。
最常见的 6 个错误
description太空，模型无法判断何时调用。- metadata 写太复杂，结果 frontmatter 解析失败。
- 把密钥直接写进正文或脚本示例。
- 正文只写目标，不写边界和失败处理。
- 漏写依赖项，导致“能加载但不能运行”。
- 写死本机绝对路径，换环境就崩。
可直接复用的进阶模板
---
name: summarize_docs
description: 对长文档进行结构化总结，输出结论、行动项和风险点
metadata: {"openclaw":{"requires":{"bins":["summarize"],"env":["SUMMARIZE_API_KEY"]},"primaryEnv":"SUMMARIZE_API_KEY","homepage":"https://example.com"}}
---
# Summarize Docs
适用场景：
- 用户提交长文档、网页或说明材料
- 目标是快速产出结构化摘要
执行规则：
- 先提炼核心结论，再列行动项与风险
- 输出保持简洁，不逐段复述原文
失败处理：
- 缺少 summarize 命令或 API Key 时，直接指出缺失项并给出修复建议
资源路径：
- 使用 {baseDir}/templates/summary.md 作为输出模板
下一步建议
- 继续做目录落地：看 目录结构与资源管理。
- 开始接能力：看 调用 Tools / 外部 API。
- 提前排错：看 测试、调试、常见坑。