## 什么是技能
在 OpenClaw 中，技能（Skill）是一个包含 `SKILL.md` 文件的目录。SKILL.md 用 Markdown 编写，告诉智能体**这个技能能做什么**以及**怎么使用它**。
技能不是传统意义上的"插件"或"代码模块"——它更像是一份**操作手册**，智能体读取后就知道如何完成特定任务。
一个最简单的技能结构：
```
my-skill/
└── SKILL.md
```
就这么简单。一个目录，一个 Markdown 文件。
## 技能文件结构
### 最小结构
```
my-weather-skill/
└── SKILL.md
```
### 完整结构
复杂技能可能包含额外文件：
```
my-complex-skill/
├── SKILL.md # 技能说明（必须）
├── install.sh # 安装脚本（可选）
├── templates/ # 模板文件（可选）
│ └── report.md
└── config/ # 配置文件（可选）
└── defaults.json
```
## SKILL.md 文件格式
SKILL.md 由两部分组成：**YAML frontmatter**（元数据）和 **Markdown 正文**（说明内容）。
### 必填字段
```yaml
---
name: my-weather-skill
description: 查询全球天气预报，支持多城市、多天预测和天气预警
---
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 技能的唯一标识符，建议用小写字母和连字符 |
| `description` | string | 技能的简短描述，一句话说明功能 |
### 可选字段
```yaml
---
name: my-weather-skill
description: 查询全球天气预报
homepage: https://github.com/yourname/my-weather-skill
user-invocable: true
disable-model-invocation: false
command-dispatch: false
---
```
| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `homepage` | string | — | 技能主页 URL |
| `user-invocable` | boolean | `true` | 用户是否可以直接调用此技能 |
| `disable-model-invocation` | boolean | `false` | 是否禁止模型自动调用此技能 |
| `command-dispatch` | boolean | `false` | 是否启用命令分发模式 |
### user-invocable vs disable-model-invocation
这两个字段控制技能的调用方式：
| 组合 | 用户可调用 | 模型可自动调用 | 适用场景 |
|------|-----------|---------------|----------|
| 默认（都不设） | ✅ | ✅ | 通用技能 |
| `user-invocable: false` | ❌ | ✅ | 仅供模型内部使用的辅助技能 |
| `disable-model-invocation: true` | ✅ | ❌ | 用户手动触发的敏感操作 |
| 两者都设 | ❌ | ❌ | 基本没用，等于禁用 |
## Metadata 门控
metadata 门控让技能声明运行前提条件，OpenClaw 会在加载技能时自动检查。
### requires.bins — 依赖的命令行工具
```yaml
---
name: docker-manager
description: 管理 Docker 容器
requires:
bins:
- docker
- docker-compose
---
```
如果用户系统上没有安装 `docker` 或 `docker-compose`，这个技能不会被加载。
### requires.env — 依赖的环境变量
```yaml
---
name: openai-helper
description: 使用 OpenAI API 的辅助技能
requires:
env:
- OPENAI_API_KEY
---
```
如果 `OPENAI_API_KEY` 环境变量未设置，技能不会被加载。
### requires.config — 依赖的配置项
```yaml
---
name: github-pr-reviewer
description: 自动审查 GitHub PR
requires:
config:
- github.token
---
```
### primaryEnv — 主要环境变量
```yaml
---
name: weather-api
description: 天气查询
primaryEnv: WEATHER_API_KEY
---
```
`primaryEnv` 是一个快捷方式，等同于 `requires.env` 中只有一个变量的情况。
### os — 操作系统过滤
```yaml
---
name: macos-automation
description: macOS 自动化操作
os:
- darwin
---
```
可选值：`darwin`（macOS）、`linux`、`win32`（Windows）。只在指定的操作系统上加载。
## Markdown 说明编写最佳实践
SKILL.md 的正文部分是技能的核心——它告诉智能体如何使用这个技能。
### 原则一：简洁明了
智能体不需要冗长的背景介绍。直接告诉它**做什么**和**怎么做**：
```markdown
## 使用方法
当用户询问天气时：
1. 使用 `web_search` 工具搜索 "{城市} 天气预报"
2. 提取温度、湿度、风力信息
3. 用简洁的格式回复用户
```
### 原则二：安全优先
明确告诉智能体什么**不能做**：
```markdown
## 安全规则
- 不要执行任何删除操作
- 不要修改系统配置文件
- 操作前必须确认用户意图
- 敏感信息不要输出到日志
```
### 原则三：使用 {baseDir} 引用技能路径
如果技能包含额外文件（模板、配置等），使用 `{baseDir}` 占位符引用技能目录：
```markdown
## 报告模板
使用 `{baseDir}/templates/report.md` 作为报告模板。
读取模板内容，替换其中的占位符后生成最终报告。
```
`{baseDir}` 会在运行时被替换为技能的实际安装路径。
### 原则四：提供示例对话
帮助智能体理解预期的交互方式：
```markdown
## 示例
用户：帮我查一下北京明天的天气
助手：北京明天（1月16日）天气预报：
- 🌡 温度：-5°C ~ 3°C
- 💨 风力：北风 3-4 级
- 🌤 天气：晴转多云
- 💧 湿度：35%
建议明天出门多穿点，注意防风。
```
### 原则五：声明工具依赖
如果技能需要使用特定工具，明确列出：
```markdown
## 依赖工具
此技能需要以下工具：
- `web_search`：搜索天气信息
- `read`：读取模板文件
- `write`：保存天气报告
```
## 技能存放位置和优先级
OpenClaw 从多个位置加载技能，按优先级从高到低：
| 优先级 | 位置 | 说明 |
|--------|------|------|
| 1（最高） | 工作区技能 | `~/.openclaw/workspace/skills/` |
| 2 | 项目技能 | 当前项目目录下的 `skills/` |
| 3 | 个人技能 | `~/.openclaw/skills/` |
| 4 | 托管技能 | 通过 `clawhub install` 安装的技能 |
| 5 | 内置技能 | OpenClaw 自带的技能 |
| 6（最低） | extraDirs | 配置文件中指定的额外目录 |
如果多个位置存在同名技能，高优先级的会覆盖低优先级的。
### 开发时推荐的存放位置
开发新技能时，建议放在工作区技能目录：
```bash
mkdir -p ~/.openclaw/workspace/skills/my-new-skill
nano ~/.openclaw/workspace/skills/my-new-skill/SKILL.md
```
这样优先级最高，方便测试和迭代。
## 本地测试
### 快速测试
创建好 SKILL.md 后，直接用命令行测试：
```bash
# 发送一条消息，看智能体是否正确使用了你的技能
openclaw agent --message "帮我查一下北京的天气"
```
### 交互式测试
启动交互式会话进行更深入的测试：
```bash
# 启动 TUI 交互界面
openclaw
```
然后在对话中测试各种场景：
- 正常使用场景
- 边界情况（如缺少参数）
- 错误处理（如 API 不可用）
### 调试技巧
```bash
# 查看已加载的技能列表
clawhub list
# 检查技能是否被正确加载
openclaw doctor
# 查看技能加载日志
openclaw gateway logs | grep "skill"
```
如果技能没有被加载，常见原因：
1. **SKILL.md 格式错误**：YAML frontmatter 语法不正确
2. **门控条件不满足**：缺少依赖的命令行工具或环境变量
3. **目录位置不对**：技能目录不在 OpenClaw 的搜索路径中
4. **同名冲突**：高优先级位置有同名技能覆盖了你的技能
## 发布到 ClawHub
当技能开发完成并测试通过后，可以发布到 ClawHub 供其他用户使用。
### 准备工作
1. 确保 SKILL.md 的 frontmatter 完整（name、description 必填）
2. 确保技能目录结构干净，没有临时文件
3. 注册 ClawHub 账号（如果还没有）
### 登录 ClawHub
```bash
clawhub login
```
按提示完成认证。
### 发布技能
```bash
# 发布当前目录下的技能
clawhub sync --all
# 发布指定目录的技能
clawhub sync ./my-weather-skill
```
### 版本管理
每次发布会自动递增版本号。你也可以在 frontmatter 中手动指定版本：
```yaml
---
name: my-weather-skill
description: 查询天气预报
version: 1.2.0
---
```
### 发布后验证
```bash
# 搜索你发布的技能
clawhub search my-weather-skill
# 在另一台机器上安装测试
clawhub install my-weather-skill
```
## 安装器规范
如果你的技能依赖外部工具，可以在 SKILL.md 中声明安装器，OpenClaw 会在安装技能时自动安装依赖。
### 支持的安装器类型
| 安装器 | 说明 | 示例 |
|--------|------|------|
| `brew` | Homebrew（macOS/Linux） | `brew: jq` |
| `node` | npm 全局包 | `node: typescript` |
| `go` | Go 工具 | `go: github.com/user/tool@latest` |
| `uv` | Python 包（uv） | `uv: requests` |
| `download` | 下载二进制文件 | 指定 URL 和目标路径 |
### 在 frontmatter 中声明
```yaml
---
name: data-processor
description: 数据处理工具
installers:
- type: node
package: csv-parser
- type: brew
package: jq
---
```
### download 安装器
对于需要下载二进制文件的情况：
```yaml
---
name: special-tool
description: 使用特殊工具
installers:
- type: download
url: https://github.com/user/tool/releases/latest/download/tool-linux-amd64
target: tool
chmod: true
---
```
## 完整示例：创建一个代码审查技能
下面是一个完整的技能示例，帮你把所有知识点串起来：
```yaml
---
name: code-review-helper
description: 辅助代码审查，检查常见问题并给出改进建议
homepage: https://github.com/yourname/code-review-helper
version: 1.0.0
requires:
bins:
- git
env:
- GITHUB_TOKEN
---
```
```markdown
## 功能说明
这个技能帮助你进行代码审查。当用户提供代码片段或 PR 链接时，
分析代码质量并给出改进建议。
## 使用方法
### 审查代码片段
当用户粘贴代码并要求审查时：
1. 分析代码结构和逻辑
2. 检查常见问题（命名规范、错误处理、性能）
3. 给出具体的改进建议和示例代码
### 审查 GitHub PR
当用户提供 PR 链接时：
1. 使用 `exec` 工具运行 `git diff` 获取变更
2. 逐文件分析变更内容
3. 汇总审查意见
## 审查维度
- **命名规范**：变量名、函数名是否清晰
- **错误处理**：是否有适当的 try-catch 和错误提示
- **性能**：是否有明显的性能问题（N+1 查询、不必要的循环）
- **安全**：是否有 SQL 注入、XSS 等安全风险
- **可读性**：代码是否易于理解和维护
## 输出格式
审查结果按严重程度分类：
- 🔴 **严重**：必须修复的问题
- 🟡 **建议**：建议改进的地方
- 🟢 **优点**：做得好的地方（正面反馈）
## 安全规则
- 不要修改任何代码文件，只提供建议
- 不要执行代码中的命令
- 敏感信息（API Key、密码）发现后提醒用户，但不要输出完整内容
```
## 小结
创建 OpenClaw 技能的核心流程：
1. 创建目录和 SKILL.md 文件
2. 编写 frontmatter（name + description 必填）
3. 编写 Markdown 说明（简洁、安全、有示例）
4. 按需添加 metadata 门控和安装器
5. 本地测试（`openclaw agent --message "..."`）
6. 发布到 ClawHub（`clawhub sync --all`）
记住：技能的本质是一份**操作手册**，写得越清晰，智能体执行得越准确。
---
#创建OpenClaw技能 #SKILL.md #ClawHub发布 #开发者教程 #龙虾技能库