技能
创建技能
Skills 用于教智能体如何以及何时使用工具。每个技能都是一个目录，
其中包含带有 YAML 前置元数据和 Markdown 指令的 SKILL.md 文件。
OpenClaw 会按照明确的优先级顺序从多个根目录加载技能。
创建你的第一个技能
创建技能目录
技能位于你的工作区 skills/ 文件夹中：
mkdir -p ~/.openclaw/workspace/skills/hello-world你可以将技能放在子文件夹中进行分类整理——技能名称仍由
SKILL.md 的前置元数据定义，而不是由文件夹路径定义：
mkdir -p ~/.openclaw/workspace/skills/personal/hello-world# 技能名称仍为 "hello-world"，通过 /hello-world 调用编写 SKILL.md
前置元数据定义元数据；正文为智能体提供指令。
---name: hello-worlddescription: A simple skill that prints a greeting.--- # Hello World When the user asks for a greeting, use the `exec` tool to run: ```bashecho "Hello from your custom skill!" 命名规则：- `name` 使用小写字母、数字和连字符。- 目录名称应与前置元数据中的 `name` 保持一致。- `description` 会显示给智能体，并出现在斜杠命令发现结果中—— 请保持为单行且不超过 160 个字符。 OPENCLAW_DOCS_MARKER:stepClose: OPENCLAW_DOCS_MARKER:stepOpen:IHRpdGxlPSLpqozor4HmioDog73lt7LliqDovb0i ```bashopenclaw skills list默认情况下，OpenClaw 会监视技能根目录下的 SKILL.md 文件。如果
监视器已禁用，或者你要继续使用现有会话，请启动一个新会话，
以便智能体接收刷新后的列表：
# 在聊天中——归档当前会话并重新开始/new # 或重启 Gateway 网关openclaw gateway restart测试技能
openclaw agent --message "give me a greeting"或者打开聊天，直接向智能体提出请求。使用 /skill hello-world
可按名称显式调用该技能。
SKILL.md 参考
必填字段
| 字段 | 说明 |
|---|---|
name |
使用小写字母、数字和连字符的唯一标识符 |
description |
显示给智能体并出现在发现结果中的单行说明 |
可选前置元数据键
| 字段 | 默认值 | 说明 |
|---|---|---|
user-invocable |
true |
将技能公开为用户斜杠命令 |
disable-model-invocation |
false |
不在智能体的系统提示词中包含该技能（仍可通过 /skill 运行） |
command-dispatch |
— | 设为 tool，将斜杠命令直接路由到工具并绕过模型 |
command-tool |
— | 设置 command-dispatch: tool 时要调用的工具名称 |
command-arg-mode |
raw |
使用工具分发时，将原始参数字符串转发给工具 |
homepage |
— | 在 macOS Skills 界面中显示为 “Website” 的 URL |
有关门控字段（requires.bins、requires.env 等），请参阅
Skills — 门控。
使用 {baseDir}
引用技能目录中的文件时无需硬编码路径——智能体会相对于技能自身的目录
解析 {baseDir}：
Run the helper script at `{baseDir}/scripts/run.sh`.添加条件激活
为技能设置门控，使其仅在依赖项可用时加载：
---name: gemini-searchdescription: Search using Gemini CLI.metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } }---门控选项
| 键 | 说明 |
|---|---|
requires.bins |
所有二进制文件都必须存在于 PATH 中 |
requires.anyBins |
至少一个二进制文件必须存在于 PATH 中 |
requires.env |
每个环境变量都必须存在于进程或配置中 |
requires.config |
每个 openclaw.json 路径的值都必须为真 |
os |
平台筛选器：["darwin"]、["linux"]、["win32"] |
always |
设为 true 可跳过所有门控并始终包含该技能 |
完整参考：Skills — 门控。
环境变量和 API 密钥
在 openclaw.json 中将 API 密钥关联到技能条目：
{ skills: { entries: { "gemini-search": { enabled: true, apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, }, }, },}该密钥仅在智能体的当前轮次中注入宿主进程。 它不会进入沙箱——请参阅 沙箱隔离的环境变量。
通过 Skill Workshop 提议
对于由智能体起草的技能，或者你希望技能上线前由操作员审核的情况，
请使用 Skill Workshop 提案，而不要直接编写
SKILL.md。
# 提议创建全新技能openclaw skills workshop propose-create \ --name "hello-world" \ --description "A simple skill that prints a greeting." \ --proposal ./PROPOSAL.md # 提议更新现有技能openclaw skills workshop propose-update hello-world \ --proposal ./PROPOSAL.md \ --description "Updated greeting skill"当提案包含支持文件时，请使用 --proposal-dir：
openclaw skills workshop propose-create \ --name "hello-world" \ --description "A simple skill that prints a greeting." \ --proposal-dir ./hello-world-proposal/该目录的根目录中必须包含 PROPOSAL.md。支持文件应放在
assets/、examples/、references/、scripts/ 或 templates/ 下。
审核后：
openclaw skills workshop inspect <proposal-id>openclaw skills workshop apply <proposal-id>有关完整的提案生命周期，请参阅 Skill Workshop。
发布到 ClawHub
确保你的 SKILL.md 完整
请确保已设置 name、description 和所有 metadata.openclaw 门控字段。
如果你有项目页面，请添加 homepage URL。
安装独立的 ClawHub CLI 并登录
npm i -g clawhubclawhub login发布
clawhub skill publish ./path/to/hello-world添加 --version <version> 或 --owner <owner> 可覆盖推断出的版本，
或以指定所有者身份发布。有关完整流程、所有者范围以及其他维护命令
（clawhub sync、clawhub skill rename 等），请参阅
ClawHub — 发布和
ClawHub CLI。
