OpenClaw Skills 机制总结

一、什么是 Skill

Skill 是一个包含 SKILL.md 的目录，遵循 AgentSkills 规范。它通过 Markdown 指令教 LLM 如何使用特定工具或工作流。

my-skill/
├── SKILL.md          # 必须：定义 + 指令
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：按需加载的参考文档
└── assets/           # 可选：输出用的资源文件

SKILL.md 结构：

---
name: my-skill
description: 一句话描述，帮助 LLM 判断何时触发
user-invocable: true
metadata:
  { "openclaw": { "emoji": "", "skillKey": "my-skill", "requires": { "bins": ["some-cli"] } } }
---

这里是 Markdown 正文，包含 LLM 使用该 skill 的完整指令...

二、Skill 存储位置（按优先级从低到高）

同名 skill，高优先级覆盖低优先级。

三、Skill 的两种触发方式

1. 模型自动触发 — skill 的 name + description 被注入到系统提示词中，LLM 根据用户意图自动判断是否调用。

2. 用户手动触发 — 在对话中输入 /skill-name（斜杠命令），直接激活该 skill。

通过 frontmatter 控制行为： - user-invocable: true — 暴露为用户斜杠命令 - disable-model-invocation: true — 仅用户手动触发，模型不自动调用 - command-dispatch: tool — 绕过模型，直接调用指定工具

四、Skill 准入门控（Gating）

通过 metadata.openclaw 中的字段控制 skill 是否可用：

{
  "openclaw": {
    "always": true,                    // 跳过所有检查，始终加载
    "os": ["darwin", "linux"],         // 操作系统限制
    "requires": {
      "bins": ["ffmpeg"],              // 必须安装的命令行工具
      "anyBins": ["bun", "node"],      // 至少安装其中一个
      "env": ["OPENAI_API_KEY"],       // 必须设置的环境变量
      "config": ["browser.enabled"]    // 必须开启的配置项
    }
  }
}

不满足条件的 skill 不会加载到 LLM 上下文中。

五、CLI 管理命令

openclaw skills list               # 列出所有 skill
openclaw skills list --eligible    # 仅显示当前可用的
openclaw skills list --verbose     # 显示缺失依赖详情
openclaw skills info <name>        # 查看单个 skill 详情
openclaw skills check              # 检查所有 skill 就绪状态

六、配置管理

在 ~/.openclaw/openclaw.json 中：

{
  "skills": {
    // 启用/禁用 + API Key 管理
    "entries": {
      "gemini": { "enabled": true, "apiKey": "xxx" },
      "peekaboo": { "enabled": false }
    },
    // 限制内置 skill 范围
    "allowBundled": ["gemini", "peekaboo"],
    // 额外 skill 目录
    "load": {
      "extraDirs": ["~/my-skills-pack/skills"],
      "watch": true
    }
  }
}

Per-agent skill 过滤：

{
  "agents": {
    "list": [
      { "id": "coding-agent", "skills": ["gemini", "github"] }
    ]
  }
}

七、最佳实践

1. 分层管理

2. 编写高质量 SKILL.md

• description 精准简洁，帮助 LLM 正确判断触发时机
• 用 requires 声明依赖，避免运行时报错
• 正文中写清楚何时使用 / 何时不使用（参考内置 skill 的 "Use when" / "Do NOT use" 模式）
• 脚本放 scripts/，大段参考资料放 references/（按需加载，节省 token）

3. 控制 token 开销

每个 eligible skill 都会占用系统提示词 token。建议： - 用 enabled: false 关闭不常用的 skill - 用 allowBundled 只加载需要的内置 skill - 用 disable-model-invocation: true 让不常用但偶尔需要的 skill 仅在 /命令 时触发 - SKILL.md 正文保持精炼

4. 热重载开发

开启 skills.load.watch: true 后，编辑 SKILL.md 会自动重载（默认 250ms 防抖），开发调试时无需重启。

5. 安全注意

• 安装 skill 依赖前会自动安全扫描（检测 child_process、eval、数据外传等危险模式）
• apiKey 存在配置文件中，通过环境变量注入运行时，运行结束后自动清理
• 不要在 SKILL.md 中硬编码敏感信息