OpenClaw Skills 开发完全指南

本文来自知乎专栏，原文标题：”深入解析 OpenClaw 的 Skills 扩展系统：AI Agent 如何学会’自我进化'”。

OpenClaw 是当下最火的开源 AI Agent 框架，GitHub star 数已突破 19 万。今天我们来看看系统的另一个关键功能，Skills 扩展。

OpenClaw 最吸引人的设计之一，就是它的 Skills（技能）扩展系统——一种让 AI 助手可以不断学习新本领、甚至能”自己给自己写技能”的插件架构。本文将从原理到实践，全面拆解这套系统的运作方式。

一、为什么 AI Agent 需要 Skills？

想象你雇了一个非常聪明的助理。他什么都懂一点，但你让他做 PPT、处理 Excel、操作智能家居、帮你发 WhatsApp 消息……他可能一脸茫然——不是因为不够聪明，而是因为不知道具体怎么操作。

这就是大语言模型（LLM）面临的核心困境：通用知识很强，专项操作能力很弱。

LLM 天生擅长理解语言、推理分析，但它不知道你的 PDF 工具怎么调用，不了解你的智能音箱的 API 是什么，也不清楚生成 Word 文档的最佳实践。传统的做法是把所有工具的调用方式硬编码到系统里，但这样做有三个致命问题：

1. 扩展性差：每加一个新能力，就要改代码、重新部署
2. Token 浪费：把所有工具的说明都塞进上下文窗口，大量 token 被浪费在当前用不上的工具描述上
3. 无法个性化：每个用户的需求不同，一刀切的能力集合无法满足所有人

OpenClaw 的 Skills 系统正是为了解决这些问题而生。简单来说：Skills 就是给 AI 助手的”操作手册”，让它在需要的时候翻阅对应的说明书，而不是把所有说明书都背下来。

二、OpenClaw 的 Skills 是如何定义的？

核心理念：用 Markdown 教 AI 做事

与 LangChain 用 Python 函数定义工具、OpenAI 用 JSON Schema 描述函数调用不同，OpenClaw 的 Skill 本质上就是一个 Markdown 文档——准确地说，是一个名为 SKILL.md 的文件，外加 YAML 格式的元数据头。

这个设计理念非常精妙：既然 LLM 最擅长阅读和理解自然语言，那为什么不直接用自然语言来教它怎么做事呢？

一个 Skill 的目录结构

skills/
└── my-awesome-skill/
    ├── SKILL.md          # 必需：YAML 元数据 + Markdown 操作指南
    ├── bins/             # 可选：可执行文件（自动加入 PATH）
    ├── references/       # 可选：参考文档
    ├── scripts/          # 可选：辅助脚本（Python、Bash、JS 等）
    └── skill.json        # 可选：旧版元数据格式

整个 Skill 里，只有 SKILL.md 是必须的，其它都是锦上添花的可选项。

SKILL.md 长什么样？

以一个图片生成 Skill 为例：

---
name: nano-banana-pro
description: 使用 Gemini 3 Pro 生成或编辑图片
metadata: {
  "openclaw": {
    "emoji": "🎨",
    "os": ["darwin", "linux"],
    "primaryEnv": "GEMINI_API_KEY",
    "requires": {
      "bins": ["uv"],
      "env": ["GEMINI_API_KEY"]
    },
    "install": [{
      "id": "brew",
      "kind": "brew",
      "formula": "gemini-cli",
      "label": "安装 Gemini CLI (brew)",
      "os": ["darwin"]
    }]
  }
}
---

# Nano Banana Pro - 图片生成技能

## 使用方法

1. 首先确认用户的需求：是生成新图片还是编辑已有图片
2. 使用 {baseDir}/scripts/generate.py 调用 Gemini API
3. 生成结果保存到工作目录
4. 向用户展示结果并询问是否需要调整

## 注意事项

- 始终使用中性、安全的提示词
- 图片尺寸默认 1024x1024
- 如果 API 返回错误，提示用户检查 API Key

让我们拆解这个文件的关键部分：

必填字段：

• name：技能名称，最长 64 个字符，必须和目录名一致
• description：技能描述，这是最关键的字段——AI 就是根据这段描述来判断什么时候该用这个技能

可选但实用的字段：

• requires.bins：运行这个技能需要哪些命令行工具
• requires.env：需要哪些环境变量（比如 API Key）
• install：如何一键安装所需依赖
• os：支持的操作系统

Markdown 正文： 就是用自然语言写的操作指南，告诉 AI “第一步做什么、第二步做什么、遇到什么情况怎么处理”。

三、Skills 的完整生命周期：从发现到执行

第一步：发现——去哪里找 Skills？

OpenClaw 启动时会从四个位置扫描 Skills，按优先级从高到低排列：

当出现同名 Skill 时，高优先级的会覆盖低优先级的。这意味着你可以在工作区目录放一个同名 Skill 来覆盖内置版本，实现”定制化”。

第二步：资格检查——这个 Skill 能用吗？

扫描到一个 SKILL.md 后，OpenClaw 会根据 requires 字段做一系列检查：

• bins：指定的命令行工具是否都装了？（比如 ffmpeg、uv）
• env：必需的环境变量是否已设置？（比如 GEMINI_API_KEY）
• config：OpenClaw 配置中是否满足条件？（比如 browser.enabled）
• os：当前操作系统是否在支持列表中？

只有所有条件都满足的 Skill 才会被标记为”可用”。这避免了 Agent 试图使用一个根本跑不起来的技能。

第三步：加载——三级渐进式披露

这是 OpenClaw Skill 系统最精妙的设计之一。它不会一股脑把所有 Skill 的完整内容塞进 AI 的上下文窗口，而是采用三级渐进式披露：

第一级——名片（约 24 个 token/Skill）： 只把 Skill 的名称、描述和文件位置以 XML 标签的形式注入系统提示词。50 个 Skill 加在一起也才约 1,200 个 token——非常经济。

<available_skills>
  <skill>
    <name>docx</name>
    <description>创建、编辑 Word 文档</description>
    <location>/mnt/skills/public/docx/SKILL.md</location>
  </skill>
  <!-- 更多 skills... -->
</available_skills>

第二级——完整说明书（按需加载）： 当 AI 判断某个 Skill 跟当前任务相关时，它会主动调用 read 工具读取完整的 SKILL.md 内容。

第三级——深度资源（需要时才加载）： 参考文档、辅助脚本等只在执行具体子任务时才会被读取。

系统提示词里会明确告诉 AI 这样的策略指引：”先扫描可用技能列表。如果恰好有一个技能明显适用，读取它的 SKILL.md。如果有多个可能适用，选最具体的那个。如果都不适用，不要读取任何 SKILL.md。”

这种设计相比 MCP 等方案动辄把所有工具 Schema 全量注入的做法，token 效率高出一个数量级。

第四步：调用——AI 自主决策

当 AI 读取了 SKILL.md 的完整内容后，它就像一个学会了新技能的人，按照说明书上的步骤一步步执行：调用相应的命令行工具、运行脚本、处理结果、回复用户。整个过程通过 OpenClaw的 Agentic Loop（代理循环）驱动：模型提出工具调用 → 执行 → 结果回填 → 继续推理 → 直到任务完成。

第五步：更新——热重载

OpenClaw 默认开启了文件监听器（debounce 250ms），实时监控 Skill 目录的变化。你修改了一个 SKILL.md，不需要重启 Agent——下一轮对话就会自动使用新版本。

配置示例（openclaw.json）：

{
  "skills": {
    "load": {
      "watch": true,
      "watchDebounceMs": 250,
      "extraDirs": ["~/shared-skills"]
    },
    "entries": {
      "nano-banana-pro": {
        "enabled": true,
        "env": { "GEMINI_API_KEY": "你的密钥" }
      },
      "some-other-skill": { "enabled": false }
    }
  }
}

注意这里的密钥注入机制：通过 entries.<name>.env 设置的环境变量只在该 Skill 执行期间生效，执行完毕后自动恢复——不会污染全局环境。

四、与 AgentSkills.io 的兼容性

AgentSkills 是什么？

AgentSkills（agentskills.io）是 Anthropic 发起的一个开放标准，最初于 2025 年 10 月作为 Claude 的专属功能推出，随后在 2025 年 12 月作为行业通用标准开放发布。它定义了一套极简的 Agent 技能描述规范：一个包含 SKILL.md 文件的文件夹，YAML 头部包含 name、description 等字段，正文是 Markdown 格式的操作说明。

OpenClaw 完全兼容 AgentSkills 标准

OpenClaw 官方文档明确表示：”我们遵循 AgentSkills 规范的布局和设计意图。” OpenClaw 在 AgentSkills 基本规范之上，通过 metadata.openclaw 扩展块添加了平台特定的功能（如依赖检查、安装器、密钥管理），但核心格式完全兼容。

这意味着什么？一次编写，到处运行。 一个符合 AgentSkills 规范的 Skill 可以跨平台使用：

• Claude Code（~/.claude/skills/）
• Claude.ai 和 Claude API
• OpenAI Codex CLI（~/.codex/skills/）
• ChatGPT（/home/oai/skills）
• GitHub Copilot / VS Code（.agents/skills/）
• Cursor（.cursor/rules/）
• Amp、Goose、Manus 等其他兼容平台

不过需要注意：agentskills.io 本身只是一个规范和文档网站，它不是一个技能市场或商店。各种第三方市场（如 SkillHub.club、ClawHub，skills.sh 等）是围绕这个标准建立的独立生态。

五、内置了哪些默认 Skills？

OpenClaw 开箱即附带 53 个官方内置 Skill，覆盖以下几大类别：

文档处理

• docx — 创建和编辑 Word 文档
• pdf — 读取、合并、拆分、填写 PDF 表单
• pptx — 制作和编辑演示文稿
• xlsx — 处理电子表格

生产力工具

• gog — Google Workspace 集成（Drive、Docs、Sheets）
• obsidian — Obsidian 笔记管理
• notion — Notion 集成
• apple-notes — macOS 备忘录
• trello — Trello 看板管理
• things-mac — Things 待办事项

消息通讯

• wacli — WhatsApp 消息
• slack — Slack 频道管理
• discord — Discord 服务器
• imsg — iMessage 短信

开发者工具

• github — GitHub 仓库操作
• tmux — 终端多路复用
• coding-agent — 编程辅助
• frontend-design — 前端设计最佳实践

智能家居与媒体

• spotify-player — Spotify 播放控制
• sonoscli — Sonos 音箱控制
• sag — ElevenLabs 语音合成
• peekaboo — macOS 截图

元技能（Meta Skills）

• clawhub — 技能注册中心管理
• skill-creator — 让 AI 自己创建新技能
• summarize — 内容摘要

这些内置 Skill 默认全部可用，你也可以通过配置文件中的 skills.allowBundled 字段来控制只加载特定的内置技能。

六、为什么这套 Skills 系统如此强大？

1. 自然语言定义，人人可写

你不需要是程序员，不需要学 Python 或 JavaScript，只要会写 Markdown 就能给 AI 定义新技能。这极大地降低了 AI 应用的开发门槛。

2. 按需加载，Token 效率极高

三级渐进式披露机制确保 AI 只在真正需要时才读取完整的 Skill 内容，50 个 Skill 的名片加起来才 1200 个 token——相比之下，MCP 等方案把所有工具 Schema 全量注入，轻松突破 1 万 token。

3. 跨平台兼容，生态共享

遵循 AgentSkills 标准意味着一个 Skill 可以在 Claude、OpenAI、GitHub Copilot、Cursor 等多个平台使用。这促进了技能生态的繁荣发展。

4. 热重载，即时生效

修改 Skill 不需要重启 Agent，文件监听器会自动检测变化并重新加载。这使得 Skill 开发和调试变得异常高效。

5. 安全的密钥管理

通过配置文件注入的环境变量只在 Skill 执行期间生效，不会污染全局环境。这种设计既保证了便利性，又兼顾了安全性。

结语

OpenClaw 的 Skills 系统代表了一种全新的 AI 应用开发范式：用自然语言定义技能，按需加载，跨平台兼容。它让 AI 从”通用聊天机器人”进化为”专属数字员工”，能够执行各种专业任务。

如果你正在构建 AI 应用，或者想让现有的 AI 助手变得更强大，深入理解并善用 Skills 系统，绝对是一个值得投入的方向。

📰 来源：知乎专栏

🔗 原文链接：https://zhuanlan.zhihu.com/p/2006196534333694047

游侠云AI普通

收藏 链接