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

​
创建你的第一个技能

1

创建技能目录

技能位于你工作区的 skills/ 文件夹中。为你的新技能创建一个目录：
mkdir -p ~/.openclaw/workspace/skills/hello-world
你可以为了组织管理把技能分到子文件夹中——技能仍然由 SKILL.md frontmatter 中的内容命名，而不是由文件夹路径命名：
mkdir -p ~/.openclaw/workspace/skills/personal/hello-world
# 技能名称仍然是 "hello-world"，调用方式为 /hello-world
2

编写 SKILL.md

在目录中创建 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
3

测试它

发送一条应该触发该技能的消息：
openclaw agent --message "给我一个问候"
或者打开聊天并直接向 agent 提问。使用 /skill hello-world 可以按名称显式调用它。

​
SKILL.md 参考

​
必需字段

字段描述
name使用小写字母、数字和连字符的唯一 slug
description显示给 agent 和发现输出的一行描述

​
可选 frontmatter 键

字段默认值描述
user-invocabletrue将该技能暴露为用户斜杠命令
disable-model-invocationfalse将该技能排除在 agent 的系统提示之外（仍可通过 /skill 运行）
command-dispatch—设置为 tool 可将斜杠命令直接路由到工具，绕过模型
command-tool—当设置了 command-dispatch: tool 时要调用的工具名称
command-arg-moderaw对于工具分发，将原始参数字符串转发给工具
homepage—在 macOS Skills UI 中显示为“网站”的 URL
关于门控字段（requires.bins、requires.env 等），请参见 Skills — 门控。

​
使用 {baseDir}

在技能正文中使用 {baseDir} 来引用技能目录中的文件，而不必硬编码路径： 
在 `{baseDir}/scripts/run.sh` 运行 helper 脚本。

​
添加条件激活

对你的技能进行门控，使其只在依赖可用时加载： 
---
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 — 门控。
在 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 apply <proposal-id>
完整提案流程请参见 Skill Workshop。

​
发布到 ClawHub

1

确保你的 SKILL.md 完整

确保已设置 name、description 以及任何 metadata.openclaw 门控字段。如果你有项目页面，也可以添加 homepage URL。
2

安装 ClawHub skill

ClawHub skill 会记录当前发布命令的格式和所需元数据：
openclaw skills install clawhub-publish
3

发布

clawhub publish
完整流程请参见 ClawHub — Publishing。

​
最佳实践

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

​
相关内容

Skills reference

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

Skill Workshop

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

Skills config

完整的 skills.* 配置 schema。

ClawHub

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

Building plugins

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