04 OpenClaw Skill 与 Tool——AgentSkills 兼容格式

原文：Skills

Skill 格式：和 Claude Code 相同

OpenClaw 和 Claude Code 使用完全相同的 Skill 格式——都是包含 SKILL.md 的文件夹。这不是巧合：两者都遵循 AgentSkills 规范。

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
---
（指令正文）

四级加载层次

优先级	来源	位置
最高	Workspace skills	`<workspace>/skills/`
高	Managed/local skills	`~/.openclaw/skills/`
中	Plugin skills	Plugin 包内
低	Bundled skills	随 OpenClaw 安装

对比 Claude Code 的三级：企业策略 > 用户级 > 项目级。OpenClaw 多了 Plugin 层级。

Gating 机制（OpenClaw 独有）

OpenClaw 的 Skill 有”条件加载”机制——通过 metadata.openclaw 字段定义加载条件：

{
  "openclaw": {
    "os": ["darwin"],
    "requires": {
      "bins": ["ffmpeg"],
      "env": ["OPENAI_API_KEY"],
      "config": ["skills.entries.image-lab.enabled"]
    }
  }
}

只有满足条件的 Skill 才会被加载到系统提示中。

Claude Code 没有这个——Claude Code 的 Skill 要么手动触发，要么通过 description 语义匹配。

ClawHub 市场

OpenClaw 有一个公共 Skill 市场：clawhub.com

openclaw skills install <skill-slug>    # 安装
openclaw skills update --all            # 更新所有

对比 Claude Code：Plugin Marketplace（更重量级，打包 Skill + Hook + MCP 等）。

Token 成本

每个 Skill 在系统提示中的开销：

基础开销（≥1 个 Skill）：~195 字符
每个 Skill：~97 字符 + name + description + location

粗估：每个 Skill ≈ 24 tokens。10 个 Skill ≈ 240 tokens + 基础开销。

Skill 快照

OpenClaw 在 session 开始时对 Skill 列表做快照，后续轮次复用。变更在下一次新 session 生效。

可通过 skills.load.watch: true 启用文件监控，实现热更新。

环境变量注入

Skill 可以在运行时注入环境变量：

{
  "skills": {
    "entries": {
      "image-lab": {
        "apiKey": {"source": "env", "provider": "default", "id": "GEMINI_API_KEY"},
        "env": {"GEMINI_API_KEY": "key_here"}
      }
    }
  }
}

注入仅在 Agent 运行期间有效，运行结束后恢复原环境。

与 Claude Code 的 Skill 对比

	Claude Code	OpenClaw
格式	SKILL.md（相同）	SKILL.md（相同）
触发	语义匹配 description / `/name` 手动	语义匹配 / 手动
条件加载	无	Gating（OS、二进制、环境变量、配置）
市场	Plugin Marketplace（含 Skill + Hook + MCP）	ClawHub（纯 Skill）
快照	无（description 始终在上下文）	Session 开始时快照
环境变量	无	支持 per-skill 注入
SubAgent 中	`skills:` 字段预加载	类似
`context: fork`	在独立 SubAgent 中运行	无对应
`disable-model-invocation`	隐藏直到手动调用	同名字段存在

知识检测

概念理解题

Gating 机制解决什么问题？举一个没有 Gating 会出错的场景。
Skill 快照为什么在 session 开始时做，而不是每次 Agent 运行时重新检查？
环境变量注入仅在 Agent 运行期间有效——为什么不永久设置？这和安全有什么关系？

应用题

你要为 OpenClaw 创建一个 pdf-converter Skill，它需要：Linux 或 macOS 系统、安装了 pandoc 和 wkhtmltopdf、配置了 OUTPUT_DIR 环境变量。写出完整的 SKILL.md（包括 gating metadata）。

参见

04-Skill-技能系统（Claude Code 版）— 对比学习
SlipBox 相关：Skill、OpenClaw

参考答案

1. Gating 解决什么问题

没有 Gating 的场景：一个 image-lab Skill 需要 ffmpeg 命令行工具，但用户没装。Skill 被加载到系统提示中，Agent 尝试使用它，调用 ffmpeg 报错，Agent 困惑地尝试安装或绕过——浪费 token 和时间。有了 Gating：Skill 在加载时检查 ffmpeg 是否在 PATH 中，不在就跳过，Agent 根本不知道这个 Skill 存在，不会尝试使用不可用的能力。

2. 为什么在 session 开始时做快照

性能和一致性。(1) 性能：检查所有 Skill 的 gating 条件（文件系统检查、环境变量检查）有开销，每次 Agent 运行都做会拖慢响应。做一次快照后续复用。(2) 一致性：如果在 session 中间某个 Skill 突然变得不可用（环境变量被删了），Agent 的可用工具集突然变化会导致困惑。快照保证一个 session 内工具集不变。

3. 环境变量为什么不永久设置

安全：Skill 可能注入 API key（如 GEMINI_API_KEY）。如果永久设置到 process.env：(1) 其他 Skill 或工具可能意外读到这个 key (2) 如果 Gateway 被攻击，所有 key 都暴露 (3) 日志可能泄露环境变量。运行期注入 + 运行后恢复 = 最小权限原则——每个 Skill 只在需要时才能访问自己的 key。

4. ios-screenshot SKILL.md

---
name: pdf-converter
description: Convert documents (Markdown, HTML, DOCX) to PDF using pandoc and wkhtmltopdf
metadata: {"openclaw":{"os":["darwin","linux"],"requires":{"bins":["pandoc","wkhtmltopdf"],"env":["OUTPUT_DIR"]}}}
---
## PDF Converter
Use `pandoc` to convert Markdown/HTML/DOCX to PDF.
For HTML with complex layouts, use `wkhtmltopdf` directly.
Save output to $OUTPUT_DIR and report the file path to the user.