创建技能

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

创建你的第一个技能

创建技能目录

技能位于你的工作区 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 定义元数据；正文为 agent 提供指令。

---
name: hello-world
description: 一个会打印问候语的简单技能。
---

# Hello World

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

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

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

</Step>

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

默认情况下，OpenClaw 会监视 skills 根目录下的 SKILL.md 文件。如果监视器被禁用，或者你正在继续一个已有会话，请新建一个会话，以便 agent 接收到刷新后的列表：

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

# 或重启网关
openclaw gateway restart

测试它

openclaw agent --message "给我一个问候"

或者打开聊天并直接向 agent 提问。使用 /skill hello-world 可以按名称显式调用它。

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 技能 UI 中显示为“网站”的 URL

关于门控字段（requires.bins、requires.env 等），请参见技能 — 门控。

使用 `{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" },
      },
    },
  },
}

该密钥只会在该 agent 回合期间注入到宿主进程中。它不会进入沙箱——参见沙箱化环境变量。

通过 Skill Workshop 提议

对于由 agent 起草的技能，或者当你希望在技能上线前进行运营审核时，请使用 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 evaluate <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 — 发布和 ClawHub CLI 以了解完整流程、所有者作用域以及其他维护命令（clawhub sync、clawhub skill rename、…）。

最佳实践

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

技能参考

加载顺序、门控、允许列表和 SKILL.md 格式。

技能工作坊

供智能体起草技能使用的提案队列。

技能配置

完整的 skills.* 配置模式。

ClawHub

浏览并在公共注册表中发布技能。

构建插件

插件可以将技能与它们所文档化的工具一起发布。

概览

插件

插件指南

构建插件

技能

自动化

工具

智能体协作

创建你的第一个技能

SKILL.md 参考

必需字段

可选前置元数据键

使用 `{baseDir}`

添加条件激活

通过 Skill Workshop 提议

发布到 ClawHub

最佳实践

相关内容

技能参考

技能工作坊

技能配置

ClawHub

构建插件

​创建你的第一个技能

​SKILL.md 参考

​必需字段

​可选前置元数据键

​使用 {baseDir}

​添加条件激活

​通过 Skill Workshop 提议

​发布到 ClawHub

​最佳实践

​相关内容

技能参考

技能工作坊

技能配置

ClawHub

构建插件

创建你的第一个技能

SKILL.md 参考

必需字段

可选前置元数据键

使用 `{baseDir}`

添加条件激活

通过 Skill Workshop 提议

发布到 ClawHub

最佳实践

相关内容