创建技能
技能教智能体如何以及何时使用工具。每个技能是一个包含 SKILL.md 文件的目录,内含 YAML 前置元数据和 Markdown 指令。OpenClaw 会按定义的优先级顺序从多个根目录加载技能。
创建你的第一个技能¶
1. 创建技能目录
技能存放在你的工作区 skills/ 文件夹中:
你可以将技能分组放在子文件夹中以便组织——技能仍以 SKILL.md 前置元数据中的 name 命名,而非文件夹路径:
mkdir -p ~/.openclaw/workspace/skills/personal/hello-world
# skill name is still "hello-world", invoked as /hello-world
2. 编写 SKILL.md
前置元数据定义元信息;正文部分为智能体提供指令。
---
name: hello-world
description: A simple skill that prints a greeting.
---
# Hello World
When the user asks for a greeting, use the `exec` tool to run:
```bash
echo "Hello from your custom skill!"
```
命名规则:
name使用小写字母、数字和连字符。- 保持目录名与前置元数据中的
name一致。 description会展示给智能体,并用于斜杠命令发现——请保持在一行且不超过 160 个字符。
3. 确认技能已加载
默认情况下,OpenClaw 会监视技能根目录下的 SKILL.md 文件。如果监视器已禁用,或者你正在继续既有会话,请启动一个新会话,以便智能体获得刷新后的列表:
# From chat — archive current session and start fresh
/new
# Or restart the gateway
openclaw gateway restart
4. 测试它
或者打开聊天并直接向智能体提出请求。使用 /skill hello-world 可按名称显式调用该技能。
在共享 Gateway 上创建个人技能¶
对于应跟随你已登录资料而非属于某个智能体工作区的技能,请使用 Plugins → Skills → My skills。在那里创建或导入 SKILL.md 包,然后查看已保存的修订版本和激活结果。你不需要主机 shell 访问权限,也无需编辑共享 Gateway 设置的权限。
你也可以让智能体创建或改进个人技能。它的 skill_workshop 工具使用 Gateway 的授权库服务;它不会直接写入受管修订目录。结果会指明所发布的修订版本,并说明会话何时可以使用该修订。
请明确要求在当前会话中使用新修订,或与团队分享。
单一管理员默认仍采用上述工作区工作流。同一操作者的额外渠道身份不会将个人安装变为团队设置。关于所有权、共享、存储和会话行为,请参阅个人技能与修订。
SKILL.md 参考¶
必填字段¶
| 字段 | 描述 |
|---|---|
name |
使用小写字母、数字和连字符的唯一 slug |
description |
一行描述,展示给智能体并显示在发现输出中 |
可选前置元数据键¶
| 字段 | 默认值 | 描述 |
|---|---|---|
user-invocable |
true |
将技能公开为用户斜杠命令 |
disable-model-invocation |
false |
将技能从智能体的系统提示中排除(仍可通过 /skill 运行) |
command-dispatch |
— | 设置为 tool 可将斜杠命令直接路由到工具,绕过模型 |
command-tool |
— | 在设置 command-dispatch: tool 时要调用的工具名称 |
command-arg-mode |
raw |
对于工具分发,将原始参数字符串转发给工具 |
homepage |
— | 在 macOS 技能界面中显示为“网站”的 URL |
有关门控字段(requires.bins、requires.env 等),请参阅技能 — 门控。
使用 {baseDir}¶
引用技能目录内的文件而无需硬编码路径——智能体会将 {baseDir} 解析为技能自身目录:
添加条件激活¶
为你的技能设置门控,使其仅在依赖项可用时加载:
---
name: gemini-search
description: 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 |
即使 requires.* 检查失败,在兼容操作系统上也包含 |
完整参考:技能 — 门控。
环境与 API 密钥
在 openclaw.json 中将 API 密钥绑定到技能条目:
{
skills: {
entries: {
"gemini-search": {
enabled: true,
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
},
},
},
}
该密钥仅在该次智能体轮次注入宿主进程,不会到达沙箱——请参阅沙箱环境变量。
习得技能(Skill Workshop)¶
智能体还会通过Skill Workshop编写自己的技能。这些习得技能会立即生效,并保留之前的版本,因此任何更改都可以撤销。你可以从 CLI 检查和管理它们:
openclaw skills workshop list
openclaw skills workshop changes
openclaw skills workshop show hello-world
openclaw skills workshop archive hello-world --reason "Replaced by greeting"
openclaw skills workshop restore hello-world
查看 openclaw skills workshop 了解所有选项。
发布到 ClawHub¶
所有者是 ClawHub 发布者句柄,例如 @alice 或 @your-org。
你的账户拥有一个个人所有者。组织所有者可以拥有具有
owner、admin 或 publisher 角色的成员;这三种角色都可以发布。请选择你的
个人所有者,或选择一个你拥有发布者访问权限的组织。
1. 确保你的 SKILL.md 已完整
确保 name、description 以及任何 metadata.openclaw 门控字段
已设置。如果你有项目页面,请添加 homepage URL。
2. 安装独立的 ClawHub CLI 并登录
3. 发布
添加 --version <version> 或 --owner <owner> 以覆盖推断的
版本,或在特定所有者下发布。请参阅
ClawHub — 发布 和
ClawHub CLI 了解完整流程、所有者作用域以及其他
维护命令(clawhub sync、clawhub skill rename 等)。
最佳实践¶
Tip
- 保持简洁 — 指示模型做什么,而不是如何成为 AI。
- 安全第一 — 如果你的技能使用
exec,请确保提示词不允许 来自不受信任输入的任意命令注入。 - 本地测试 — 在分享之前使用
openclaw agent --message "..."。 - 使用 ClawHub — 在从零开始构建之前,先在 clawhub.ai 上浏览社区技能。
相关¶
加载顺序、门控、允许列表以及 SKILL.md 格式。
你的代理自行保存和更新的技能,支持撤销。
完整的 skills.* 配置模式。
在公共注册表中浏览和发布技能。
插件可以随其文档化的工具一起发布技能。
技能注册的命令如何被调用和门控。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw