什么是技能
在 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发布 #开发者教程 #龙虾技能库