夜雨聆风一、Skill 的本质与价值
1.1 什么是 Skill
OpenClaw Skill 是可复用的能力包，本质是一个包含 SKILL.md 定义文件及相关脚本的目录。当用户请求涉及某个特定领域时，Agent 会自动扫描并激活对应的 Skill，将用户的自然语言请求转化为具体的工具调用序列。
与传统 Tool 相比，Skill 的粒度更大——它不是单一功能的函数调用，而是多个操作的有序组合。例如，一个“创建会议”的 Skill 实际上封装了以下完整流程：查询参与人信息、创建会议实例、发送会议邀请。一个设计良好的 Skill 应该是“交给我这件事，我能完整搞定”的程度。
1.2 Skill 的核心价值
理解 Skill 的价值，有助于我们在编写时做出更好的设计决策：
能力抽象是 Skill 最直接的价值。将重复性的操作封装为可调用模块，避免每次遇到相同场景都重新描述需求。设想一个团队中有五个 Agent 都需要查询天气，如果没有 Skill，每个 Agent 都需要各自理解如何调用天气 API；有了 Skill，一次封装，五个 Agent 都能使用。
一键激活意味着 Agent 可以在运行时自动发现和加载工作区中的 Skill。编写合格的 Skill 定义后，Agent 无需人工干预即可在恰当的时机启用对应能力。
跨 Agent 共享特性使得 Skill 成为团队协作的基础设施。多个 Agent 可以共用同一 Skill，保持能力的一致性，同时也便于集中维护和更新。
版本管理能力则保证了 Skill 的演进可以可控地进行。当 Skill 升级时，使用它的 Agent 可以选择同步到最新版本或锁定在特定版本。
二、Skill 目录结构规范
2.1 标准目录布局
一个生产级别的 Skill 目录应当遵循以下结构：
~/.openclaw/extensions/xxx/skills/weather/├── SKILL.md # 技能定义文件（必需）├── references/ # 参考资料目录│ └── api_docs.md├── scripts/ # 辅助脚本目录│ └── setup.sh└── config.json # 配置文件（可选）其中 SKILL.md 是唯一必需的文件，其他目录和文件均为可选。保持目录简洁有助于 Skill 的维护和理解。
2.2 核心文件说明
需要特别强调的是，SKILL.md 不仅是给 Agent 看的定义文件，也是未来维护者和协作者理解 Skill 的主要入口。编写清晰的 SKILL.md 是 Skill 编写者最重要的职责。
三、SKILL.md 编写深度指南
3.1 文件格式：YAML frontmatter + Markdown
SKILL.md 采用 YAML frontmatter + Markdown 正文 的混合格式。Frontmatter 用于定义元数据，正文用于描述详细规范。这种格式既便于程序解析关键信息，也保留了人类可读的自然语言描述能力。
一个完整的 SKILL.md 示例：
---name: weatherdescription: 获取当前天气和天气预报trigger: 当用户询问天气、温度、湿度、预报时触发platform: wttr.in / Open-Meteo（无需 API Key）---# 天气查询技能## 触发条件当用户提及以下关键词时自动激活：- "天气"- "温度"- "预报"- "下雨吗"## 能力范围1. 查询指定城市的当前天气2. 提供 3 天天气预报3. 给出穿着建议3.2 Frontmatter 字段详解
Frontmatter 中的字段是 Skill 的“名片”，Agent 和其他系统在加载 Skill 时首先读取这些信息：
weather | |||
查询天气和预报 | |||
用户询问天气时触发 | |||
wttr.in | |||
1.0.0 | |||
OpenClaw Team |
其中 name 和 trigger 是最关键的两个字段。name 是系统的唯一标识，trigger 决定了 Skill 何时被激活。编写这两个字段时需要反复推敲，确保既不过于宽泛导致误触发，也不至于过于狭窄而遗漏有效场景。
3.3 正文结构建议
正文的结构应当包含以下核心章节：
触发条件是必选章节。需要明确说明什么情况下激活该 Skill。建议采用“关键词列表 + 场景描述”的双重方式，既覆盖明确的关键词触发，也涵盖语义相近的自然语言表述。
能力范围是必选章节。列出 Skill 可以完成的所有任务，使用清晰的动词开头（如“查询”、“创建”、“编辑”、“删除”、“发送”），避免模糊表述。
使用限制是必选章节。必须明确说明 Skill 不能做什么，包括：不支持的文件格式、超出能力范围的操作、风险操作提醒等。清晰的边界定义是避免 Agent 行为出格的关键。
调用示例是推荐章节。提供 1-2 个典型的用户请求与 Agent 响应示例，帮助理解 Skill 的实际使用方式。
注意事项是可选章节。补充说明如依赖服务优先级、回退策略、特殊情况处理等信息。
四、触发条件设计最佳实践
4.1 好的触发条件 vs 不好的触发条件
触发条件是 Skill 生效的“开关”，设计时需要格外谨慎。
好的触发条件具备以下特征：
明确具体：用户说“创建会议”、“预约会议”时触发，而不是“处理会议相关任务” 可匹配：使用具体的关键词或短语，便于 Agent 进行文本匹配 避免歧义：不会与其他常见表达产生混淆
❌ 不好的触发条件则包括：
过于宽泛：如“处理文档相关任务”——什么是“文档相关”？几乎任何请求都可能涉及文档 难以匹配：如“根据上下文判断”——这种模糊条件依赖Agent的推理能力，不够可靠 语义不清：使用模棱两可的表述，导致 Agent 无法确定是否应该激活
4.2 关键词选择策略
选择关键词时，建议遵循以下策略：
优先选择核心动作词：如“创建”、“查询”、“发送”、“删除”。这些词直接对应具体操作，误触发概率低。
覆盖同义词和变体：中文表达丰富，“天气”、“气温”、“多少度”、“冷不冷”都可能是在问天气。建议列出常见表达变体。
排除干扰项：注意避免与日常高频词汇冲突。例如，“删除”是高风险词，如果 Skill 涉及删除操作，触发条件应当更加严格。
一个经过仔细设计的触发条件示例：
## 触发条件用户提及以下任一场景时激活：- 明确动作：创建会议、预约会议、安排会议、发起会议- 时间相关：定个会议、约个时间、什么时候开会- 上下文暗示：需要把大家聚一下、让大家空出时间五、能力描述与边界明确
5.1 能力描述规范
能力描述应当使用清晰的动词，并确保每个能力项都是可验证、可执行的。
推荐格式：
## 能力范围1.**查询天气**：获取指定城市的当前温度、湿度、风力、空气质量2.**短期预报**：提供未来 3 天的天气预报，包括最高/最低温度和降水概率3.**穿着建议**：根据温度和天气情况给出衣服厚度和出行建议注意每个能力项都应当有明确的输出预期。“给出穿着建议”是一个结果导向的描述，Agent 很清楚完成这个能力后需要产出什么。
5.2 边界明确：必须告诉 Agent 不能做什么
这是最容易被忽视但却至关重要的部分。明确的边界定义可以避免 Agent 做出超出预期的行为。
## 使用限制- 仅支持全球主要城市查询，不支持自定义地点- 不提供历史天气数据查询- 不发送灾害性天气预警（超出能力范围）- 不提供分钟级精确预报边界的定义应当基于实际能力而非“假设能力”。如果你不确定某个功能能否实现，最好的做法是先不承诺，等待 Skill 迭代完善后再添加。
5.3 工具封装原则
Skill 应当封装完整的操作流程，而非仅仅暴露单一工具调用。
❌ 不好的实践：将 Skill 等同于某个工具的包装
## 能力调用 weather API 查询天气✅ 好的实践：封装完整的用户任务闭环
## 能力：会议创建完整的会议创建流程：1. 调用 `wecom_meeting_create` 创建会议2. 调用 `wecom_mcp call contact getContact` 查询参与人信息3. 调用 `wecom_mcp call meeting invite` 发送会议邀请4. 返回创建结果给用户后者不仅告诉 Agent 可以调用什么工具，还说明了调用的顺序和目的，形成一个完整的任务闭环。
六、Skill 编写常见问题
Q1: Skill 和 Tool 有什么区别？
这是最常见的问题。从技术实现角度看，两者有以下区别：
简单来说，Tool 是 Agent 的“手”，Skill 是 Agent 的“技能手册”。Agent 通过 Skill 理解自己可以做什么，通过 Tool 具体去做。
Q2: 一个 Skill 应该包含多少功能？
建议一个 Skill 聚焦一个完整任务域，而不是把各种相关不相关的功能都塞进去。
✅ 好的例子：
wecom-meeting-create- 专注于会议创建相关能力wecom-schedule- 专注于日程管理相关能力wecom-contact-lookup- 专注于通讯录查询能力
❌ 不好的例子：
office-all-in-one- 功能太杂，难以维护和理解wecom-everything- 试图覆盖企业微信所有功能
一个判断标准是：用户是否能用一句话说清楚这个 Skill 的用途。如果需要用“既可以...又可以...还可以...”来描述，说明这个 Skill 可能过于庞大，需要拆分。
Q3: 如何调试 Skill？
Skill 编写完成后，需要通过实际测试验证其行为：
使用 openclaw skills list命令查看已加载的 Skills，确认 Skill 被正确识别在 Agent 对话中使用相应的触发语句，观察 Skill 是否被正确激活 检查 Agent 的决策日志，确认 Skill 激活的时机和调用链是否符合预期 测试边界情况，确认限制条件是否生效
Q4: Skill 可以调用其他 Skill 吗？
当前版本不支持 Skill 间直接调用。这一设计是有意为之——Skill 是定义文件，不是可执行代码。如果需要实现跨 Skill 的协作，应当通过 Agent 的工具调用链来实现：让一个 Agent 在完成自己的任务后，再调用其他工具或触发其他 Skill。
七、总结：Skill 编写的核心原则
回顾全文，一个高质量的 OpenClaw Skill 应当遵循以下原则：
触发条件要精准：明确具体，避免宽泛，减少误触发概率。
能力边界要清晰：明确告诉 Agent 能做什么和不能做什么。
封装要完整：Skill 应当封装完整的任务闭环，而非单一工具调用。
命名要规范：name 字段使用小写字母和连字符，保持全局唯一。
维护要持续：随着使用中发现的问题，持续优化触发条件和能力描述。
Skill 是 OpenClaw 能力扩展的基础单元。好的 Skill 设计，可以让 Agent 从“能说会道”走向“能说会做”，真正成为用户的数字助手。希望本文提供的规范和实践建议，能够帮助技术读者快速上手 Skill 编写，构建出高质量的能力扩展。
📢 关于我们
本文由**「老易在」小龙虾团队——老易与四虾居**辅助创作而成。
如果你对 AI话题感兴趣，欢迎关注我们，一起探索"养小龙虾"的乐趣！
"老易与四虾居"的四名成员：司理、采微、染翰、丹青
