一、技能核心概念
在 OpenClaw 中，技能（Skill） 并非传统二进制插件 / 代码模块，本质是带规则说明的目录 + SKILL.md 文档。智能体会读取文档内的指令、流程、权限规则，自动完成对应业务逻辑。
最简技能结构仅两层：
plaintext
my-skill/
└── SKILL.md
二、技能目录结构
根据功能复杂度，分为最小结构和完整结构。
1. 最小结构（简单功能推荐）
仅必备配置文件，适合单一场景、轻量化技能：
plaintext
my-skill/
└── SKILL.md # 技能核心规则文件（必选）
2. 完整结构（复杂功能推荐）
支持脚本、模板、独立配置文件，适合多流程、带依赖的技能：
plaintext
my-complex-skill/
├── SKILL.md # 技能元数据+使用规则（核心必选）
├── install.sh # 自定义安装脚本（可选）
├── templates/ # 文本/文档模板目录（可选）
│ └── report.md
└── config/ # 技能独立配置（可选）
└── defaults.json
三、SKILL.md 标准格式
SKILL.md 分为两大块：YAML 头部元数据（Frontmatter） + Markdown 正文规则，头部和正文之间用空行分隔。
3.1 基础必填元数据
所有技能必须配置 name 和 description，放在文件最顶部：
yaml
---
name: my-weather-skill
description: 查询多城市天气预报，支持温度、风力、天气预警查询
---
表格
| 字段 | 类型 | 说明 |
|---|---|---|
name | 字符串 | 技能唯一标识，统一使用小写字母 + 连字符，全局不可重复 |
description | 字符串 | 一句话简介，展示在技能列表中 |
3.2 常用可选元数据
拓展技能属性、主页、调用权限等：
yaml
---
name: my-weather-skill
description: 查询多城市天气预报，支持温度、风力、天气预警查询
homepage: https://github.com/xxx/xxx
user-invocable: true
disable-model-invocation: false
command-dispatch: false
version: 1.0.0
---
表格
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
homepage | 字符串 | – | 技能项目地址、文档地址 |
user-invocable | 布尔 | true | 是否允许用户手动调用 |
disable-model-invocation | 布尔 | false | 是否禁止模型自动调用 |
command-dispatch | 布尔 | false | 是否开启命令分发模式 |
version | 字符串 | – | 技能版本号，用于版本管理 |
3.3 调用权限组合说明
通过两个布尔字段控制调用主体，适配不同使用场景：
表格
| 配置组合 | 用户可调用 | 模型自动调用 | 适用场景 |
|---|---|---|---|
| 默认（不配置） | ✅ | ✅ | 通用日常技能 |
user-invocable: false | ❌ | ✅ | 内部辅助技能，仅模型后台调用 |
disable-model-invocation: true | ✅ | ❌ | 敏感操作，仅允许用户手动触发 |
两者均设为 false | ❌ | ❌ | 技能禁用，无实际用途 |
3.4 运行前置门控（Requires）
用于声明技能运行依赖，不满足条件则技能不会加载，避免报错。
1）依赖命令行工具 requires.bins
检测系统是否存在指定命令，常用于运维、容器类技能：
yaml
---
name: docker-manager
description: 容器启停、状态查询管理
requires:
bins:
- docker
- docker-compose
---
2）依赖环境变量 requires.env
检测系统环境变量，多用于各类 API 密钥类技能：
yaml
---
name: openai-helper
description: OpenAI 模型辅助调用
requires:
env:
- OPENAI_API_KEY
---
3）依赖网关配置项 requires.config
检测 openclaw.json 中的指定配置：
yaml
---
name: github-review
description: GitHub PR 自动审查
requires:
config:
- github.token
---
4）快捷单变量 primaryEnv
仅依赖单个环境变量时，可简化写法：
yaml
---
name: weather-api
description: 第三方天气接口查询
primaryEnv: WEATHER_API_KEY
---
5）操作系统过滤 os
限定技能仅在指定系统加载，可选值：darwin(macOS)、linux、win32(Windows)
yaml
---
name: macos-auto-tool
description: macOS 桌面自动化工具
os:
- darwin
---
3.5 自动安装依赖（installers）
声明技能所需外部包 / 二进制，安装技能时自动拉取依赖，支持多种安装器。
基础语法示例
yaml
---
name: data-processor
description: 批量数据解析处理
installers:
- type: node
package: csv-parser
- type: brew
package: jq
---
安装器类型对照表
表格
| 类型 | 适用场景 | 示例 |
|---|---|---|
brew | macOS / Linux Homebrew 工具 | brew: jq |
node | npm 全局包 | node: typescript |
go | Go 语言工具 | go: github.com/xxx/tool@latest |
uv | Python 包管理 | uv: requests |
download | 下载独立二进制文件 | 配置 URL、权限、存放路径 |
download 二进制下载示例
yaml
---
name: special-bin-tool
description: 第三方二进制工具调用
installers:
- type: download
url: https://xxx/releases/tool-linux-amd64
target: tool
chmod: true
---
target：保存后的文件名chmod: true：自动添加可执行权限
四、Markdown 正文编写规范（核心规则）
正文是给智能体执行的操作手册，遵循 5 大编写原则，保证执行准确率。
原则 1：逻辑清晰，步骤化描述
直接写明触发条件 + 执行步骤，拒绝冗余文案：
markdown
## 使用方法
当用户询问天气时，按以下流程执行：
1. 使用 `web_search` 工具搜索「{城市} 今日天气预报」
2. 提取温度、风力、天气状况、湿度数据
3. 整理信息并简洁回复用户
原则 2：明确安全规则，划定禁区
强制约束高危操作，规避数据、权限风险：
markdown
## 安全规则
- 禁止执行文件删除、系统配置修改操作
- 禁止输出用户密钥、密码等敏感信息
- 涉及高危操作，必须先向用户二次确认
- 禁止执行未知外部脚本
原则 3：使用 {baseDir} 引用技能路径
技能包含模板、配置等附属文件时，用 {baseDir} 占位符（运行时自动替换为技能真实目录）：
markdown
## 模板使用
读取 `{baseDir}/templates/report.md` 作为报告模板，替换占位内容后生成文档。
原则 4：补充交互示例
提供对话样例，让智能体理解交互格式与输出风格：
markdown
## 交互示例
用户：帮我查上海明天天气
助手：上海明日天气预报
🌡 气温：18℃ ~ 26℃
💨 风力：东南风 2~3级
☁ 天气：多云，局部有小雨
温馨提示：出门建议携带雨具。
原则 5：声明依赖工具
明确技能需要调用的内置工具，避免智能体调用出错：
markdown
## 依赖工具
本技能需调用以下内置工具：
- web_search：网络信息检索
- read：读取本地模板文件
- write：生成并保存文档
五、技能存放路径 & 加载优先级
OpenClaw 按优先级从高到低依次加载技能，同名技能会被高优先级版本覆盖，开发测试建议使用最高优先级目录。
表格
| 优先级 | 目录路径 | 说明 |
|---|---|---|
| 1（最高） | ~/.openclaw/workspace/skills/ | 工作区技能，开发测试首选 |
| 2 | 当前项目 skills/ | 项目局部技能 |
| 3 | ~/.openclaw/skills/ | 个人全局技能 |
| 4 | ClawHub 托管目录 | clawhub install 在线安装的技能 |
| 5 | 系统内置技能 | OpenClaw 原生自带技能 |
| 6（最低） | extraDirs | 配置文件额外指定目录 |
开发目录创建命令
bash
运行
# 在最高优先级目录创建自定义技能文件夹
mkdir -p ~/.openclaw/workspace/skills/my-new-skill
# 编辑核心文件
nano ~/.openclaw/workspace/skills/my-new-skill/SKILL.md
六、本地测试与调试
技能编写完成后，分步骤测试加载、调用、异常场景。
1. 基础快速测试
直接传参调用会话，验证功能是否正常：
bash
运行
openclaw agent --message "帮我查询北京天气"
2. 交互式深度测试
进入交互终端，测试多轮对话、边界场景、异常输入：
bash
运行
openclaw
3. 排错调试命令
bash
运行
# 查看全部已加载技能，确认自定义技能是否存在
clawhub list
# 全局环境诊断，检测技能门控、语法、路径问题
openclaw doctor
# 过滤日志，查看技能加载详情
openclaw gateway logs | grep skill
常见加载失败原因
SKILL.md头部 YAML 语法错误（冒号、缩进、符号问题）；- 门控条件不满足（缺失命令、环境变量、系统不匹配）；
- 目录放置错误，不在技能检索路径内；
- 高优先级目录存在同名技能，被覆盖。
七、技能发布到 ClawHub
本地测试无误后，可发布至官方技能中心，供全网用户使用。
1. 发布前置准备
- 检查
SKILL.md元数据完整，无语法错误； - 清理目录临时文件、日志、缓存；
- 提前注册 ClawHub 账号。
2. 账号登录
bash
运行
clawhub login
按照终端提示完成账号认证。
3. 发布技能
bash
运行
# 发布当前目录下所有技能
clawhub sync --all
# 指定单个技能目录发布
clawhub sync ./my-new-skill
- 未手动指定
version时，系统自动递增版本号； - 如需固定版本，在
SKILL.md头部添加version字段。
4. 发布后验证
bash
运行
# 终端搜索已发布技能
clawhub search my-new-skill
# 另一台设备测试安装
clawhub install my-new-skill
八、完整实战示例：代码审查技能
1. 完整 SKILL.md
yaml
---
name: code-review-helper
description: 代码审查助手，检查规范、漏洞、性能问题并给出优化建议
homepage: https://github.com/xxx/code-review-helper
version: 1.0.0
requires:
bins:
- git
env:
- GITHUB_TOKEN
user-invocable: true
disable-model-invocation: false
---
## 功能说明
针对代码片段、GitHub PR 进行代码审查，输出标准化评审意见。
## 使用流程
### 场景1：审查代码片段
1. 读取用户粘贴的代码内容
2. 依次检查：命名规范、异常处理、性能、安全漏洞、可读性
3. 按等级分类输出评审结果
### 场景2：审查 GitHub PR
1. 使用 `exec` 执行 `git diff` 获取代码变更
2. 逐文件分析变更内容
3. 汇总全部问题与优化建议
## 审查维度
1. 命名规范：变量、函数、文件命名是否统一
2. 异常处理：是否存在未捕获异常
3. 性能问题：循环嵌套、重复查询、无效逻辑
4. 安全风险：明文密钥、注入漏洞、权限问题
5. 代码可读性：注释、逻辑分层
## 输出格式
🔴 **严重问题（必须修复）**
- 问题描述 + 修复方案
🟡 **优化建议（可选改进）**
- 优化点 + 参考代码
🟢 **亮点**
- 优秀设计与写法
## 安全规则
1. 仅输出评审建议，**禁止修改/删除任何代码文件**
2. 发现密钥、账号等敏感信息，仅做提醒，不展示完整内容
3. 禁止执行代码片段中的命令、脚本
## 依赖工具
- exec：执行 git 命令
- read：读取代码文件
九、总结
- 自定义技能核心 = 目录 + SKILL.md，本质是给智能体的操作手册；
- 头部 YAML 配置元数据、调用权限、依赖门控、自动安装器；
- 正文分步骤写清流程、规则、示例、工具依赖，越严谨执行越稳定；
- 开发测试优先使用工作区技能目录（最高优先级）；
- 本地通过
clawhub list、openclaw doctor排错，测试完成后通过clawhub sync发布。