Skills

Skills 是教 Agent 如何使用外部工具的 Markdown 文件夹（遵循 AgentSkills 规范）。每个 Skill 是一个包含 SKILL.md 的目录，里面有 YAML 前言和使用说明，Agent 会在推理时参考这些说明。

加载位置与优先级

Skills 从三个位置加载（优先级从高到低）：

1. 工作区 Skills：<workspace>/skills（专属于该 Agent）
2. 本机共享 Skills：~/.openclaw/skills（跨工作区共享）
3. 内置 Skills：随 OpenClaw 安装包附带

同名 Skill 以最高优先级为准。此外，可通过 skills.load.extraDirs 配置额外目录（最低优先级）。

多 Agent 场景：

• 工作区 Skills → 仅当前 Agent 可见
• ~/.openclaw/skills → 所有 Agent 共享
• 可用 skills.load.extraDirs 共享一份 Skills 包给多个 Agent

从 ClawHub 安装 Skills

ClawHub 是 OpenClaw 的公共 Skills 注册表（https://clawhub.com）：

# 安装 Skill 到当前工作区
clawhub install <skill-slug>

# 更新所有已安装的 Skills
clawhub update --all

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

SKILL.md 格式

每个 Skill 目录至少包含一个 SKILL.md：

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
---

# Skill 说明
在这里写 Agent 应该怎么使用这个工具...

可选的前言字段：

字段	说明
homepage	在 macOS Skills UI 中展示的官网链接
user-invocable	true（默认）时作为用户 slash 命令暴露
disable-model-invocation	true 时不注入模型提示（仅用户可调用）
command-dispatch: tool	跳过模型，直接路由到指定工具
command-tool	与 command-dispatch: tool 配合，指定工具名

加载时过滤（Gating）

OpenClaw 在加载时根据 metadata 字段过滤 Skills，不满足条件的自动跳过：

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

过滤字段说明（metadata.openclaw 下）：

字段	说明
always: true	始终加载，跳过其他检查
os	仅在指定平台加载（darwin/linux/win32）
requires.bins	这些可执行文件必须在 PATH 上
requires.anyBins	至少一个在 PATH 上
requires.env	环境变量必须存在（或在 config 中提供）
requires.config	指定的 openclaw.json 路径值必须为真
primaryEnv	与 skills.entries.<name>.apiKey 关联的环境变量名

配置覆盖（openclaw.json）

在配置文件中启用/禁用 Skills，并注入 API Key 和环境变量：

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: "YOUR_GEMINI_KEY_HERE",  // 或 { 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: ["gemini", "session-memory"],  // 只允许指定的内置 Skills
  },
}

规则：

• enabled: false 禁用（即使是内置 Skill）
• env：仅在环境变量尚未设置时注入
• apiKey：与 metadata.openclaw.primaryEnv 关联
• config：自定义字段的存放位置

安装器（Installer）

Skills 可以声明自动安装方法，macOS Skills UI 会据此引导安装：

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
  {
    "openclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "Install Gemini CLI (brew)",
            },
          ],
      },
  }
---

支持的安装方式：brew、node、go、uv、download。

Node 安装使用 skills.install.nodeManager（默认 npm；支持 npm/pnpm/yarn/bun）。

环境注入时机

每次 Agent 运行时：

1. 读取 Skill 元数据
2. 将 skills.entries.<key>.env 或 .apiKey 注入 process.env
3. 构建含可用 Skills 的系统提示
4. 运行结束后恢复原始环境

作用域为单次 Agent 运行，不污染全局环境。

会话快照（性能优化）

Sessions 启动时对可用 Skills 做快照，整个 Session 内复用该列表。Skills 或配置变更在下一次新会话时生效。

开启 Skills 热重载（监视文件变化）：

{
  skills: {
    load: {
      watch: true,
      watchDebounceMs: 250,
    },
  },
}

Token 开销估算

Skills 以紧凑 XML 形式注入系统提示，开销公式：

总字符 = 195 + Σ (97 + len(name) + len(description) + len(location))

粗略估算：每个 Skill 约 24 tokens（不含 name/description 本身）。

安全注意事项

• 将第三方 Skills 视为不可信代码，使用前先阅读
• Skills 的 env/apiKey 注入到宿主进程（不是沙箱内），不要在提示或日志中暴露 secret
• 如需在沙箱内使用 Skill 依赖的二进制工具，需通过 agents.defaults.sandbox.docker.setupCommand 安装