夜雨聆风如何编写高质量的 SKILL.md，让 AI 助手更聪明
什么是 OpenClaw 技能？
OpenClaw 的能力是通过技能（Skill）扩展的。每个技能都是一个模块化、自包含的包，为 AI 提供特定领域的专业知识、工作流程和工具集成。
可以把技能理解为给 AI 的「操作手册」：当遇到特定任务时，AI 会根据技能文档的指引，按正确的步骤完成工作。好的技能文档能让 AI 少走弯路，准确率大大提升。
技能的本质：把人类总结的最佳实践，变成 AI 可以遵循的流程。
技能的目录结构
一个标准的技能目录结构如下：
skill-name/├── SKILL.md （必需，核心文档）└── 可选资源目录 ├── scripts/ （可执行脚本，Python/Bash 等） ├── references/（参考文档，按需加载） └── assets/ （静态资源，模板、图标、字体等）核心原则：保持简洁，避免冗余。只包含 AI 完成任务真正需要的内容。
不要创建这些文件
技能是给 AI 读的，不是给人类用户看的传统开源项目。不要添加这些冗余文件：
❌ README.md ❌ INSTALLATION_GUIDE.md ❌ CHANGELOG.md ❌ 其他无关文档
所有信息都应该整合到 SKILL.md 或对应的资源目录中。
SKILL.md 详解
SKILL.md 是每个技能必需的核心文件，它由两部分组成：
- YAML 前置元数据
（必需）- 包含 name 和 description，决定技能何时被触发 - Markdown 正文
（必需）- 详细的使用说明和工作流程
第一步：编写 YAML 前置元数据
SKILL.md 开头必须是 YAML 前置元数据：
---name: skill-creatordescription: Create, edit, improve, or audit AgentSkills. Use when creating a new skill from scratch or when asked to improve, review, audit, tidy up, or clean up an existing skill or SKILL.md file. Also use when editing or restructuring a skill directory (moving files to references/ or scripts/, removing stale content, validating against the AgentSkills spec). Triggers on phrases like "create a skill", "author a skill", "tidy up a skill", "improve this skill", "review the skill", "clean up the skill", "audit the skill".---重要说明：只有 name 和 description 两个字段，不要添加其他字段。
name 字段
技能的名称，简洁明了 使用小写字母、数字和连字符，不允许空格和特殊字符 例如： weather、baidu-search、ai-news-collector
description 字段（重中之重）
description 是 AI 判断是否触发该技能的唯一依据，必须写清楚：
- 这个技能做什么
- 什么时候应该使用它
（列出具体的触发场景和关键词）
写作技巧：把所有「什么时候用」的信息都写在 description 里，不要放在正文中。因为正文只有技能触发后才会被加载。
好的例子：
description: Get current weather and forecasts (no API key required). Use when users ask about weather, temperature, forecast, rain, sunshine for any location.不好的例子：
description: Weather module.（AI 不知道什么时候该用它）
第二步：编写 Markdown 正文
正文是给 AI 看的操作指南，遵循以下原则：
1. 简洁至上
上下文窗口是宝贵的公共资源。记住：AI 已经很聪明了，只需要补充 AI 没有的知识。
每一段内容都问问自己：「AI 真的需要这段解释吗？」
原则：偏好简洁的例子，胜过冗长的解释。
2. 合理控制自由度
根据任务的特点，选择合适的具体程度：
- 高自由度（文字指南）：
多种方法都可行，决策依赖上下文时使用 - 中等自由度（伪代码/带参数脚本）：
有偏好模式，但允许变化时使用 - 低自由度（固定脚本，少量参数）：
操作容易出错，需要一致性时使用
想象一下：窄桥需要护栏（低自由度），旷野可以走任意路线（高自由度）。
3. 渐进式披露原则
OpenClaw 使用三级加载机制来高效管理上下文：
**元数据（name + description）**- 始终在上下文中（约 100 词） - SKILL.md 正文
- 技能触发后加载（控制在 500 行以内） - 绑定资源
- 需要时才加载（不受上下文限制）
当内容较多时，拆分到参考文件中，只在需要时加载：
# 我的技能## 快速开始[基础用法...]## 高级功能- **表单填写**：参见 [FORMS.md](references/FORMS.md)- **API 参考**：参见 [REFERENCE.md](references/REFERENCE.md)- **使用示例**：参见 [EXAMPLES.md](references/EXAMPLES.md)最佳实践：多个变体支持时，只在 SKILL.md 保留核心流程和选择指南，变体细节放到独立参考文件中。
资源目录详解
scripts/ - 可执行代码
存放需要确定性执行、会被重复使用的代码。
什么时候用：
相同代码需要反复生成时 需要确定性结果时 例如： scripts/rotate_pdf.py用于 PDF 旋转
优点：节省 token，结果确定，可以直接执行不用读入上下文。
references/ - 参考文档
存放详细的参考资料，AI 在工作过程中按需读取。
什么时候用：
数据库表结构定义 API 文档 公司政策和规范 详细的工作流程指南 多个工具/框架的变体说明
避免重复：信息要么在 SKILL.md，要么在参考文件中，不要两边都放。核心流程放在 SKILL.md，详细参考材料放到 references 目录。
如果参考文件超过 100 行，建议在文件开头加目录，方便 AI 快速定位。
assets/ - 静态资源
存放生成结果时会用到的文件，不会被加载到上下文中。
什么时候用：
品牌 Logo 图片 文档模板（PPT、Word 等） 代码脚手架模板 字体文件 示例文档
这样可以把输出资源和文档分开，AI 使用文件时不需要把文件内容读入上下文。
命名规范
技能文件夹名称必须和技能名称一致 只使用小写字母、数字和连字符 不超过 64 个字符 偏好简短、动词开头的短语 示例： wechat-image-generator、baidu-search
创建技能的完整流程
步骤 1：理解需求
明确这个技能要解决什么问题，收集具体的使用示例：
用户会说什么话触发这个技能？ 这个技能需要支持哪些功能？ 能不能给出几个实际使用的例子？
当有了清晰具体的认识后，再进行下一步。
步骤 2：规划资源
分析每个使用场景，确定需要哪些可复用资源：
需要重复执行的代码 → 放到 scripts/需要参考的详细文档 → 放到 references/输出用的模板资源 → 放到 assets/
步骤 3：初始化技能
使用官方脚本快速创建：
python /usr/lib/node_modules/openclaw/skills/skill-creator/scripts/init_skill.py \ your-skill-name --path ./skills \ --resources scripts,references,assets这个脚本会：
创建技能目录 生成 SKILL.md 模板 根据参数创建资源目录
步骤 4：添加资源
先添加你规划好的资源：
脚本需要实际运行测试，确保没有 bug 参考文档按主题整理好 删掉不需要的占位文件
步骤 5：编写 SKILL.md
按照本文的指导，先写好 YAML 前置元数据，再写正文指引。记住：
description 一定要写清楚什么时候用这个技能 正文只保留核心流程，细节拆分到参考文件 保持简洁，控制在 500 行以内
步骤 6：打包验证
完成开发后，使用打包脚本验证并打包：
python /usr/lib/node_modules/openclaw/skills/skill-creator/scripts/package_skill.py \ path/to/your-skill-folder打包脚本会自动验证：
YAML 格式是否正确 必填字段是否完整 命名规范是否符合要求 目录结构是否合理
验证通过后会生成 .skill 文件（本质是 zip 包），可以分发安装了。
常见错误和最佳实践
❌ 常见错误
- description 太简短
- AI 不知道什么时候触发 - 正文太长
- 消耗太多上下文，影响其他功能 - 重复信息
- SKILL.md 和参考文件内容重复 - 多余文件
- 创建 README.md 等不必要文件 - 深层嵌套
- 参考文件嵌套超过一层，AI 找不到
✅ 最佳实践
- 渐进式披露
- 核心在 SKILL.md，细节按需加载 - 一次只做一件事
- 一个技能聚焦一个领域，不要贪大 - 用例子说话
- 简洁的例子胜过冗长的解释 - 测试驱动
- 用实际任务测试技能，根据反馈迭代 - 保持简洁
- 每一个 token 都值得珍惜
记住：技能是给 AI 读的，不是给人类用户读的。只需要告诉 AI 怎么做，不需要写漂亮的介绍和宣传文字。
完整示例
这是一个完整的 SKILL.md 示例：
---name: weatherdescription: Get current weather and forecasts (no API key required). Use when users ask about weather, temperature, forecast, rain, sunshine for any location.---# WeatherGet current weather and forecasts using public API. No API key required.## UsageWhen user asks about weather for a location:1. Extract the city/location from the query2. Call the weather API using this command: ```bash curl "https://wttr.in/{location}?format=j1"Parse the JSON response Present the result in a friendly, readable format
Output format
Include:
Current temperature and feels like Weather condition (sunny/rainy/cloudy/etc.) Wind speed Today's forecast (high/low)
Examples
User: "今天上海天气怎么样？"→ Location: 上海→ Call API → Format response
For more API options, see API.md
## 总结编写好的技能文档，核心就是四个词：* **清晰：**description 写清楚触发条件* **简洁：**只保留必要信息，避免上下文膨胀* **渐进：**核心在内，细节在外，按需加载* **实用：**聚焦解决具体问题遵循这个指南，你也可以写出高质量的 OpenClaw 技能，让 AI 助手越来越聪明！
