创建技能

为你的 OpenClaw 智能体构建、测试并发布自定义的工作区 SKILL.md Skills。

Skills 会教智能体如何以及何时使用工具。每个技能都是一个目录，其中包含带有 YAML frontmatter 和 Markdown 指令的 SKILL.md 文件。 OpenClaw 按定义的优先级顺序从多个根目录加载技能。

创建你的第一个技能

创建技能目录

Skills 位于工作区的 skills/ 文件夹中：

mkdir -p ~/.openclaw/workspace/skills/hello-world

你可以将技能分组到子文件夹中以便整理，但技能仍由 SKILL.md frontmatter 命名，而不是由文件夹路径命名：

mkdir -p ~/.openclaw/workspace/skills/personal/hello-world
# 技能名称仍为 "hello-world"，通过 /hello-world 调用

编写 SKILL.md

frontmatter 定义元数据；正文为智能体提供指令。

---
name: hello-world
description: 一个输出问候语的简单技能。
---

# Hello World

当用户请求问候语时，使用 `exec` 工具运行：

```bash
echo "来自你的自定义技能的问候！"


命名规则：
- `name` 使用小写字母、数字和连字符。
- 保持目录名称与 frontmatter 中的 `name` 一致。
- `description` 会显示给智能体，并出现在斜杠命令发现结果中——
  请保持为一行且少于 160 个字符。

</Step>

<Step title="验证技能已加载">
```bash
openclaw skills list

默认情况下，OpenClaw 会监视技能根目录下的 SKILL.md 文件。如果监视器已禁用，或者你要继续现有会话，请启动新会话，以便智能体接收刷新后的列表：

# 在聊天中——归档当前会话并重新开始
/new

# 或重启 Gateway 网关
openclaw gateway restart

测试

openclaw agent --message "给我一句问候语"

或者打开聊天，直接向智能体提出请求。使用 /skill hello-world 按名称显式调用它。

SKILL.md 参考

必填字段

字段	描述
`name`	使用小写字母、数字和连字符的唯一 slug
`description`	显示给智能体并出现在发现输出中的单行描述

可选 frontmatter 键

字段	默认值	描述
`user-invocable`	`true`	将技能公开为用户斜杠命令
`disable-model-invocation`	`false`	不在智能体的系统提示词中包含该技能（仍可通过 `/skill` 运行）
`command-dispatch`	—	设为 `tool`，将斜杠命令直接路由到工具，绕过模型
`command-tool`	—	设置 `command-dispatch: tool` 时要调用的工具名称
`command-arg-mode`	`raw`	对于工具分派，将原始参数字符串转发给工具
`homepage`	—	在 macOS Skills UI 中显示为“Website”的 URL

有关门控字段（requires.bins、requires.env 等），请参阅 Skills — 门控。

使用 `{baseDir}`

引用技能目录中的文件而无需硬编码路径—— 智能体会基于技能自身的目录解析 {baseDir}：

运行位于 `{baseDir}/scripts/run.sh` 的辅助脚本。

添加条件激活

为技能设置门控，使其仅在依赖项可用时加载：

---
name: gemini-search
description: 使用 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 "一个输出问候语的简单技能。" \
  --proposal ./PROPOSAL.md

# 提议更新现有技能
openclaw skills workshop propose-update hello-world \
  --proposal ./PROPOSAL.md \
  --description "更新后的问候技能"

当提案包含支持文件时，使用 --proposal-dir：

openclaw skills workshop propose-create \
  --name "hello-world" \
  --description "一个输出问候语的简单技能。" \
  --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 clawhub
clawhub login

发布

clawhub skill publish ./path/to/hello-world

添加 --version <version> 或 --owner <owner> 可覆盖推断出的版本，或以特定所有者的名义发布。有关完整流程、所有者范围和其他维护命令（clawhub sync、clawhub skill rename 等），请参阅 ClawHub — 发布和 ClawHub CLI。

最佳实践

保持简洁——告诉模型要做什么，而不是如何成为 AI。
安全第一——如果你的技能使用 exec，请确保提示词不会允许不受信任的输入进行任意命令注入。
在本地测试——分享前使用 openclaw agent --message "..."。
使用 ClawHub——从头构建之前，先在 clawhub.ai 浏览社区技能。