如何编写高质量的 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 是每个技能必需的核心文件，它由两部分组成：

1. YAML 前置元数据
   （必需）- 包含 name 和 description，决定技能何时被触发
2. 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 判断是否触发该技能的唯一依据，必须写清楚：

1. 这个技能做什么
2. 什么时候应该使用它
   （列出具体的触发场景和关键词）

写作技巧：把所有「什么时候用」的信息都写在 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 使用三级加载机制来高效管理上下文：

1. **元数据（name + description）**- 始终在上下文中（约 100 词）
2. SKILL.md 正文
   - 技能触发后加载（控制在 500 行以内）
3. 绑定资源
   - 需要时才加载（不受上下文限制）

当内容较多时，拆分到参考文件中，只在需要时加载：

# 我的技能## 快速开始[基础用法...]## 高级功能- **表单填写**：参见 [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

这个脚本会：

1. 创建技能目录
2. 生成 SKILL.md 模板
3. 根据参数创建资源目录

步骤 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

打包脚本会自动验证：

1. YAML 格式是否正确
2. 必填字段是否完整
3. 命名规范是否符合要求
4. 目录结构是否合理

验证通过后会生成 .skill 文件（本质是 zip 包），可以分发安装了。

常见错误和最佳实践

❌ 常见错误

1. description 太简短
    - AI 不知道什么时候触发
2. 正文太长
    - 消耗太多上下文，影响其他功能
3. 重复信息
    - SKILL.md 和参考文件内容重复
4. 多余文件
    - 创建 README.md 等不必要文件
5. 深层嵌套
    - 参考文件嵌套超过一层，AI 找不到

✅ 最佳实践

1. 渐进式披露
    - 核心在 SKILL.md，细节按需加载
2. 一次只做一件事
    - 一个技能聚焦一个领域，不要贪大
3. 用例子说话
    - 简洁的例子胜过冗长的解释
4. 测试驱动
    - 用实际任务测试技能，根据反馈迭代
5. 保持简洁
    - 每一个 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"

1. Parse the JSON response
2. 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 助手越来越聪明！