OpenClaw Skill 是 OpenClaw 智能体框架的核心扩展机制，其本质是“教智能体如何使用工具”的模块化功能单元。每个 Skill 是一个包含带有 YAML frontmatter 元数据和 Markdown 说明文件的目录，遵循 AgentSkills 开放规范。

Skill 的核心价值在于：将通用大语言模型转变为具备特定领域专业知识的智能体，通过注入操作指令、工具集成和领域知识，让智能体能够完成文件处理、API 调用、自动化操作等复杂任务。

如果将 OpenClaw 智能体比作“大脑”，Skill 就是为其配备的“经验 + 行动指南”。两者是互补的架构模式：Agent 读取 Skill 获得领域知识，进而能够调用工具完成实际工作。

每个 Skill 的最小单元是一个包含必要文件的目录，结构如下：

skill-name/ ├── SKILL.md # 必需：YAML 元数据 + Markdown 指令 ├── scripts/ # 可选：可执行代码（Python/Bash 等） ├── references/ # 可选：按需加载的参考文档 └── assets/ # 可选：输出用的资源文件（模板、图标等） 

SKILL.md 是 Skill 的核心文件，由两部分组成：

1. YAML frontmatter（前置元数据） ：定义 Skill 的标识、描述和准入规则，以 --- 开头和结尾
2. Markdown body（正文） ：提供给智能体的操作指令和说明

重要格式约束：OpenClaw 内嵌的智能体解析器仅支持单行 frontmatter 键值，以保证与 Pi Agent 运行时的兼容性。metadata 字段必须是一个单行 JSON 对象，不能使用多行 YAML 缩进写法。

✅ 正确写法示例

--- name: hello_world description: A simple skill that says hello. metadata: {"openclaw": {"requires": {"bins": ["echo"]}}} --- # Hello World Skill When the user asks for a greeting, use the `echo` tool to say "Hello from your custom skill!" 

在 Markdown 正文中可使用 {baseDir} 占位符来引用 Skill 文件夹路径，便于引用 scripts/ 目录下的脚本。

SKILL.md 的 YAML frontmatter 支持以下字段。除 metadata 为单行 JSON 外，其余字段均为普通字符串值。

metadata JSON 对象内可包含以下 openclaw 子属性：

🏷️ name 与 description

name 和 description 是智能体用来确定是否触发该 Skill 的唯一字段，因此清晰、全面地描述 Skill 的功能和使用场景至关重要。

🚦 metadata.openclaw.requires（准入门控）

通过 requires 字段，OpenClaw 在加载时根据环境、配置和二进制文件存在情况对 Skill 进行过滤。requires.env 检查的是环境变量存在或已通过 skills.entries. .env 在配置中提供，并非仅检查系统环境变量。

metadata: {"openclaw": {"requires": {"bins": ["gh", "git"], "anyBins": ["jq", "yq"], "env": ["GITHUB_TOKEN"], "config": ["github.username"], "os": ["darwin", "linux"]}}} 

OpenClaw 使用 evaluateEntryRequirementsForCurrentPlatform 函数检查当前平台上的 OS 兼容性、必需二进制文件的存在性以及必要的环境变量。

📦 metadata.openclaw.install（自动安装）

定义 Skill 依赖的自动安装方式，支持五种安装器类型：

Gateway 网关会根据 install.preferBrew 配置优先选择安装器，在可用时优先使用 brew。

所有 Skill 加载器和安装配置位于 ~/.openclaw/openclaw.json 中的 skills 键下。

{ "skills": { "allowBundled": ["gemini", "peekaboo"], "load": { "extraDirs": ["~/Projects/agent-scripts/skills"], "watch": true, "watchDebounceMs": 250 }, "install": { "preferBrew": true, "nodeManager": "npm" }, "entries": { "nano-banana-pro": { "enabled": true, "apiKey": { "source": "env", "provider": "default", "id": "GEMINI_KEY_HERE" }, "env": { "GEMINI_API_KEY": "your-key-here" }, "config": { "endpoint": "https://example.invalid", "model": "nano-pro" } } } } } 

注意：entries 下的键默认映射到 Skill 名称。如果 Skill 定义了 metadata.openclaw.skillKey，则使用该键。

OpenClaw 从多个层级加载 Skill，同名冲突时高优先级覆盖低优先级：

此外，插件 Skills 是一种特殊来源：插件通过 openclaw.plugin.json 的 skills 目录附带 Skill，参与正常的优先级规则，位于工作区 Skill 之后、共享 Skill 之前。

• 单智能体 Skill：位于 /skills ，仅供该智能体使用
• 共享 Skill：位于 ~/.openclaw/skills，对同一机器上的所有智能体可见
• 额外目录：通过 skills.load.extraDirs 添加共享文件夹（最低优先级）

使用 Agent 配置来控制每个智能体可见的 Skill 集合：

{ "agents": { "defaults": { "skills": ["github", "weather"] }, "list": [ { "id": "writer" }, // 继承 defaults { "id": "docs", "skills": ["docs-search"] }, // 替换 defaults { "id": "locked-down", "skills": [] } // 无 Skill ] } } 

规则：

• agents.defaults.skills：共享基线白名单
• 省略 agents.defaults.skills：默认无限制
• agents.list[].skills：该智能体的最终 Skill 集合，不与 defaults 合并，而是完全替换

OpenClaw 在加载 Skill 时根据以下条件进行过滤：

• 操作系统兼容性（metadata.openclaw.os）
• 必需二进制文件的存在性（bins 全部存在，anyBins 至少一个存在）
• 必需环境变量是否设置或已通过配置提供
• 配置键是否存在
• 智能体 Skill 白名单
• allowBundled 白名单

skills.status（Gateway 网关）返回所有 Skill 及其资格状态和缺失的要求，包括内置 Skill 的允许列表阻止情况。

OpenClaw 在会话开始时对 eligible skills 进行快照，后续轮次复用该快照。启用监视器（load.watch: true）后，Skill 文件夹的更改会在下一个智能体轮次被自动获取，无需重启 Gateway。但变更需新会话或 watcher 触发刷新才能生效。

环境变量可通过多种方式注入 Skill：

1. 配置文件注入：通过 skills.entries. .env 在 ~/.openclaw/openclaw.json 中配置
2. API 密钥便捷字段：skills.entries. .apiKey 作为主环境变量的便捷声明方式，支持明文值或 SecretRef 对象
3. 运行时注入：skills.update 命令更新 enabled、apiKey 和 env

当会话处于沙箱隔离状态时，Skill 进程在 Docker 内运行，沙箱不会继承宿主机的 process.env。解决方案：

• 使用 agents.defaults.sandbox.docker.env（或单智能体的 agents.list[].sandbox.docker.env）
• 将环境变量烘焙到自定义沙箱镜像中

全局 env 和 skills.entries. .env/apiKey 仅适用于宿主机运行。

当 Gateway 运行在 Linux 上但连接了 macOS node 时，macOS-only 的 Skill（metadata.openclaw.os: ["darwin"]）也可以变为 eligible，通过 nodes.run 在远程 macOS 节点上执行。这为跨平台部署提供了灵活性。

Skill 注入到模型 prompt 会产生 token 消耗，精确开销公式如下：

• 基础开销：当至少 1 个 skill 被激活时，注入 195 个字符的固定前缀
• 单个 skill 开销：97 字符 + name + description + location 的 XML 转义长度

开发者可通过控制 name 和 description 长度来优化上下文窗口占用。

• 将第三方 Skill 视为不受信任的代码：启用前请仔细阅读 Skill 内容
• 使用沙箱隔离：对于不受信任的输入和高风险工具，优先使用沙箱隔离运行
• 密钥保护：skills.entries.*.env 和 skills.entries.*.apiKey 为该智能体轮次将秘密注入到宿主机进程中，需确保秘密不进入提示词和日志
• 端口隔离：建议不将 OpenClaw 默认端口暴露到公网，不使用管理员权限运行

工作区和额外目录的 skill 发现只接受解析后的真实路径保持在配置根目录内的 Skill，有效防止通过符号链接逃逸到任意文件系统位置。

早期版本（< 2026.2.14）曾存在沙箱 skill 镜像的路径遍历漏洞（CVE-2026-28457），通过未净化的 skill frontmatter name 参数导致，已在后续版本修复。

Skill 本身不具备独立权限，仅调用已开启的 Tools。若未开启对应 Tools，Skill 无法生效。官方 bundled Skills 会随系统自动启用，需手动设置白名单限制。

• 简洁原则：上下文窗口是公共资源，只添加智能体尚未具备的上下文，优先使用简洁的示例而非冗长的解释
• 设置适当自由度：将详细程度与任务的脆弱性和可变性相匹配（高自由度指令 → 中等自由度伪代码 → 低自由度特定脚本）
• 本地测试：发布前使用 openclaw agent --message "..." 进行测试
• 使用 Skill Creator：OpenClaw 提供 Skill Creator 技能，它本身就是技能创建的**实践示例，遵循 agentskills 开放规范

OpenClaw 提供两套独立的 CLI 命令集：

OpenClaw Gateway 提供 REST API（默认监听 http://127.0.0.1:18789），可用于查询 Skill 状态和触发操作：

• skills.status：返回所有 Skill 及其资格状态
• skills.install：在 Gateway 主机上运行 Skill 安装器
• skills.update：更新 enabled、apiKey 和 env 配置

以下是一个符合单行 JSON 格式要求的完整 Skill 定义：

SKILL.md

— name: github_pr_manager description: Manage GitHub pull requests, including creation, review, and merging. metadata: {“openclaw”: {“os”: [“darwin”, “linux”], “requires”: {“bins”: [“gh”, “git”], “env”: [“GITHUB_TOKEN”], “config”: [“github.username”]}, “install”: [{“type”: “brew”, “formula”: “gh”}, {“type”: “node”, “package”: “@octokit/rest”}], “skillKey”: “github”, “primaryEnv”: “GITHUB_TOKEN”, “emoji”: “🐙”, “homepage”: “https://cli.github.com”}} user-invocable: true

disable-model-invocation: false

GitHub Pull Request Manager

This skill enables the agent to manage GitHub pull requests using the gh CLI tool.

When to Use

• User asks to create a PR
• User wants to review or merge a PR
• User needs to list open PRs in a repository

Commands

1. List PRs: gh pr list --repo /
2. Create PR: gh pr create --title "..." --body "..." --base main
3. Merge PR: gh pr merge --merge

Environment

Ensure GITHUB_TOKEN is set with appropriate repo scopes.

对应配置文件（~/.openclaw/openclaw.json）

{ “skills”: {

"entries": { "github": { "enabled": true, "apiKey": { "source": "env", "provider": "default", "id": "GITHUB_TOKEN" }, "env": { "GITHUB_TOKEN": "your-github-token-here" } } } 

}, “agents”: {

"defaults": { "skills": ["github", "weather"] } 

} }