OpenClaw Skills 开发学习

📦 Skills 基础

什么是 Skills

Skills 是 OpenClaw 的技能系统，用于教导 Agent 如何使用工具完成任务。

核心特点：

AgentSkills 兼容格式
文件夹结构组织
YAML Frontmatter + Markdown 指令
支持工具调用和脚本执行

Skills 加载优先级

<workspace>/skills/          (最高优先级)
  ↓
<workspace>/.agents/skills/  (项目 Agent 技能)
  ↓
~/.agents/skills/            (个人 Agent 技能)
  ↓
~/.openclaw/skills/          (本地/管理技能)
  ↓
bundled skills               ( bundled 技能)
  ↓
skills.load.extraDirs        (额外共享目录 - 最低优先级)

冲突处理： 同名技能，优先级高的覆盖低的

📁 Skill 结构

基本结构

skill-name/
├── SKILL.md              # 必需：技能定义和指令
├── index.js              # 可选：主逻辑
├── package.json          # 可选：Node.js 依赖
├── requirements.txt      # 可选：Python 依赖
└── README.md             # 可选：说明文档

SKILL.md 格式

---
name: skill_name
description: 技能的单行描述
homepage: https://example.com  # 可选：主页
user-invocable: true          # 可选：是否暴露为斜杠命令
disable-model-invocation: false  # 可选：是否从模型提示排除
---

# 技能名称

这里是技能的详细指令，教导 Agent 如何使用这个技能。

## 使用场景

- 场景 1
- 场景 2

## 工具使用

使用 `exec` 工具运行命令...

🏷️ Frontmatter 字段

必需字段

字段	类型	说明
`name`	string	唯一标识符（snake_case）
`description`	string	单行描述，显示给 Agent

可选字段

字段	类型	说明
`homepage`	string	macOS Skills UI 显示的"网站"链接
`user-invocable`	boolean	是否暴露为用户斜杠命令（默认 true）
`disable-model-invocation`	boolean	是否从模型提示排除（默认 false）
`command-dispatch`	string	设置为 `tool` 时直接分派到工具
`command-tool`	string	配合 `command-dispatch` 使用的工具名
`command-arg-mode`	string	`raw`（默认）或 `parsed`

metadata.openclaw 字段

metadata:
  openclaw:
    emoji: "🔧"                    # macOS Skills UI 使用
    homepage: "https://..."        # 网站链接
    os: ["darwin", "linux"]        # OS 过滤
    always: true                   # 总是包含（跳过其他门控）
    primaryEnv: "API_KEY"          # 主环境变量

    requires:
      bins: ["node", "curl"]       # 必需的 PATH 二进制
      anyBins: ["npm", "pnpm"]     # 至少一个存在
      env: ["API_KEY"]             # 必需的环境变量
      config: ["browser.enabled"]  # 必需的配置项

    install:                       # 安装器配置
      - id: "brew"
        kind: "brew"
        formula: "package-name"
        bins: ["binary-name"]
        label: "Install via brew"

🚪 门控机制（Load-time Filters）

门控类型

OpenClaw 在加载时过滤 Skills：

metadata:
  openclaw:
    requires:
      bins: ["uv"]                    # 必需的二进制
      env: ["GEMINI_API_KEY"]         # 必需的环境变量
      config: ["browser.enabled"]     # 必需的配置项

门控逻辑

always: true - 跳过所有门控，始终包含
os 过滤 - 仅指定平台可用
bins 检查 - 所有必需二进制必须在 PATH 中
env 检查 - 环境变量必须存在或在配置中提供
config 检查 - 配置项必须为 truthy

沙箱注意事项

requires.bins 在主机上检查
如果 Agent 沙箱化，二进制也必须在容器内存在
通过 agents.defaults.sandbox.docker.setupCommand 安装

🛠️ 创建第一个 Skill

步骤 1：创建目录

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

步骤 2：编写 SKILL.md

---
name: hello_world
description: 一个简单的问候技能
---

# Hello World 技能

当用户请求问候时，使用 `message` 工具发送：
"Hello from your custom skill!"

## 使用场景

- 用户说"打招呼"
- 用户说"hello"
- 用户测试技能

## 示例

用户：打个招呼
助手：Hello from your custom skill!

步骤 3：加载技能

# 重启 Gateway 或开启新会话
openclaw gateway restart

# 或
/new

# 验证技能已加载
openclaw skills list

步骤 4：测试技能

# 通过 CLI 测试
openclaw agent --message "打个招呼"

# 或直接聊天
# 发送："打个招呼"

🔧 高级 Skills 开发

1. 使用工具的 Skills

---
name: weather_check
description: 查询天气信息
metadata:
  openclaw:
    requires:
      bins: ["curl"]
      env: ["WEATHER_API_KEY"]
---

# 天气查询技能

使用 `exec` 工具调用天气 API：

```bash
curl "https://api.weather.com/v1/current?city={city}&key=${WEATHER_API_KEY}"

指令

提取用户消息中的城市名
使用 exec 工具运行 curl 命令
解析 JSON 响应
格式化并返回天气信息

### 2. 带安装器的 Skills

```markdown
---
name: gemini_cli
description: 使用 Gemini CLI 进行编程协助
metadata:
  openclaw:
    emoji: "♊️"
    requires:
      bins: ["gemini"]
    install:
      - id: "brew"
        kind: "brew"
        formula: "gemini-cli"
        bins: ["gemini"]
        label: "Install Gemini CLI (brew)"
      - id: "npm"
        kind: "npm"
        package: "gemini-cli"
        bins: ["gemini"]
        label: "Install Gemini CLI (npm)"
---

# Gemini CLI 技能

使用 `gemini` 命令进行编程协助...

3. 多步骤工作流 Skills

---
name: code_review
description: 代码审查工作流
metadata:
  openclaw:
    requires:
      bins: ["git", "node"]
---

# 代码审查技能

## 工作流程

1. 使用 `read` 工具读取代码文件
2. 分析代码质量和最佳实践
3. 使用 `exec` 运行 linting 工具
4. 生成审查报告
5. 提供改进建议

## 审查要点

- 代码风格一致性
- 潜在的错误和边界情况
- 性能优化机会
- 安全性考虑
- 测试覆盖率

4. 使用自定义工具的 Skills

---
name: image_processor
description: 图像处理技能
metadata:
  openclaw:
    requires:
      bins: ["python3"]
---

# 图像处理技能

使用自定义 Python 脚本处理图像：

```python
# {baseDir}/process.py
from PIL import Image
import sys

def process_image(input_path, output_path):
    img = Image.open(input_path)
    # 处理逻辑
    img.save(output_path)

if __name__ == "__main__":
    process_image(sys.argv[1], sys.argv[2])

指令

接收用户提供的图像路径
使用 exec 运行 Python 脚本
返回处理后的图像

---

## 📊 Skills 配置

### openclaw.json 配置

```json5
{
  skills: {
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { 
          source: "env", 
          provider: "default", 
          id: "GEMINI_API_KEY" 
        },
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
    allowBundled: ["weather", "search"],  // 仅允许这些 bundled skills
  },
}

配置字段说明

字段	类型	说明
`enabled`	boolean	禁用技能（即使已安装）
`env`	object	注入环境变量（仅当未设置时）
`apiKey`	string/object	API Key（明文或 SecretRef）
`config`	object	自定义配置字段

环境变量注入

注入时机： Agent 运行时开始时

作用范围： 仅限该 Agent run，非全局 shell 环境

恢复： run 结束后恢复原始环境

🔄 Skills 热重载

自动刷新

{
  skills: {
    load: {
      watch: true,           // 启用监视
      watchDebounceMs: 250,  // 防抖时间
    },
  },
}

会话快照

Skills 在会话开始时快照
更改在下次新会话生效
启用 watcher 后可热重载

💰 Token 成本

计算公式

total = 195 + Σ (97 + len(name) + len(description) + len(location))

说明：

基础开销： 195 字符（当有≥1 个 skill 时）
每个 skill： 97 字符 + XML 转义后的字段长度
估算： ~4 字符/token，97 字符 ≈ 24 tokens/skill

优化建议

保持描述简洁（<50 字符）
使用短 skill 名
禁用不常用的 skills
定期清理无用 skills

🛡️ 安全最佳实践

1. 审查第三方 Skills

# 查看 skill 内容
openclaw skills show <skill-name>

# 检查 SKILL.md
cat ~/.openclaw/skills/<skill-name>/SKILL.md

2. 使用沙箱

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // 非主会话使用沙箱
      },
    },
  },
}

3. 保护 Secrets

{
  skills: {
    entries: {
      "my-skill": {
        // 使用 SecretRef 而非明文
        apiKey: {
          source: "env",
          provider: "default",
          id: "MY_API_KEY"
        }
      }
    }
  }
}

4. 限制危险工具

{
  tools: {
    exec: {
      policy: "elevated"  // 需要审批
    }
  }
}

📦 ClawHub 技能市场

浏览和安装

# 搜索技能
openclaw skills search weather

# 安装技能
openclaw skills install <skill-slug>

# 更新所有技能
openclaw skills update --all

发布技能

使用 clawhub CLI：

# 同步（扫描 + 发布更新）
clawhub sync --all

# 发布新技能
clawhub publish ./my-skill

💡 最佳实践

1. Skill 设计原则

单一职责： 一个 skill 做一件事
简洁指令： 告诉模型"做什么"，而非"如何做"
安全第一： 避免任意命令注入
本地测试： 使用 openclaw agent 测试

2. 目录组织

skills/
├── utility/           # 工具类
│   ├── file_search/
│   └── web_scrape/
├── automation/        # 自动化
│   ├── daily_report/
│   └── backup/
└── integration/       # 集成
    ├── tushare/
    └── classcms/

3. 版本控制

# 为 skills 目录创建 git 仓库
cd ~/.openclaw/workspace/skills
git init
git add .
git commit -m "Initial skills"

4. 文档化

每个 skill 包含 README.md：

# Skill 名称

## 功能描述

## 使用示例

## 配置要求

## 故障排查

🔍 故障排查

Skill 未加载

# 检查技能列表
openclaw skills list

# 查看技能详情
openclaw skills show <skill-name>

# 检查门控条件
# 验证 bins/env/config 是否满足

Skill 执行失败

# 查看日志
openclaw logs --tail 100

# 检查工具权限
openclaw config.get tools

# 测试执行
openclaw agent --message "测试技能"

📚 参考资料

Skills 参考：https://docs.openclaw.ai/tools/skills.md
创建 Skills：https://docs.openclaw.ai/tools/creating-skills.md
ClawHub：https://clawhub.ai
AgentSkills 规范：https://agentskills.io

BeiLa