# 创建技能

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

- 网址：https://funcoding.ai/agents/openclaw/tools/creating-skills/
- 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/tools/creating-skills

---
Skills 会教智能体如何以及何时使用工具。每个技能都是一个目录，
其中包含带有 YAML frontmatter 和 Markdown 指令的 `SKILL.md` 文件。
OpenClaw 按定义的[优先级顺序](https://funcoding.ai/agents/openclaw/tools/skills/#loading-order)从多个根目录加载技能。

## 创建你的第一个技能

**创建技能目录**

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

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

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

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

**编写 SKILL.md**

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

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

  # Hello World

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

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

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

</Step>

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

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

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

  # 或重启 Gateway 网关
  openclaw gateway restart
  ```

**测试**

```bash
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 — 门控](https://funcoding.ai/agents/openclaw/tools/skills/#gating)。

### 使用 `{baseDir}`

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

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

## 添加条件激活

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

```markdown
---
name: gemini-search
description: 使用 Gemini CLI 进行搜索。
metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } }
---
```

<details>
<summary>门控选项</summary>

| 键 | 描述 |
| --- | --- |
| `requires.bins` | 所有二进制文件都必须存在于 `PATH` 中 |
| `requires.anyBins` | 至少一个二进制文件必须存在于 `PATH` 中 |
| `requires.env` | 每个环境变量都必须存在于进程或配置中 |
| `requires.config` | 每个 `openclaw.json` 路径的值都必须为真 |
| `os` | 平台筛选器：`["darwin"]`、`["linux"]`、`["win32"]` |
| `always` | 设置 `true` 可跳过所有门控并始终包含该技能 |

完整参考：[Skills — 门控](https://funcoding.ai/agents/openclaw/tools/skills/#gating)。

</details>

<details>
<summary>环境和 API 密钥</summary>

在 `openclaw.json` 中将 API 密钥关联到技能条目：

```json5
{
  skills: {
    entries: {
      "gemini-search": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
      },
    },
  },
}
```

该密钥只会在对应的智能体轮次中注入宿主进程。
它不会进入沙箱——请参阅
[沙箱隔离的环境变量](https://funcoding.ai/agents/openclaw/tools/skills-config/#sandboxed-skills-and-env-vars)。

</details>

## 通过 Skill Workshop 提议

对于由智能体起草的技能，或者希望技能上线前由操作员审查的情况，
请使用 [Skill Workshop](https://funcoding.ai/agents/openclaw/tools/skill-workshop/) 提案，而不是直接编写
`SKILL.md`。

```bash
# 提议创建全新技能
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`：

```bash
openclaw skills workshop propose-create \
  --name "hello-world" \
  --description "一个输出问候语的简单技能。" \
  --proposal-dir ./hello-world-proposal/
```

该目录的根目录必须包含 `PROPOSAL.md`。支持文件应放在
`assets/`、`examples/`、`references/`、`scripts/` 或 `templates/` 下。

审查后：

```bash
openclaw skills workshop inspect <proposal-id>
openclaw skills workshop apply <proposal-id>
```

完整提案生命周期请参阅 [Skill Workshop](https://funcoding.ai/agents/openclaw/tools/skill-workshop/)。

## 发布到 ClawHub

**确保 SKILL.md 完整**

确保已设置 `name`、`description` 以及所有 `metadata.openclaw` 门控字段。
如果你有项目页面，请添加 `homepage` URL。

**安装独立的 ClawHub CLI 并登录**

```bash
npm i -g clawhub
clawhub login
```

**发布**

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

添加 `--version <version>` 或 `--owner <owner>` 可覆盖推断出的
版本，或以特定所有者的名义发布。有关完整流程、所有者范围和其他
维护命令（`clawhub sync`、`clawhub skill rename` 等），请参阅
[ClawHub — 发布](https://docs.openclaw.ai/zh-CN/clawhub/publishing)和
[ClawHub CLI](https://docs.openclaw.ai/zh-CN/clawhub/cli)。

## 最佳实践

<div class="callout callout-tip">

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

</div>

## 相关内容

- [Skills 参考](https://funcoding.ai/agents/openclaw/tools/skills/)：加载顺序、门控、允许列表和 SKILL.md 格式。
- [Skill Workshop](https://funcoding.ai/agents/openclaw/tools/skill-workshop/)：用于智能体起草技能的提案队列。
- [Skills 配置](https://funcoding.ai/agents/openclaw/tools/skills-config/)：完整的 `skills.*` 配置模式。
- [ClawHub](https://docs.openclaw.ai/clawhub)：在公共注册表中浏览和发布技能。
- [构建插件](https://funcoding.ai/agents/openclaw/plugins/building-plugins/)：插件可以将 Skills 与其所记录的工具一起发布。