出海数字营销宝典 Logo
出海数字营销宝典evaoo.com

WorkBuddy Skill 架构解析:插件注册、上下文隔离与动态调度

2026-11-06智见AI-大鹏 @zjp1997720约 22 分钟阅读

作者:智见AI-大鹏 @zjp1997720•发布日期:2026-08-31•WorkBuddy 架构机制拆解

WorkBuddy Skill 机制拆解:从 How 到 WhyWorkBuddy Skill 机制拆解:从 How 到 Why

最近我组建了一个小团队分担交付工作。团队成员统一使用 WorkBuddy(暂未全员订阅 Codex),我也教大家在里面编写自己的 Skill。

创建 Skill 本身并不难。WorkBuddy 内置了 skill-creator 技能(即用 Skill 来创建 Skill)。只要把需求描述清楚,就能生成可用的 Skill,团队成员很快掌握了这一步。

创建完成后,大家陆续遇到了下面四个问题:

“我创建的 Skill 存在哪了?”

“为什么新建了一个项目,之前的 Skill 就不见了?”

“Skill 管理里‘我安装的’这一长串,都是哪来的?”

“这些 Skill 要怎么维护?会自动更新吗?改过的会被覆盖吗?”

团队里几位成员先后都卡在了同一批问题上。

大家已经掌握了创建、安装和调用的操作步骤(What 和 How),缺少的是对运行机制(Why)的了解:Skill 在磁盘上如何存储,WorkBuddy 如何扫描加载它,以及不同来源的 Skill 如何更新维护。

本文拆解的四个机制

本文将从本地目录结构与系统提示词层面,依次说明四个问题:Skill 的文件结构、作用域存储路径、五类安装来源以及版本维护规则。搞清这套机制后,你就能看懂技能列表里每一项的来龙去脉。

WorkBuddy 架构图解WorkBuddy 架构图解


一、Skill 的文件结构:一个文件夹与一份给 AI 读的文档

要搞清存储和加载规则,先看 Skill 在磁盘上的真实文件形态。

打开本地用户级技能目录 ~/.workbuddy/skills/,任选一个技能文件夹点进去,里面通常包含以下目录结构:

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

Skill 目录结构图解Skill 目录结构图解

SKILL.md 是技能的主文件,分为两部分:

  • 顶部的 YAML 元数据:只有两个必填字段,分别是 name(技能名称)和 description(触发条件说明)。
  • Markdown 正文:详细说明这类任务的执行步骤与规范。

因此,SKILL.md 本质上是一份写给 AI 阅读的操作指南,本身无需编译,也不要求你编写代码。它的运行流程分为三步:模型在对话中检查当前任务,发现匹配某个技能的 description 后读取该文档正文,再按文档步骤执行任务。

SKILL.md 规范拆解SKILL.md 规范拆解

在这两部分中,description 字段直接决定技能能否触发。

每次对话启动时,系统只会把所有技能的 name 和 description 放进上下文,命中后才按需读取 SKILL.md 正文。这意味着模型完全依据 description 判断是否调用该技能。

编写 description 的关键原则

技能能否准确触发,一半取决于这段描述。你既要写清触发场景(例如“当用户要求写周报时使用”),也要划清排除边界(例如“不用于日记或月报”)。有些技能安装后从未触发,九成是因为这段描述边界不清。

此外,SKILL.md 遵循开放规范 agentskills.io,Claude Code、Codex 和 Cursor 的技能都采用同一格式。WorkBuddy 与腾讯开发者工具 CodeBuddy 同源,你在本地文件里还能看到这一渊源,例如部分内置技能创建脚本的默认路径仍保留着 .codebuddy/。

一个文件夹、一份 Markdown 文档和一套开放规范,构成了 Skill 的全部文件基础。


二、存储路径与作用域:为什么切换项目后找不到之前的 Skill

下面解答团队里最高频的疑问:创建的 Skill 存在哪里,为什么切换项目后就看不到了。

WorkBuddy 在系统提示词模板中为自建技能划分了两个作用域:

层级物理存储路径生效范围与生命周期
用户级~/.workbuddy/skills/本机所有项目通用,跨工作空间可见
项目级<项目目录>/.workbuddy/skills/仅在当前项目生效,随项目文件夹与 Git 仓库同步

用户级路径用户级路径

项目级路径项目级路径

新建项目后找不到旧技能的原因就在这张表里:那个技能当时创建在了项目级目录。文件并没有丢失,仍保存在旧项目的 .workbuddy/skills/ 文件夹中,只是它的作用域不覆盖新项目。

用两行只读命令查看本地技能存放位置

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

创建新技能时该如何选择层级?WorkBuddy 内置的 skill-creator 给出了明确原则:拿不准时优先放进用户级目录。

在团队协作场景下则反过来用:把需要全员统一执行的技能放进项目级目录,随代码仓库一起提交。新成员克隆项目并打开 WorkBuddy 后,即可自动加载团队共享的作业规范。

第三层目录:.agents/skills/ 跨 Agent 互操作

这是社区正在普及的跨 Agent 互操作目录约定。Codex 将其作为原生主目录,Cursor、GitHub Copilot 和 VS Code 也均已支持读取该路径。正如社区总结的那样:“The spec unified us. The paths divided us.”(规范统一了格式,路径却各自独立)。

如果你同时使用多款工具,可以把技能库集中存放在一处,再通过软链接(Symlink) 映射到各工具的读取目录(例如将 ~/.workbuddy/skills/ 软链接指向统一维护的 .claude/skills/)。各工具目录只作读取入口,真实文件集中维护一份即可。

跨 Agent 互操作软链接图解跨 Agent 互操作软链接图解

WorkBuddy Skill 作用域与存储路径查询器

三、“我安装的”列表拆解:五类磁盘来源与自动检索机制

打开 Skill 管理界面的“我安装的”列表,里面往往有几十个技能(例如测试机上显示 94 个),其中不少你并没有手动安装过。

“我安装的”实际上是一个聚合视图:只要某个技能当前能被 WorkBuddy 调用,界面就会把它列出来。它们在磁盘上主要来自以下五类路径:

插件缓存路径插件缓存路径

市场安装路径市场安装路径

  1. 自建与同步导入

存放在 ~/.workbuddy/skills/ 或项目目录,包含 AI 创建、手动导入和软链接接入的技能。

  1. 内置插件自带(18 个 skill-* 内置插件)

存放在 ~/.workbuddy/plugins/cache/workbuddy-builtin/<plugin>/<version>/,例如 skill-creator、skill-marketplace-skill-installer 和 skill-expert-manager。

  1. 技能市场手动安装

存放在 ~/.workbuddy/skills/<skill-name>/,目录内附带来源标记文件(_skillhub_meta.json 或 _knot_meta.json)。

  1. 外部插件附带的嵌套技能

存放在 ~/.workbuddy/plugins/cache/<marketplace>/<plugin>/<version>/skills/。安装某个第三方功能插件时,它包含的子技能也会一并注册。

  1. 连接器自带的技能

存放在 ~/.workbuddy/connectors/skills/(例如 fbs-connector)。

外部插件目录外部插件目录

连接器技能目录连接器技能目录

来源存储路径识别特征维护与更新规则
自建 / 手动导入~/.workbuddy/skills/本地目录,AI 创建时带 agent_created: true本地自行控制,修改后立即生效
跨 Agent 同步上述目录中的软链接执行 readlink 可查看真实源路径修改源目录文件,多工具同步生效
内置插件技能.../workbuddy-builtin/.../version/workbuddySeedManaged: true随客户端更新覆盖,复制到用户级目录再改
市场技能~/.workbuddy/skills/<name>/_skillhub_meta.json / _knot_meta.json自动更新;本地修改后受 userModified 保护
外部插件技能.../plugins/cache/.../skills/随插件清单分发随所属插件版本同步更新

系统提示词中的自动检索规则:find-skills

WorkBuddy 应用包内的系统提示词模板(workbuddy-prompt.tpl)写入了一条硬性规则:“当你遇到做不了的事(操作邮件、日历、备忘录或系统自动化),第一个动作必须是调用 find-skills 去技能市场搜索;确认没有合适技能才允许说做不了。”

因此你的技能列表会随使用过程自动增加:一部分是你主动安装的,另一部分是 AI 在执行任务途中按需从技能市场检索并安装的。

find-skills 提示词模板find-skills 提示词模板

按需加载机制按需加载机制


四、日常维护机制:元数据标记与执行后复盘

当本地技能数量增多后,修改后是否会被更新覆盖、AI 生成技能与市场技能如何区分管理,都由目录内的元数据标记文件控制。

agent_created 标记agent_created 标记

userModified 保护机制userModified 保护机制

AI 创建的技能:agent_created 标记

由 Agent 生成的技能自带 agent_created: true 标记,表明该文件由 AI 生成,允许后续在对话中由 AI 安全修改。

市场技能:userModified 防覆盖保护

只要你在 WorkBuddy 中编辑过市场安装的技能,系统就会写入 userModified: true。后续市场自动更新时不会直接覆盖,会先弹窗征求你的确认。

内置维护机制:系统提示词常驻复盘指令

“端到端使用 Skill 后必须复盘,检查是否有可由 Skill 修正的问题;存在明确优化项时说明建议,并询问是否修改。”

这条指令把复盘检查变成了 AI 的固定动作。每次完整调用一个 Skill 后,AI 都会自动排查步骤缺陷并提出修改建议。

复盘机制复盘机制

技能提炼开关技能提炼开关

Skill 与系统规则(Rules)的分工界限

Skill 按需加载,系统规则常驻生效。 全局通用的要求(如复盘准则、交付格式)写进系统规则;特定场景的操作流程(如写周报、清洗数据)封装为 Skill。

技能复盘与迭代机制技能复盘与迭代机制


五、实践工作流:四步编写高质量自建 Skill

1

先和 AI 一起把真实任务完整跑通一遍

先在真实任务中收集一手记录,明确哪一步容易出错、验收标准是什么。跳过实操直接凭空编写的文档往往难以稳定运行。

2

任务跑通后,让 AI 提炼最短执行路径

把刚才跑通的过程交给 AI 提炼,删掉中途试错的弯路,只保留验证可行的确定性步骤。

3

人工核对触发条件(写清 description 边界)

向 AI 明确说明“什么时候触发、什么时候不触发”。划清调用边界这一步必须由你亲自把关。

4

选对存储作用域,并打开 SKILL.md 核对正文

个人通用技能放入用户级目录,团队共用规范放入项目级目录。最后打开生成的 SKILL.md 检查一遍描述与步骤。

工作流实践总结工作流实践总结


六、下一步排查与整理建议

你可以按以下三步整理当前机器上的 WorkBuddy 技能目录:

  • 排查现有目录:在终端运行 ls ~/.workbuddy/skills/,区分手动创建的技能与市场安装的技能。
  • 迁移错放的通用技能:把误存在旧项目 .workbuddy/skills/ 下的个人通用技能移入用户级目录,解决切换项目后找不到的问题。
  • 补全触发边界:打开常用自建技能的 SKILL.md,在 description 字段补全触发词与排除场景。

团队协作建议:用项目级目录共享业务规范

在团队协作项目中,可以将验证成熟的工作流放入项目根目录的 .workbuddy/skills/ 并提交至 Git 仓库。新成员拉取仓库即可直接复用同一套作业规范,不会因人员流动而丢失经验。

作者:智见AI-大鹏(@zjp1997720),原文详述了 WorkBuddy 的系统提示词拼装、技能目录加载规则与插件分发机制。

WorkBuddy 进阶

觉得本文有启发?一键复制标准引用摘要

自带原文归因链接与核心摘要,可直接粘贴至团队飞书/Slack 知识库、技术周报或大模型上下文。