在 OpenClaw 的世界中，Skill（技能） 是赋予智能体特定能力的基本构建单元。你可以将其理解为一份清晰的操作指南——告诉智能体：“当你面对某种情境时，应当如何响应”。无论是调用系统命令、访问网页，还是执行自定义逻辑，Skill 都是连接用户意图与具体行为的桥梁。

本章将引导你从零开始，编写一个最基础的 Skill，并逐步深入其结构设计、加载机制与工程实践。无论你是初次接触 OpenClaw 的新手，还是已有开发经验的工程师，都能从中获得实用且系统的知识。

为什么需要 Skill？

设想这样一个场景：你希望智能体不仅能回答问题，还能主动完成任务。例如：

• 用户说“给我发一封邮件”，智能体应调用邮件工具；
• 用户问“今天北京天气如何？”，智能体应访问天气 API；
• 用户要求“列出当前目录下的文件”，智能体应执行 ls 命令。

然而，智能体本身并不知道这些工具的存在，也不清楚何时该使用它们。Skill 正是用来教会它这些能力的载体。每个 Skill 明确描述了三个核心要素：

1. 触发条件
   （如用户请求问候）；
2. 目标工具
   （如 echo 或 exec）；
3. 安全调用方式
   （防止命令注入等风险）。

通过 Skill，我们将人类意图转化为可执行、可复用、可共享的行为模块。

第一步：创建 Skill 目录

OpenClaw 的所有 Skill 默认存放在工作区的 skills/ 目录下。首先，为你的新 Skill 创建专属文件夹：

mkdir -p ~/.openclaw/workspace/skills/hello-world

该路径遵循 OpenClaw 的标准工作区布局。虽然 Skill 也可置于其他位置（后文将介绍优先级机制），但对初学者而言，workspace/skills/ 是最直观且推荐的选择。

根据官方规范，一个完整的 Skill 目录结构如下：

hello-world/├── SKILL.md          # 必需：元数据 + 行为指令├── scripts/          # 可选：可执行脚本（如 Bash、Python）├── references/       # 可选：补充说明文档├── assets/           # 可选：模板、图标、配置文件等资源└── ...               # 其他自定义内容

对于入门示例，我们仅需 SKILL.md 文件即可。

第二步：编写 SKILL.md 文件

每个 Skill 的核心是一个名为 SKILL.md 的 Markdown 文件，它由两部分组成：

• YAML Frontmatter
  ：定义元数据（名称、版本、依赖等）；
• Markdown 正文
  ：用自然语言描述智能体应采取的具体行为。

下面是我们为“打招呼”功能编写的示例：

---name: hello-worldversion: 1.0.0description: 当用户请求问候时，回复友好的问候语。触发关键词包括："你好"、"打招呼"、"greet"、"say hello" 等。# Hello World 技能## 触发条件当用户发出问候类请求时（例如："您好"、"say hello"、"greet me"、"打个招呼"），直接返回预设的友好回应。## 回复内容无需调用任何外部工具，直接输出以下文本：> 你好！我是大白，随时为你服务！🤖

注意：YAML 元数据必须被两个 --- 分隔符包围，这是标准 Markdown Frontmatter 语法。

关键字段规范

OpenClaw 对 SKILL.md 的 Frontmatter 有严格格式要求，确保一致性与安全性：

✅ 有效命名示例：name: pdf-processing❌ 无效命名示例：name: PDF-Processing（含大写字母）、name: -pdf（以连字符开头）

我们的 hello-world 完全符合命名规范：全小写、无非法字符、与目录名一致。

第三步：关联工具（可选）

Skill 本身不直接执行代码，而是指导智能体调用合适的工具。OpenClaw 内置了多种工具，例如：

• exec：安全执行系统命令；
• browser：发起 HTTP 请求或渲染网页；
• email：发送邮件（需启用对应插件）。

在“Hello World”示例中，我们未使用任何工具，仅要求智能体直接输出固定文本。这种“无工具”模式适用于纯对话响应。

若需调用外部程序（如自定义脚本），可在 Frontmatter 中声明环境依赖：

compatibility: Requires Bash and standard Unix utilities

或通过实验性字段限制可用工具范围，提升安全性：

allowed-tools: Bash(echo:*)

这表示仅允许调用 echo 命令，且参数必须匹配通配规则。

第四步：加载并验证 Skill

编写完成后，需通知 OpenClaw 重新加载 Skill。推荐以下两种方式：

# 方式一：开启新聊天会话（热加载，推荐）/new# 方式二：重启网关服务（适用于全局变更）openclaw gateway restart

随后，可通过命令行验证 Skill 是否成功注册：

openclaw skills list

若输出中包含 hello-world，则说明加载成功。

第五步：测试你的 Skill

现在，向智能体发送一条可能触发该 Skill 的消息。注意：必须指定 agent 名称（默认为 main）：

openclaw agent --agent main --message "give me a greeting"

预期输出为：

你好！我是大白，随时为你服务！🤖

你也可以进入交互式聊天界面，输入“打个招呼”、“say hello”或“你好呀”，观察是否正确触发。

Skill 的加载优先级机制

OpenClaw 支持多层级的 Skill 存放路径，不同位置具有不同优先级。当存在同名 Skill 时，高优先级路径中的版本将覆盖低优先级版本。这一机制便于开发调试与环境隔离。

📌 建议：开发阶段使用 workspace/skills/，便于快速迭代；稳定后可打包发布至 ClawHub（OpenClaw 的公共 Skill 注册中心），供社区复用。

最佳实践指南

1. 指令清晰，避免模糊表述明确告诉模型“做什么”，而非“怎么想”。例如：“直接回复固定问候语”比“请友好回应”更可靠。

2. 安全优先，防范注入风险若使用 exec，切勿将用户输入直接拼接进命令。应使用固定参数、白名单校验或沙箱脚本。

3. 充分本地测试使用 openclaw agent --agent main --message "..." 多次测试边界用例，确保不会误触发、漏触发或崩溃。

4. 结构化组织内容

• 主 SKILL.md 控制在 500 行以内；
• 复杂逻辑移入 scripts/ 目录；
• 详细说明放入 references/；
• 模板、图标等资源归入 assets/。

5. 拥抱社区生态完成高质量 Skill 后，可发布至 ClawHub，参与开源协作，提升复用价值。

总结

编写 Skill 的本质，是将人类意图翻译为智能体可执行、可理解、可复现的行为规范。它不要求掌握编程语言，而强调清晰的表达、合理的工具绑定与严谨的安全设计。

通过本章的“Hello World”示例，你已掌握：

• Skill 的标准目录结构与文件格式；
• YAML 元数据的书写规范与约束；
• 工具调用的声明与安全控制；
• 加载、测试与部署的完整流程。

下一步，可尝试构建更复杂的 Skill，例如“查询实时天气”（调用 OpenWeatherMap API）、“生成二维码”（调用 Python 脚本）或“解析 PDF 文本”（集成 pdftotext 工具）。记住：每一个强大的智能体，都始于一个精心设计的 Skill。