OpenClaw 进阶:理解 Skills 分层设计,告别多 Agent 协作＂玄学＂

很多人第一次接触 OpenClaw 的 Skills 机制，都会把几件事混在一起：

• skill 和 tool 到底是不是一回事？
• skill 应该放在哪个目录下？
• main agent 能用的 skill，sub-agent 能不能用？
• 不同 agent 之间能不能共享 skill？
• 同名 skill 如果同时出现在多个位置，系统到底会用哪一份？

如果这些边界不先讲清楚，后面一旦开始做多 Agent 协作，目录结构和行为就会越看越像"玄学"，出了问题都不知道该去哪排查。

这篇文章的目标很简单：先讲清楚 OpenClaw 里 skill 的本质是什么，再讲清楚 skill 的目录层次，最后说明不同角色 agent 之间和 skill 的关系，帮你建立清晰的工程认知。

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

这是最核心的一层认知错误。在 OpenClaw 里，skill 和 tool 不是同一个东西。

1.1 tool 是能力

tool 更像"手和脚"，是 agent 真正可以直接调用的操作能力，例如：

• read / write / edit：文件读写修改
• exec：执行系统命令
• browser：控制浏览器网页
• sessions_spawn：启动子代理
• memory_search：语义搜索记忆

tool 决定的是：能不能做这件事。有对应的 tool 权限，才能执行对应的操作。

1.2 skill 是工作方法

skill 更像"作战手册"或者"标准流程"。一个 skill 通常会告诉 agent：

• 在什么场景下应该启用它
• 先读哪个 SKILL.md
• 遇到这个问题应该走什么工作流
• 需要用哪些脚本、参考资料或外部命令

所以，skill 解决的是：应该怎么做，按什么步骤做。

一句话概括：

tool 是能力层，skill 是方法层

这也是为什么"一个 agent 看得见某个 skill"，并不自动等于"它一定能把这个 skill 完整执行成功"。因为 skill 只是指导，真正落地还取决于：

• tool 权限是否足够
• 文件路径是否可访问
• 当前 workspace 是否能看到对应资源
• 这个 skill 是否被 agent 的技能过滤规则允许

二、三层结构解析：OpenClaw 的 skill 到底从哪来

理解 skills 机制，最容易误解的地方就是以为"skill 只有一个统一目录"。实际上，OpenClaw 会从多个层次去发现 skill，我们可以把它清晰地分为三层：

2.1 第一层：全局安装层

这是 OpenClaw 安装包自带的一批 skills，典型位置类似：

.../node_modules/openclaw/skills

这里放的通常是：随 OpenClaw 一起分发的通用 skill，偏系统级、官方级、基础能力级。

比如你现在能看到的：

• skill-creator：创建和编辑技能
• healthcheck：主机安全检查
• tmux：远程控制 tmux 会话
• weather：获取天气信息

这层可以理解成：OpenClaw 安装级别的全局技能库，只要装了 OpenClaw 就能用。

2.2 第二层：共享层

这是很多人真正关心、但最容易没讲清的部分。从机制上看，OpenClaw 还会扫描一些不属于某个单独 agent workspace的公共目录，例如：

• ~/.openclaw/skills
• ~/.agents/skills

这类目录更适合放"跨 agent 复用"的自定义 skill。也就是说，如果你的目标是：

• main agent 能用
• imported agents（比如 agency-agents）能用
• 通过 sessions_spawn 拉起的 sub-agent 也更大概率能用到

那比起只放到某个 agent 的私有 workspace 里，更适合放到这种公共共享层。

这层可以理解成：机器级、配置级、跨 workspace 的共享技能库。如果你想打造自己的公共技能集，这一层最合适。

2.3 第三层：Workspace 层

每个 agent 自己的 workspace 下面，也可能有 skills 目录，例如：

• ~/.openclaw/workspace/skills
• ~/.openclaw/agency-agents/<agent-name>/skills

这一层更像：某个特定 agent 的本地技能库。

这类 skill 最大的特点是：

• 更接近这个 agent 自己的工作区
• 更适合放该 agent 专用的 workflow
• 不应默认假设别的 agent 也一定能自动共享到

比如你的内容写作 agent 有自己专用的排版流程，就可以放在它自己的 workspace 下，不需要暴露给所有 agent。

三、不同角色 agent 的可见性：谁能用到谁？

这是大家最容易直接问的问题：main agent、agency-agents、sub-agent 之间，skill 到底能不能共享？

更准确的回答不是"能"或者"不能"，而是：要看这个 skill 落在私有层，还是落在共享层，以及子代理运行时的可见范围和边界策略。

我们分情况来看：

情况 A：skill 在全局安装层

比如这个 skill 在 OpenClaw 自带的全局 skills 目录里。那么通常：

• main agent 可以用
• imported agents 也大概率可以用
• sessions_spawn 拉起的 sub-agent 通常也可以用

前提是：tool 权限允许，且 agent 没有额外的 skills filter 把它禁掉。这类 skill 属于"最像公共能力"的那种。

情况 B：skill 在共享层

比如放在 ~/.openclaw/skills 或 ~/.agents/skills，那么它也更像一份机器级共享能力。

这种放法通常适合：

• 希望多个 agent 复用
• 希望 main 和 imported agents 都能稳定发现
• 希望把某个 workflow 做成公共基础设施

如果你要做"公司内部通用 skill"或者"整套 multi-agent 公共工作流 skill"，这层通常比放到某个 workspace 私有目录更合适。

情况 C：skill 只在 main 的 workspace 层

比如路径是 ~/.openclaw/workspace/skills/my-custom-skill，这时要注意：main agent 当然最容易用到它，但 imported agent 或 sub-agent 是否也能用，不应默认想当然。

这里至少有三种可能：

1. 子代理真的可以直接读到 main 的那条路径
2. 这份 skill 恰好也同步到了子代理自己的 workspace 里
3. 当前环境存在更宽的技能发现或文件访问边界

所以对于"只放在 main workspace 的 skill"，最稳妥的态度不是拍脑袋，而是做实测。

关键误区澄清

很多人会把 sub-agent 想成"main agent 的完全克隆"，其实更准确的理解是：

sub-agent 是由 main 发起，但按目标 agent 角色和环境独立运行的子任务执行者。

它继承的是目标 agent 的身份、配置、workspace 和工具权限，不是简单复制 main 的所有东西。所以 skill 是否可用，必须同时看三点：

1. 这个 skill 在不在当前可发现范围里
2. 这个子代理有没有执行所需 tools 的权限
3. 这个 skill 的资源文件在它的边界内能不能读到

四、同名 skill 多目录存在：如何避免排障踩坑

这也是工程上很容易踩坑的一点。比如某个 skill 同时出现在：

• 全局安装层
• ~/.openclaw/skills（共享层）
• main 的 workspace/skills（私有层）

那么就会出现两个现实问题：

1. 系统最终优先用哪一份？
2. 你修改的是不是当前真正生效的那一份？

这类问题如果不去确认，就容易出现：你以为自己改了 skill，实际运行时却读的是另一个目录里的同名版本，调试半天发现改错地方了。

实践建议

因此，一旦你开始系统化维护 skill，最好做到这几点：

1. 标注来源：在文档或注释里标注清楚这个 skill 来自哪一层：官方内置版 / 本机共享版 / 某个 agent 私有版
2. 明确覆盖意图：如果你确实想覆盖官方 skill，把它放到共享层，这样优先级会高于内置版本（具体优先级由 OpenClaw 加载顺序决定，通常后面加载的会覆盖前面的）
3. 实测确认：修改完 skill 后，在实际运行的 agent 里测试一下，确认加载的是你修改后的版本

这会大幅降低后期排障成本。

五、工程实践：我该怎么设计我的 skills 层次？

结合前面的分析，如果要给出一套比较稳的实践建议，可以这样分类放置：

第一类：官方通用 skill

直接用OpenClaw自带的就好，放在全局安装层，不需要你额外处理。适合：随系统分发，大多数环境都能复用，不依赖你的私人目录结构。

第二类：机器级共享 skill

放在 ~/.openclaw/skills 或 ~/.agents/skills。适合：

• 你自己这台机器上的多个 agent 共同使用
• 你想把它当作跨 agent 的公共能力
• 你希望 main 和 agency-agents 都更稳定看到它

如果你的目标是打造一套长期复用的 multi-agent 能力层，这一层最关键。

第三类：workspace 私有 skill

放在对应 agent 的 workspace 下的 skills 目录。适合：

• 某个特定 agent 的专用流程
• 某个项目临时用的 skill
• 不想全局暴露的本地 workflow

这类 skill 非常有价值，但不要默认把它当作"全系统共享能力"。放在私有层，职责边界更清晰。

总结一下放置原则

六、常见问题排查思路

整理了几个大家最常遇到的问题，给你一套排查思路：

问题 1：我写了一个 skill，main 能用到，sub-agent 找不到

大概率原因：skill 只放在了 main 的 workspace 私有层，sub-agent 的运行环境访问不到这个路径。

解决方法：如果确实需要所有 agent 都能用，把 skill 移到共享层（~/.openclaw/skills）。如果只是这个 sub-agent 自己用，把它复制到 sub-agent 自己的 workspace 下。

问题 2：我改了 skill，但是运行还是旧行为

大概率原因：存在多个同名 skill，你改错了位置，系统加载了另一个目录的旧版本。

解决方法：检查全局安装层、共享层、当前 workspace 层是否都有这个 skill，确认你修改的是系统实际加载的那一个。可以通过实测确认当前加载的版本。

问题 3：我想让所有 agent 都能用我的 skill，该放哪？

答案：直接放到共享层 ~/.openclaw/skills，比放到每个 agent 的 workspace 更省心，也更容易维护。

总结

如果只用一句话概括 OpenClaw 的 skills 机制，那就是：

Skill 不是"一个统一目录里的插件列表"，而是一套分层发现、按 workspace 和共享范围组织起来的工作流系统。

更完整一点说：

• tool 是能力，skill 是方法
• skill 可以来自：全局安装层、共享层、以及各 agent 自己的 workspace 层
• main agent、agency-agents、sub-agent 不一定天然共享所有私有 skill
• 真正稳定的跨 agent 共享，应该依靠明确的共享层，而不是隐含假设

当你把这套机制看清楚之后，很多原本模糊的问题就会变得很直白：

• 为什么有些 skill main 能用，别的 agent 不一定能用？因为放的层次不对
• 为什么有些 skill 明明同名，却可能不是同一份？因为来自不同层
• 为什么 multi-agent 要认真设计 skill 的放置层级？因为放错位置会导致共享和隔离出问题

一旦这些边界建立起来，OpenClaw 的 skills 体系就不再神秘，而会变成一套很清晰的工程结构：

通用能力放公共层，角色能力放私有层，让 agent 在合适的范围内共享合适的工作流。

如果你在使用 OpenClaw 过程中遇到其他 skill 相关问题，欢迎留言交流。