## 摘要

Skills 是 OpenClaw 扩展 Agent 能力的核心机制：一份声明式的 SKILL.md 就能让 Agent 学会一套新操作。但当技能需要依赖外部 CLI、环境变量、配置项，或包含几十行逻辑时，单文件就不够用了。本文从 SKILL.md 的 frontmatter 字段、指令编写原则、门控过滤机制入手，讲清 metadata.openclaw 的 requires 三要素（bins/env/config）与安装器（brew/node/go/download）的配置方式，再给出多文件技能架构、环境变量注入规则、测试与错误处理的最佳实践。读完本文，你能从"写一个能跑的小技能"升级到"构建可维护、可分发的生产级技能"。

> 📌 版本声明：本文基于 OpenClaw 最新稳定版与 AgentSkills 兼容规范编写。文中的 frontmatter 字段、安装器类型、门控语义以当前官方文档为准，不同版本可能有增删。

@[toc]

## 一、为什么需要"高级"的 Skills 开发

### 1.1 简单技能的边界

一个最小技能往往只是一段 Markdown 指令：告诉 Agent"当用户问天气时，调用 weather-api 并返回结果"。它能跑，但无法覆盖下面这些现实需求：

- **外部依赖**：技能需要 ffmpeg、gemini CLI、某个 API Key，环境不满足时应该静默跳过而不是报错。
- **多步骤逻辑**：一个技能要加载配置、调用 API、套模板生成报告，逻辑超过一个提示词能承载的范围。
- **可维护性**：团队协作、版本管理、单元测试，这些都需要技能有清晰的结构。
- **可分发性**：技能要能在 ClawHub 上共享，遵循统一规范，让其他 Agent 也能复用。

### 1.2 Skills 的核心价值：能力定义与能力实现分离

Skills 的设计哲学是把"Agent 该做什么"和"具体怎么做"分开。SKILL.md 是"说明书"，Agent 通过阅读说明书掌握工具用法。这带来三个好处：技能可独立开发、测试、分发、更新；不同 Agent 平台只要兼容 AgentSkills 规范就能复用；用户像学新技能一样，用自然语言描述就能扩展 Agent 能力。

```mermaid
flowchart LR
    A[Skills 系统] --> B[标准化接口]
    A --> C[可移植性]
    A --> D[生态共享]
    B --> B1[SKILL.md 规范]
    B --> B2[YAML Frontmatter]
    C --> C1[跨平台兼容]
    C --> C2[版本管理]
    D --> D1[ClawHub 市场]
    D --> D2[社区贡献]
    style A fill:#e8f5e9
    style B fill:#e1f5fe
    style D fill:#fff3e0
```

## 二、SKILL.md 深度解析

### 2.1 完整结构

一个 SKILL.md 由 YAML frontmatter 和 Markdown 正文组成。frontmatter 描述元信息，正文是给 Agent 的操作手册：

```markdown
---
name: my-skill
description: 一句话描述技能功能
homepage: https://example.com
user-invocable: true
disable-model-invocation: false
metadata:
  {
    "openclaw": {
      "requires": { "bins": ["required-cli"], "env": ["API_KEY"] },
      "primaryEnv": "API_KEY"
    }
  }
---

# 技能标题

详细的使用说明...
```

### 2.2 Frontmatter 字段

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `name` | string | 必填 | 技能唯一标识，建议 kebab-case |
| `description` | string | 必填 | 功能描述，用于匹配和展示 |
| `homepage` | string | 可选 | 技能主页，UI 中展示 |
| `user-invocable` | boolean | true | 是否作为用户斜杠命令暴露 |
| `disable-model-invocation` | boolean | false | 是否从模型提示词排除 |
| `metadata` | object | 可选 | OpenClaw 特定配置，必须是单行 JSON |

`metadata.openclaw` 是最需要理解的部分，它承载了门控条件、环境配置、安装器和 UI 信息。其中 `requires` 是门控的三要素。

### 2.3 指令编写三原则

正文是给 Agent 的"操作手册"。写得好的指令有三个特征：**触发条件明确、操作步骤具体、变量引用正确**。

```markdown
# 天气查询技能

当用户询问以下内容时激活：
- 当前天气情况
- 未来几天的天气预报
- 特定城市的气温、降水

不要在以下情况使用：
- 历史天气数据
- 极端天气预警（请使用 weather-alert 技能）

## 使用步骤
1. 确认用户询问的城市名称，不明确时主动询问
2. 调用 weather-api 工具获取数据
3. 将数据格式化为用户友好的文本输出
4. API 失败时改用备用方案 wttr.in
```

这段指令把"什么时候用、什么时候不用、具体怎么做、失败怎么办"都写清楚了，Agent 不需要猜测。

![1793260809825.jpg#center](https://developer.qcloudimg.com/http-save/yehe-11154201/6b22141590c15a051dcac2dff9ffd353.png)
> 🖼️ **图1：SKILL.md 结构分解图** —— 展示 frontmatter 元信息与正文指令的分层结构。

### 2.4 变量占位符 {baseDir}

技能目录里的资源文件通过 `{baseDir}` 引用，Agent 运行时会替换为技能实际路径。这是多文件技能的基础：

```markdown
此技能依赖：
- 配置模板：{baseDir}/templates/config.yaml
- 示例数据：{baseDir}/examples/sample.json
```

## 三、门控过滤与外部依赖

### 3.1 requires 三要素

`metadata.openclaw.requires` 声明技能的前置条件，只有全部满足时技能才会被加载：

```markdown
---
metadata:
  {
    "openclaw": {
      "requires": {
        "bins": ["ffmpeg", "ffprobe"],
        "env": ["OPENAI_API_KEY"],
        "config": ["browser.enabled"]
      }
    }
  }
---
```

- **bins**：指定二进制工具，加载时检查是否在 PATH 中，缺失则技能被过滤。
- **env**：指定环境变量，缺失时若配置文件提供了值则注入，否则过滤。
- **config**：指定配置项，要求配置为真值。

### 3.2 加载过滤流程

```mermaid
flowchart TD
    A[技能加载] --> B{enabled 未关闭?}
    B -->|否| C[跳过]
    B -->|是| D{bins 检查}
    D -->|缺失| C
    D -->|存在| E{env 检查}
    E -->|缺失且无配置| C
    E -->|有值或存在| F{config 检查}
    F -->|为真| G[加入技能快照]
    F -->|为假| C
    style G fill:#e8f5e9
    style C fill:#fce4ec
```

这个流程保证：环境不满足的技能**不会加载、不会报错、也不会进入提示词**。这正是"优雅降级"——缺 ffmpeg 的机器上，视频处理技能默默消失，而不是每次调用都失败。

![1793262063529.jpg#center](https://developer.qcloudimg.com/http-save/yehe-11154201/92985f1b5558fbe25be67391db0e0f1d.png)
> 🖼️ **图2：门控过滤决策树** —— 展示 bins/env/config 三重门控的通过与过滤路径。

### 3.3 安装器：自动补齐依赖

对需要外部工具的技能，可以配置自动安装器，让"缺依赖"变成"自动装"：

```markdown
---
name: gemini
metadata:
  {
    "openclaw": {
      "requires": { "bins": ["gemini"] },
      "install": [
        { "id": "brew", "kind": "brew", "formula": "gemini-cli", "bins": ["gemini"] },
        { "id": "npm", "kind": "node", "package": "@google/gemini-cli", "bins": ["gemini"] }
      ]
    }
  }
---
```

| 安装器类型 | 必填字段 | 说明 |
|-----------|----------|------|
| `brew` | `formula` | Homebrew 包 |
| `node` | `package` | npm/pnpm/yarn/bun 包 |
| `go` | `package` | Go 模块 |
| `download` | `url` | 直接下载归档 |

## 四、多文件技能架构

### 4.1 为什么单文件不够用

技能逻辑复杂后，把所有东西塞进 SKILL.md 会导致指令冗长、模板和代码难以维护。多文件架构把技能拆成可独立演进的模块：

```
my-complex-skill/
├── SKILL.md              # 主入口
├── lib/
│   ├── helpers.py
│   ├── api_client.py
│   └── validators.py
├── templates/
│   ├── report.md
│   └── email.html
├── config/
│   └── defaults.yaml
└── tests/
    └── test_helpers.py
```
![1793262906029.jpg#center](https://developer.qcloudimg.com/http-save/yehe-11154201/64daa22f29be9a8fd176efdb2bcf4d5e.png)
> 🖼️ **图3：多文件技能目录树** —— 展示复杂技能的模块划分与依赖关系。

### 4.2 在 SKILL.md 中引用

SKILL.md 负责编排，具体实现交给 lib 里的脚本，输出格式交给 templates：

```markdown
## 执行流程
1. 加载配置：`python3 {baseDir}/lib/helpers.py --config {baseDir}/config/defaults.yaml`
2. 调用 API：`python3 {baseDir}/lib/api_client.py --key $API_KEY`
3. 生成报告：使用 `{baseDir}/templates/report.md` 模板
```

## 五、配置注入与环境变量

### 5.1 skills 配置结构

所有 Skills 配置在 `~/.openclaw/openclaw.json` 的 `skills` 键下：

```json5
{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/my-skills"],
      watch: true,
      watchDebounceMs: 250
    },
    install: { preferBrew: true, nodeManager: "npm" },
    entries: {
      "my-api-skill": {
        enabled: true,
        apiKey: "sk-xxxxx",
        env: { MY_API_KEY: "sk-xxxxx", DEBUG: "true" },
        config: { endpoint: "https://example.com/api", timeout: 30000 }
      }
    }
  }
}
```

### 5.2 环境变量注入的"非覆盖"原则

注入环境变量时，OpenClaw 只在变量未设置时才写入，不会覆盖已有的环境变量；且注入作用域限定在 Agent 运行期间，敏感信息不会泄漏到提示词或日志。核心逻辑如下：

```python
def inject_skill_environment(skill_name, config):
    skill_config = config.skills.entries.get(skill_name, {})
    # 1. 注入 env 字段中的变量（不覆盖已存在值）
    for key, value in skill_config.get('env', {}).items():
        if key not in os.environ:
            os.environ[key] = value
    # 2. primaryEnv 对应 apiKey
    primary_env = skill_metadata.get('primaryEnv')
    if primary_env and primary_env not in os.environ:
        os.environ[primary_env] = skill_config.get('apiKey', '')
```

### 5.3 沙箱中的特殊处理

沙箱容器**不会继承宿主机的环境变量**，必须通过 `docker.env` 显式注入，或使用自定义镜像。这是沙箱配置中最容易被忽略的点：本地能跑的技能，放进沙箱后因为环境变量缺失而被门控过滤掉，表现为"技能突然不可用"。

![4b9a880c-5f7c-4b7f-83b2-95336223848a.png#center](https://developer.qcloudimg.com/http-save/yehe-11154201/8980b29a0b900bac71521f7329e43509.png)
> 🖼️ **图4：环境变量注入时序图** —— 展示非覆盖原则与沙箱环境变量的传递差异。

## 六、调试、测试与错误处理

### 6.1 调试工具

```bash
# 详细日志启动网关
openclaw gateway start --verbose

# 直接测试某个技能
openclaw agent --message "测试我的技能" --skill my-skill

# 查看技能加载状态（是否通过门控）
openclaw skills list
```

### 6.2 技能测试

为技能写测试是质量保障的关键。一个推荐的结构是：校验 SKILL.md 存在、frontmatter 合法、依赖齐全、脚本可执行：

```python
def test_skill_md_frontmatter():
    content = skill_md.read_text()
    assert content.startswith("---"), "缺少 YAML frontmatter"
    frontmatter = yaml.safe_load(content.split("---", 2)[1])
    assert "name" in frontmatter
    assert "description" in frontmatter

def test_skill_dependencies():
    for bin_name in ["python3", "curl"]:
        result = subprocess.run(["which", bin_name], capture_output=True)
        assert result.returncode == 0, f"缺少依赖: {bin_name}"
```

### 6.3 错误处理与恢复

在 SKILL.md 里定义清晰的错误恢复策略，比让 Agent 现场发挥更可靠：

```markdown
## 错误处理
1. API 密钥无效（Authentication failed）→ 提示用户检查配置
2. 网络超时（Connection timeout）→ 自动重试 3 次，间隔 2 秒
3. 资源不存在（Resource not found）→ 提供相似资源列表
```

恢复流程用时序图表达更直观：

```mermaid
sequenceDiagram
    participant A as Agent
    participant S as Skill
    participant API as 外部服务
    A->>S: 调用技能
    S->>API: 发送请求
    alt 成功
        API-->>S: 返回数据
        S-->>A: 正常结果
    else 失败
        API-->>S: 错误响应
        S->>S: 判断错误类型
        alt 可重试
            S->>API: 重试请求
        else 需人工
            S-->>A: 返回错误信息
        end
    end
```

## 七、适用边界与风险提示

### 7.1 不适用场景

- **一次性、纯提示词的小任务**：为了一个简单操作建一套多文件技能是过度设计，直接在对话里说明即可。
- **强依赖宿主机环境的开发场景**：沙箱容器不继承宿主机环境变量，如果技能强依赖本地二进制或环境，放进沙箱前要先解决注入问题。
- **涉及敏感凭证的第三方工具**：安装器会自动执行包管理器命令，供应链风险需要自行评估，优先用官方源。

### 7.2 需要注意的点

- 不要把真实 API Key 写进 SKILL.md 正文或测试样例，用占位符并标注"替换为实际值"。
- 不要宣称技能"绝对安全"。门控过滤是降低误用概率，不替代人工审查。
- 自定义正则脱敏和安装器要经过充分测试，避免误删合法内容或安装恶意包。

### 7.3 版本与时效

frontmatter 字段、安装器类型、门控语义随版本演进。开发时对照当前官方文档核对，发布到 ClawHub 前确认兼容性。

## 八、总结

OpenClaw Skills 把"能力定义"和"能力实现"分离，让 Agent 通过阅读 SKILL.md 学会新操作。本文从 SKILL.md 的 frontmatter 和指令三原则出发，讲清了门控过滤（bins/env/config）、安装器、多文件架构、环境变量注入（非覆盖原则）和测试调试。

核心结论是：**小技能靠清晰的指令，生产级技能靠结构化的门控与多文件组织**。写 SKILL.md 时始终回答三个问题——什么时候用、具体怎么做、失败了怎么办；引入外部依赖时用 requires 门控做优雅降级；逻辑复杂后拆分为 lib/templates/config 多文件结构，并配上测试和结构化日志。

从"能跑的小技能"到"可维护的技能系统"，关键不在于代码量，而在于把触发条件、依赖声明、错误恢复这些"非功能"因素提前设计好。这也是 Skills 生态能持续生长、被不同 Agent 平台复用的基础。

## 参考资料

1. OpenClaw Skills 官方文档：https://docs.openclaw.ai/zh-CN/tools/skills
2. 创建自定义 Skills：https://docs.openclaw.ai/zh-CN/tools/creating-skills
3. Skills 配置参考：https://docs.openclaw.ai/zh-CN/tools/skills-config
4. AgentSkills 规范：https://agentskills.io
5. ClawHub 技能市场：https://clawhub.com



Skills 是 OpenClaw 扩展 Agent 能力的核心机制：一份声明式的 SKILL.md 就能让 Agent 学会一套新操作。但当技能需要依赖外部 CLI、环境变量、配置项，或包含几十行逻辑时，单文件就不够用了。本文从 SKILL.md 的 frontmatter 字段、指令编写原则、门控过滤机制入手，讲清 metadata.openclaw 的 requires 三要素（bins/env/config）与安装器（brew/node/go/download）的配置方式，再给出多文件技能架构、环境变量注入规则、测试与错误处理的最佳实践。读完本文，你能从"写一个能跑的小技能"升级到"构建可维护、可分发的生产级技能"。

OpenClaw Skills 高级开发实战：从 SKILL.md 到多文件技能系统

Skills 是 OpenClaw 扩展 Agent 能力的核心机制：一份声明式的 SKILL.md 就能让 Agent 学会一套新操作。但当技能需要依赖外部 CLI、环境变量、配置项，或包含几十行逻辑时，单文件就不够用了。本文从 SKILL.md 的 frontmatter 字段、指令编写原则、门控过滤机制入手，讲清 metadata.openclaw 的 requires 三要素（bins/e

项目经理

人工智能

开发工具

架构设计

OpenClaw Skills生产级开发指南：详解SKILL.md的frontmatter字段、指令编写三原则与门控过滤机制，覆盖requires三要素（bins/env/config）及安装器配置。文章深入多文件技能架构、环境变量非覆盖注入原则、测试调试最佳实践，助你从基础技能升级到可维护、可分发的生产级技能，实现能力定义与实现的优雅分离。

单元测试

代码解释

包管理器

OpenClaw

Markdown

Docker

容器

Agent

Solid

JSON

pnpm

Yarn

让每一个 Agent，都跑在云上

媒体处理 MPS 普通转码包1元起


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

OpenClaw Skills生产级开发指南：详解SKILL.md的frontmatter字段、指令编写三原则与门控过滤机制，覆盖requires三要素（bins/env/config）及安装器配置。文章深入多文件技能架构、环境变量非覆盖注入原则、测试调试最佳实践，助你从基础技能升级到可维护、可分发的生产级技能，实现能...

OpenClaw Skills 高级开发实战：从 SKILL.md 到多文件技能系统-腾讯云开发者社区-腾讯云

OpenClaw Skills 高级开发实战：从 SKILL.md 到多文件技能系统

OpenClaw Skills 高级开发实战：从 SKILL.md 到多文件技能系统

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐