技术笔记 OpenClaw 深度解析 OpenClaw Agent AI Skills 多智能体

OpenClaw Skills 怎样决定加载优先级与共享范围

Asaakii2026-03-182026-07-16

核验范围： 本文以 2026 年 7 月查阅的官方文档为准。Skill 的加载优先级与继承规则会随版本变化，实际部署时请用当前文档和运行结果核对。

Skill 决定 agent 在某类任务中“按什么步骤做”，而目录位置决定它会被哪个 agent 发现、同名时谁覆盖谁。本文从 Skill 与 tool 的区别讲起，再说明六层加载优先级，以及多 Agent 下如何划分共享能力和私有能力。

初学者阅读地图

先回答的问题	对应章节
Skill 和 tool 有什么不同？	第一节
一个 Skill 需要哪些文件？	第二节
同名 Skill 为什么不生效？	第三、四节
多个 agent 到底共享哪些 Skill？	第五节

如果你只想先落地一个 Skill：先放到某个 agent 的 <workspace>/skills 验证它能被发现；确认要跨 agent 复用时，再迁到共享层。不要一开始就把所有 Skill 堆到全局目录。

一、先别把 skill 和 tool 混为一谈

这是最基础、也最容易错的一层。在 OpenClaw 里，skill 和 tool 是两个东西：

tool 是能力，是「手和脚」——read、write、exec、browser、sessions_spawn、memory_search。它决定能不能做：能不能读文件、能不能起子代理、能不能控制浏览器。
skill 是方法，是「作战手册」——一个 SKILL.md 告诉 agent：什么场景该用它、按什么步骤走、要读哪些参考、调哪些脚本。它决定该怎么做。

一句话：tool 是能力层，skill 是方法层。

这个区分有个重要推论：「一个 agent 看得见某个 skill」不等于「它能把这个 skill 跑成功」。 因为 skill 只是指导，真正落地还得看 tool 权限够不够、文件路径能不能访问、资源在不在它的边界内。看得见方法，不代表有能力执行——这一点在多 agent 场景里尤其容易踩。

二、一个 skill 长什么样

OpenClaw 的一个 skill 是一个目录，核心入口是 SKILL.md（带 YAML frontmatter + markdown 说明），通常还带辅助资源：

some-skill/
├── SKILL.md          # 触发场景、步骤、要读的参考、要调的脚本
├── references/       # 详细说明：API 参考、工作流、错误处理手册
└── scripts/          # 可复用脚本：格式转换、导入导出等

发现规则官方写得很具体：只要 SKILL.md 出现在某个「configured root」下（最多 6 层深），这个 skill 就会被发现。 skill 的名字取自 frontmatter 的 name 字段，缺省时用目录名。所以 skill 不是「一个 markdown 文件」，而是一组围绕某个任务组织起来的资源。

一个最小例子：给内容 agent 写一个只用于排版的 Skill，可以先放在 <workspace>/skills/article-format/SKILL.md。它只影响这个 workspace；如果研究、内容和审核 agent 都需要同一套流程，再把它迁到共享目录，并明确它的来源和版本。

三、核心：skill 的 6 层加载优先级

这是原文讲得最含糊、而官方其实最明确的地方。原文说 skill「大致分三层」，还留了「同名用哪份要确认」的尾巴。实际上，OpenClaw 从 6 个来源加载 skill，优先级从高到低是确定的：

  flowchart TD
  A["1. Workspace skills<br/><workspace>/skills （最高）"] --> B["2. Project agent skills<br/><workspace>/.agents/skills"]
  B --> C["3. Personal agent skills<br/>~/.agents/skills"]
  C --> D["4. Managed/local skills<br/>~/.openclaw/skills （本地覆盖）"]
  D --> E["5. Bundled skills<br/>随安装分发（skill-creator、clawhub 等）"]
  E --> F["6. Extra dirs<br/>skills.load.extraDirs （最低）"]

把这 6 层归一下类，其实就是三种性质：

最高两层（<workspace>/skills、<workspace>/.agents/skills）是「谁的工作区，谁私有」——某个 agent 专属的 workflow 放这。
中间两层（~/.agents/skills、~/.openclaw/skills）是「同机共享」——想让 main、imported agents、spawn 出来的 sub-agent 都稳定看到，就放这。~/.openclaw/skills 还常用来对官方 skill 做本地覆盖（不动 bundled 原件、在这打个补丁）。
最低两层（bundled、extraDirs）是「系统与扩展」——bundled 是随安装分发的官方通用 skill（skill-creator、clawhub、healthcheck 这些），extraDirs 是你在配置里额外声明的目录。

四、同名冲突：highest source wins

有了确定的优先级，原文那个「同名 skill 到底用哪份」的老大难就有了确定答案：同名时，优先级最高的那一份生效（highest source wins）。

这解决了一个很常见的坑：你以为改了某个 skill，运行时却没生效——因为你改的是 ~/.openclaw/skills 里的版本，而 <workspace>/skills 里有个同名的、优先级更高的把它盖住了。所以一旦开始系统化维护 skill，最好在 SKILL.md 里标清来源（官方内置版 / 本机共享版 / 某 agent 私有版 / 本地覆盖版），排障成本会低很多。

真正需要「实测」的其实只有这一种情况：同名 skill 散落在多层、而你没标注来源，于是搞不清当前生效的是哪份。这不是机制玄学，是维护没做好。机制本身——6 层优先级 + highest wins——是确定的。

五、多 agent 下：到底共享哪些 skill

现在把 skill 接到第五篇的多 agent 上。核心结论：共享的是公共层，私有的是各自 workspace 层。

共享层（~/.agents/skills、~/.openclaw/skills、bundled）：这些对同机所有 agent 可见。想做「公司内部通用 skill」「跨角色统一 workflow」，放这。
私有层（<workspace>/skills、<agent>/.agents/skills）：谁的 workspace 谁优先看自己那份。某个安全 agent 的专用审计模板、某个内容 agent 的特殊排版流程，放这。

所以「main agent 的本地 skill，其他 imported agent 能不能用」这个问题，答案是确定的：main 放在 <workspace>/skills 里的私有 skill，其他 agent 不天然共享；想共享就往上挪到共享层。 不是「有时会有时不会」，是「看你放哪层」。

至于 sub-agent 继承哪些 skill，官方给的是一套明确规则（在 agents 配置里）：

配置写法	效果
省略 `agents.list[].skills`	继承 `agents.defaults.skills`
`skills: []`	该 agent 不暴露任何 skill
非空 list，如 `["a", "b"]`	这就是最终集合，完全覆盖、不与 defaults 合并

第三行最容易踩：一旦你给某个 agent 显式写了 skill 列表，它就不再继承默认的那批了——你以为是「在默认基础上加两个」，实际是「只剩这两个」。这跟第五篇讲的 allowAgents 是同一种设计脾气：要么继承默认，要么显式声明的就是全部，没有隐式合并。

六、回到主线：skill 可见性也是配置，不是玄学

原文最有价值的部分其实是它的实践建议，我完全认同，这里保留下来：

要被很多 agent 复用的 skill，别只藏在 main 的 workspace 里——放到 ~/.openclaw/skills 这种共享层。
只服务某个角色的 skill，就留在那个角色自己的 workspace——职责边界更清楚。
skill 放哪不只是目录问题，是架构问题——它直接决定了你的多 agent 工作流能不能稳定复用能力。

但原文把机制本身讲成了「要靠实测的玄学」，这一点我想纠正，因为它正好落在本系列反复出现的那条主线上。

从第一篇的 lane 队列、第三篇的 capability 分级、第五篇的 allowAgents 白名单，到这一篇的 skill 6 层优先级和继承规则——OpenClaw 反复在做同一件事：把「谁能看见什么、同名用哪份、子代理继承哪些」这些边界，写成确定的配置规范，而不是留给运行时的运气。 skill 之所以让很多人觉得像玄学，不是因为它真的不确定，而是因为它的规范藏在文档里、没被读到，于是大家只能靠实测反推。一旦你看到那 6 层优先级，「为什么这个 skill 这个 agent 能用、那个不能用」就从玄学变成了查表。