《WorkBuddy Skill 机制拆解｜从 How 到 Why，万字干货》

最近我组了个小团队来帮我分担交付压力。作为一个 AI native 团队，我让团队的小伙伴都用上了 WorkBuddy（全员上 Codex 暂时还用不起），也教他们怎么在里面自己设计 Skill。

创建这件事本身不难。WorkBuddy 内置了一个叫 skill-creator 的技能——对，用 Skill 来创建 Skill。只要能把需求说清楚，就能创建出一个不错的 Skill。这一步，大家很快就都过了。

但创建完之后，问题才真正开始：

这些问题不是一个人问的。团队里几个小伙伴，前后撞的是同一批墙。

我后来想明白了：他们不是不会用。创建会用，安装会用，调用也会用——What 和 How 都有了，缺的是 Why。Skill 在这个软件里怎么存在、怎么被找到、怎么被加载、怎么被管理，这套机制没人讲过。

一、Skill 到底是什么：一个文件夹，一份 AI 自己会去读的文档

先校准概念。这一节不解决具体问题，但后面三个答案都建立在它上面。

打开你磁盘上的技能目录（用户级的在 ~/.workbuddy/skills/，怎么找到它下一节讲），随便挑一个技能进去看。你不会看到代码。你会看到一个文件夹，里面躺着一到几个 Markdown 文档：

skill-name/
├── SKILL.md          ← 必需，技能本体
├── scripts/          ← 可选，可执行脚本
├── references/       ← 可选，参考文档
└── assets/           ← 可选，模板等资产文件

SKILL.md 是技能的本体，分两段：

• 开头一段 YAML 元数据：只有两样东西是必需的：name（叫什么）和 description（什么时候用我）。
• 正文是方法论：写清楚「这类任务怎么做」。

所以 Skill 主文件的准确定义是：一份写给 AI 读的方法论文档。它不运行，不编译，不需要你会任何编程。工作过程是：模型在对话中判断当前任务匹配了某个技能的 description，就去读这份文档，然后按照文档里的方法做事。

两段结构里，description 值得单独停一下。

系统每次对话只会把所有技能的「名字+描述」放进上下文，正文要等真正用到时才读取。这是按需加载。这带来一个直接推论：模型是凭 description 决定要不要唤醒这个技能的。

还有一层背景值得知道：SKILL.md 不是 WorkBuddy 的私有格式，它是一个开放标准（agentskills.io 规范）。Claude、Codex、Cursor 这些工具的技能，用的都是同一套格式。WorkBuddy 的技能格式和腾讯的开发者工具 CodeBuddy 完全同源。你会在文件层不断看到这个血脉痕迹——比如它的技能创建脚本里，默认路径还写着 .codebuddy/。

一个文件夹，一份文档，一个开放标准。这就是 Skill 的全部物质基础。

二、放在哪、为什么换项目就找不到：作用域，不是丢件

现在回答团队里被问得最多的问题：我创建的 Skill 存哪了？为什么换个项目就不见了？

WorkBuddy 给自建技能留了两个作用域，这是系统提示词模板里明文写的：

「为什么新建项目后技能不见了」的答案就在这张表里：那个技能当时被创建到了项目级目录。它没有丢，就躺在旧项目的 .workbuddy/skills/ 文件夹里，只是作用域不覆盖新项目。

ls ~/.workbuddy/skills/ | head -20        # 查看你的用户级技能库
ls <项目目录>/.workbuddy/skills/ 2>/dev/null   # 查看当前项目的专属技能

那创建的时候，技能会被放进哪一层？WorkBuddy 内置的 skill-creator 给了明确的判断原则：拿不准就放用户级。

这个原则反过来读，就是团队分发的正确姿势：把需要全员一致的技能放进项目级目录，让它随代码仓库走。新人 clone 项目、打开 WorkBuddy，老员工沉淀的方法论自动就在了。

三、「我安装的」那一长串从哪来：分清入口、来源和落点

第三个问题最普遍也最隐蔽。打开 Skill 管理的「我安装的」列表，里面几十个技能（我这台机器显示 94 个），很多你压根没印象装过。

「我安装的」是一个聚合视图：只要当前能被 WorkBuddy 调用，界面就把它列进来。它的磁盘来源至少有五类：

四、怎么维护：一套生命周期标记体系与复盘闭环

技能多了之后的维护——改了会不会被覆盖、AI 创建的和市场装的能不能混着管、团队怎么统一升级——答案藏在文件层的一套标记体系里。

五、从 Why 回到 How：一条被机制校准过的四步工作流

六、收个尾：工具会换，机制认知跟着你走

回到开头。团队小伙伴的四个问题，现在都有了机制层的答案：

• Skill 是什么：一份给 AI 读的方法论文档；
• 存放在哪：两层作用域和多个插件缓存，入口决定在何处出现；
• 从哪来：多个来源的聚合，还会被 find-skills 悄悄在干活时自动补齐；
• 怎么维护：一套标记体系，高级形态是在使用中强制复盘、由人决定进化。