OpenClaw Skills 系统深度解析：从源码到自定义技能

作者：CSDN博客

---

一、引言：为什么需要理解 Skills 系统？

OpenClaw 作为一款强大的 AI Agent 框架，其核心魅力不仅在于内置的工具集，更在于极度灵活的可扩展性。而这一切的基石，正是 Skills 系统——一个基于 AgentSkills 规范的插件化架构。
如果你只是使用 OpenClaw 的默认功能，那可能只用了其 30% 的能力。当你需要：

集成内部工具（公司数据库、私有 API）为特定场景定制智能行为（如股票分析、代码审查）贡献社区技能，建立个人影响力理解框架源码，进行深度定制

这时，Skills 系统就是你必须掌握的桥梁。本文将从源码级别剖析 Skills 的加载、配置、分发机制，并提供手把手的实战教程，让你从使用者变为扩展者。

---

二、Skills 系统架构解析

技能在哪里？——三层加载优先级

OpenClaw 的技能来源分为三个层次，形成一个清晰的优先级链：
1. Bundled Skills（内置技能）

随 OpenClaw npm 包或应用一起安装的技能，位于：

1. /Users/xgn/.npm-global/lib/node_modules/openclaw/skills/

复制代码

示例：coding-agent、peekaboo、gemini、github 等。
2. Managed/Local Skills（管理技能）

用户级覆盖目录：

1. ~/.openclaw/skills/

复制代码

用于局部修改内置技能（比如 patch 一个 bug 或调整提示词），而无需改动 bundled 版本。
3. Workspace Skills（工作区技能）

当前 OpenClaw 会话的工作区目录：

1. <workspace>/skills/

复制代码

你可以为不同项目配置不同的技能集，实现完全隔离。
Precedence 规则（优先级）

1. <workspace>/skills  (最高) → ~/.openclaw/skills → bundled skills (最低)

复制代码

同名技能，workspace 版本始终胜出。这意味着你可以安全地覆盖任何内置技能，而不会影响全局。

实战：覆盖内置技能

假设你想修改 coding-agent 的提示词：

1. # 1. 在工作区创建同名技能目录mkdir-p ~/.openclaw/workspace/skills/coding-agent
3. # 2. 复制原技能文件（从 bundled 复制过来）cp /Users/xgn/.npm-global/lib/node_modules/openclaw/skills/coding-agent/SKILL.md \
4.    ~/.openclaw/workspace/skills/coding-agent/
6. # 3. 编辑 SKILL.md，修改指令部分# 4. 启动新会话，workspace 版本自动覆盖 bundled

复制代码

Skills 与 Plugins 的关系

OpenClaw 的插件（Plugins）可以打包自己的技能，在 openclaw.plugin.json 中声明：

1. {"skills":["./skills"]// 相对路径}

复制代码

插件技能在插件启用时加载，参与同样的优先级规则。这使得：

功能模块化（例如 feishu 插件打包 4 个技能：doc/drive/perm/wiki）第三方开发者可以分发完整的技能+工具包

单 Agent vs 多 Agent 场景

在多 Agent 架构中，每个 Agent 有独立的 workspace。因此：

Per-agent skills：放在 <workspace>/skills，仅该 Agent 可见Shared skills：放在 ~/.openclaw/skills，所有同机 Agent 共享Extra dirs：通过 skills.load.extraDirs 配置，最低优先级，适合共享技能包

1. {
2.   skills: {
3.     load: {
4.       extraDirs: ["~/Projects/oss/skill-pack/skills"]
5.     }
6.   }
7. }

复制代码

---

三、SKILL.md 格式详解

Frontmatter 元数据规范

一个技能的核心是 SKILL.md，采用 YAML frontmatter + Markdown body：
[code]---name: coding-agent
description:'Delegate coding tasks to Codex, Claude Code, or Pi agents...'metadata:{"openclaw":{"emoji":"