【WorkBuddy专栏12】技能到底存在哪？——WorkBuddy两级技能存储架构深度解析

前几天有个读者在后台问我：「WB 的项目功能里，技能是单独的一个空间是吗？如果是，那普通工作空间和项目，不是割裂了？技能还出现了重复？」

这个问题问得非常犀利。它触及了 WorkBuddy 架构设计里最容易被误解、也最容易用错的一部分。

很多人用了一段时间 WB 之后，都会遇到这个困惑：我在 A 项目里装的技能，为什么 B 项目里没有？我在全局装的技能，项目里能用吗？两个地方都有同一个技能，WB 用哪个？

今天这篇文章，我把 WB 的技能存储架构彻底拆开——从目录结构、加载优先级、到实际使用中的最佳实践，一次性讲清楚。

一、先建立认知：WB 的技能存储不是「一个地方」，而是「两级架构」

要搞清楚技能在哪里，首先得理解 WB 对「技能」的定义。

技能（Skill）= 一个独立的目录，里面至少有SKILL.md文件。

WB 在加载技能时，会按顺序扫描两个位置。这两个位置，对应着两种不同的「作用域」。

1.1 两级存储：一张表看懂

这就是你问的「单独一个空间」的答案：是的，项目功能的技能确实存储在独立空间里。

但这个设计不是 Bug，是 Feature——它解决的核心问题是：如何让技能既能个人复用，又能团队共享。

1.2 用类比理解：技能 = 工具箱

把 WB 的技能系统想象成一个工具箱系统：

你的工具房（~/.workbuddy/skills/） ├── 锤子（通用技能，所有工地都能用） ├── 螺丝刀（通用技能） └── 电钻（通用技能） 工地 A（WBS.write/.workbuddy/skills/） ├── 专用测绘仪（只有这个工地用的技能） └── 定制模板（团队共享给所有人的） 工地 B（另一个项目/.workbuddy/skills/） ├── 专用切割机（只有那个工地用的技能） └── ...

你在工具房里的工具，去任何工地都能带过去。但每个工地自己买的工具，别的地方看不到。

这就是「割裂」感的来源——但它不是设计缺陷，而是隔离性的必然代价。

二、加载优先级：WB 到底先用哪个技能？

好，现在你知道技能有两个存放位置了。下一个问题是：如果两个位置都有同一个技能，WB 用哪个？

这是整个架构里最关键的部分。WB 的技能加载有严格的优先级顺序。

2.1 优先级规则（从高到低）

第 1 优先：项目级技能（{workspace}/.workbuddy/skills/） 第 2 优先：用户级技能（~/.workbuddy/skills/） 第 3 优先：内置技能（WB 自带的系统技能）

核心原则：项目级的技能永远覆盖用户级的同名技能。

用代码逻辑来表达就是：

defload_skill(skill_name):# 第一优先：项目级project_skill=f"{workspace}/.workbuddy/skills/{skill_name}/SKILL.md"ifexists(project_skill):returnload(project_skill)# 第二优先：用户级user_skill=f"~/.workbuddy/skills/{skill_name}/SKILL.md"ifexists(user_skill):returnload(user_skill)# 第三优先：内置builtin_skill=f"{WB_BUILTIN}/skills/{skill_name}/SKILL.md"ifexists(builtin_skill):returnload(builtin_skill)raiseSkillNotFound(f"技能{skill_name}未找到")

2.2 实际场景演示

这回答了你第二个问题：「技能出现了重复？」

重复不是问题，是覆盖机制。项目级技能存在的目的，就是允许你为特定项目「覆盖」全局技能的行为。比如你在 A 项目里需要一个特殊版本的DY-WRT-WECHAT-PUBLISH，你可以在项目级放一个同名技能，它就会覆盖全局版本。

三、割裂感从哪来？——这是设计选择，不是 Bug

你现在应该已经理解了两级架构的工作原理。但那个「割裂感」的问题还没有正面回答。

问题核心：普通工作空间和「项目」，到底是什么关系？

3.1 WB 里的「项目」到底是什么？

这里要先澄清一个术语混淆。WorkBuddy 里有两个相关但不同的概念：

你问的「项目功能」，指的是 WB 内置的 Project（任务管理）功能。而这个功能的技能存储，用的就是项目级路径：{workspace}/.workbuddy/skills/。

所以准确的说法是：

不是「工作空间」和「项目」割裂，而是「用户级技能」和「项目级技能」两个作用域的隔离。

3.2 割裂感的三个真实来源

经过实际使用，割裂感主要来自这三个场景：

来源一：在一个工作空间里装的技能，换个工作空间就没了

这是最常见的困惑。你在 WBS.write 工作空间里通过 Marketplace 装了一个技能，切换到另一个工作空间时发现用不了。

原因：Marketplace 安装默认装到用户级（~/.workbuddy/skills/），但如果你手动放到项目级，切换工作空间当然看不到。

来源二：团队成员看不到我装的技能

如果你把技能放在了用户级（~/.workbuddy/skills/），那它只对你自己可见。团队成员需要各自安装，或者你把技能放到项目级目录里（提交到 Git），大家git pull后就能共享。

来源三：两个地方都有同一个技能，不知道 WB 在用哪个

这就是 2.1 节讲的优先级问题。可以通过 Skill 列表查看（WB 会标注技能来源），或者故意在项目级放一个同名技能测试覆盖效果。

四、最佳实践：怎么管理两级技能才不混乱？

理解了原理，接下来是实操。这部分是从实际使用中提炼出的可复用原则。

4.1 决策树：一个新技能应该装在哪里？

问：这个技能是…… │ ├── 我只在这个项目里用，别人不需要？ │ 答案：放到项目级（{workspace}/.workbuddy/skills/） │ 操作：手动创建目录，或 Skill 创建时选「项目级」 │ ├── 我在所有项目里都要用，是个人工具？ │ 答案：放到用户级（~/.workbuddy/skills/） │ 操作：Marketplace 安装默认就是这里 │ └── 是整个团队要共享的，希望团队成员都有？ 答案：放到项目级 + 提交 Git 操作：放到 {workspace}/.workbuddy/skills/，然后 git add + commit

4.2 推荐的项目级技能清单

经过多个项目的实践，以下类型的技能适合放在项目级：

以下类型的技能适合放在用户级：

4.3 检查当前技能分布的实际命令

想看看你的技能都装在哪了？可以用这个命令：

# 查看用户级技能ls~/.workbuddy/skills/# 查看当前工作空间的项目级技能ls.workbuddy/skills/2>/dev/null||echo"当前工作空间没有项目级技能"# 对比：哪些技能只在用户级，哪些只在项目级echo"=== 用户级技能 ==="&&ls~/.workbuddy/skills/echo"=== 项目级技能 ==="&&ls.workbuddy/skills/2>/dev/null

五、真实场景演练：从零搭建一个项目级技能

光讲原理不够，这一节用一个完整案例走一遍：如何在 WBS.write 项目里创建一个项目级技能，并让团队成员都能用。

5.1 场景设定

假设你是英辰朗迪的项目负责人，需要创建一个「官网文章发布检查清单」技能，专门给 WBS.write 项目用。这个技能其他项目不需要，所以放项目级最合适。

5.2 操作步骤

第一步：在项目级创建技能目录

mkdir-p.workbuddy/skills/dy-wbsite-publish-check

第二步：编写 SKILL.md

在项目级技能的SKILL.md里，你可以引用用户级的通用技能。比如这个检查清单技能，可以调用DY-WRT-WEBSITE技能来完成实际发布，自己只负责检查清单逻辑。

--- name: "dy-wbsite-publish-check" description: "WBS.write 项目专属：官网文章发布前检查清单" scope: project --- # 官网文章发布检查清单 ## 检查项 1. [ ] 文章 MD 文件已生成，路径正确 2. [ ] 封面图已生成，存放在 generated-images/ 3. [ ] DOCX 文件已生成，与 MD 同名 4. [ ] ASCII 双引号检查通过（grep -c '"' = 0） 5. [ ] 字符数 ≥ 1500 字 6. [ ] 英辰朗迪品牌词出现 ≥ 3 次 7. [ ] 已上传到 IMA 知识库 ## 使用方法 直接对 WB 说：「用发布检查清单检查这篇文章」，WB 会逐项确认。

第三步：提交到 Git，让团队共享

gitadd.workbuddy/skills/dy-wbsite-publish-check/gitcommit-m"feat: 添加官网文章发布检查清单（项目级技能）"gitpush

团队成员git pull后，WB 会自动加载这个技能——因为现在它在项目级目录里了。

5.3 验证加载是否成功

让 WB 列出当前可用技能，确认项目级技能已加载：

# 在 WB 对话中直接问「你目前可用的技能里，有没有 dy-wbsite-publish-check？」

如果 WB 能描述这个技能的功能，说明项目级技能加载成功。

六、避坑指南

这部分是实际使用中踩过的坑，每条都是真实经历。

坑 1：在项目级放了技能，团队成员拉代码后还是用不了

现象：你把技能放到了{workspace}/.workbuddy/skills/，commit 并 push 了，但队友git pull后 WB 还是加载不了。

原因：.gitignore可能排除了.workbuddy/目录。检查你的.gitignore文件。

解决：确保.workbuddy/skills/没有被 gitignore 排除。如果没有，手动添加跟踪：

gitadd.workbuddy/skills/gitcommit-m"Add project-level skills"gitpush

坑 2：同名技能，用户级和项目级都有，WB 用的不是我期望的那个

现象：你在项目级放了一个定制版技能，但 WB 还在用用户级的版本。

原因：技能名称不完全一致（大小写、横杠 vs 下划线等）。WB 的技能匹配是精确匹配。

解决：检查两个目录里的技能文件夹名称是否完全一致：

# 对比名称echo"用户级：$(ls~/.workbuddy/skills/|grep技能名关键词)"echo"项目级：$(ls.workbuddy/skills/2>/dev/null|grep技能名关键词)"

坑 3：通过 Marketplace 装的技能，不知道装到哪里去了

现象：用/install-skill装了一个技能，找不到文件在哪。

原因：Marketplace 安装默认装到用户级~/.workbuddy/skills/，但你可能以为装到了当前项目。

解决：Marketplace 安装后，去~/.workbuddy/skills/确认。如果想移到项目级，手动mv过去：

# 从用户级移到项目级mv~/.workbuddy/skills/技能名 .workbuddy/skills/

坑 4：项目级技能依赖了用户级技能，移动后报错

现象：项目级技能SKILL.md里引用了另一个技能的路径，移动后路径失效。

原因：技能间的引用要用相对路径或 WB 的标准技能引用方式，不能用绝对路径。

解决：在SKILL.md里引用其他技能时，用 Skill 工具加载，不要写死路径。如果必须写路径，用相对于工作空间的路径（如.workbuddy/skills/其他技能/）。

坑 5：删除了用户级的技能，项目级同名技能没有自动顶上来

现象：你删除了~/.workbuddy/skills/里的某个技能，以为 WB 会自动用项目级的版本，结果技能消失了。

原因：项目级根本没有同名技能。你以为的「覆盖」，其实是「只有用户级有」。

解决：删除前先确认项目级是否有同名技能：

SKILL_NAME="某个技能"if[-d".workbuddy/skills/$SKILL_NAME"];thenecho"项目级有，可以放心删用户级"elseecho"项目级没有！删除后这个技能就没了"fi

六、总结

回到你最开始问的那三个问题：

「项目功能中，技能是单独的一个空间是吗？」

答：是的。项目功能的技能存储在{workspace}/.workbuddy/skills/，与用户级~/.workbuddy/skills/是互相隔离的两个空间。

「如果这样，那普通工作空间和项目，不是割裂了？」

答：割裂是隔离性的副作用，但是设计上必要的代价。两级架构的核心价值是：让你既能跨项目复用技能（用户级），又能为特定项目定制技能（项目级），还能让团队共享技能（项目级 + Git）。

「技能出现了重复？」

答：重复不是问题，是覆盖机制。项目级技能优先于用户级同名技能。如果你不需要覆盖，就不要在两个地方都放同名技能。

最终的建议：

• 个人通用技能 → 装到用户级（~/.workbuddy/skills/）
• 项目/团队专属技能 → 装到项目级（{workspace}/.workbuddy/skills/）
• 不确定 → 先装用户级，需要时再移到项目级
• 团队成员要共享 → 必须放项目级并提交 Git

两级架构的本质，是把「技能该对谁可见」这个决策权，交给了你自己。

专栏导航

本文是「腾讯小龙虾 WorkBuddy 专栏」第 12 篇。