workbuddy 部署 skill 严格说不是“部署”，因为既没有编译，也没有服务要启动。技能本质是一个文件夹，里面放一份 SKILL.md，客户端启动时扫描目录、读 frontmatter、把描述挂进可用列表，任务对上了才加载。所以大家需要注意的只有三件事：放对位置、写对字段、描述能被匹配上。
Workbuddy Skill 目录结构
先看清楚要放什么。一个标准的技能目录长这样：
元数据文件有几套命名，分别对应不同的安装来源。走技能市场装的是市场元数据，手动导入生成的是 _user_meta.json，里面写着 name、installedAt 和 source 三个字段，source 的值为 userImport。这个字段能让你事后判断一个技能是怎么进来的。
叶子节点必须是 SKILL.md 这个文件名，大小写按原样。扫描器认两种布局：一种是每个技能一个子目录、目录里放 SKILL.md；另一种是目录下直接平铺 .md 文件。前者是标准写法，后者是兼容写法，正式做技能建议用前者，因为一个技能往往要带 references 目录。
三种安装方式怎么选
技能市场的入口在应用内，官方文档站 codebuddy.cn 也挂了技能相关章节，两边说法以产品内当期界面为准。
技能市场这条路最省事。点安装会弹一个确认框，写的是“该技能包将被下载并安装到本地技能目录”。如果本地已经有同名技能，会再问一次“是否使用下载的版本覆盖本地已有技能”，这一步别习惯性点确认，自己的改动会被盖掉。
导入技能这条路，桌面端的实现和“专家 → 技能 → 添加技能”是同一套代码。要点是必须选文件夹，不能选单个 md 文件。选错会直接报错，提示是“未选择文件夹”或“未选择任何技能文件”，本质原因是导入器要求来源必须是个目录。
手动放目录适合调试。它的好处是改完立刻能验证，坏处是没有任何校验，写错了不会有提示，只会静默不生效。
手动放目录为什么经常不生效
九成的手动安装失败都出在层级上。技能目录下必须是技能名这一层，再往里才是 SKILL.md。常见的错法是解压之后多套了一层，变成技能名/技能名/SKILL.md，扫描器在第二层找不到 SKILL.md 就跳过了，界面上什么都不会显示。
正确的层级只有两层：
- 第一层是技能名目录，建议用英文小写加连字符，和 frontmatter 里的 name 保持一致。
- 第二层是 SKILL.md，直接放在技能名目录里，不要再嵌套。
第二个高频坑是编码。SKILL.md 用 UTF-8 存，用系统记事本另存时容易带上 BOM，frontmatter 的第一个分隔符会解析失败，名称读不出来，技能就被当成无名条目丢掉。
第三个坑是 frontmatter 格式。分隔符必须是三条短横线单独占一行，开头结尾各一条，中间是键值对。少一条、多一条、或者写成了四条，解析都会失败。
frontmatter必须写对哪几个字段
三个字段里，description 的价值被严重低估。它不是给人看的简介，是给模型看的匹配信号。写法上要包含三样东西：这个技能做什么、什么场景该用它、什么场景不该用它。前两样决定能不能被选中，第三样决定会不会被滥用。
反面写法是“帮助处理文档”。正面写法接近“把 Excel 表按列汇总成月度报告，适用于财务与运营的周期性报表，不适用于单次数据清洗”。后者能匹配上具体任务，前者只能匹配上空气。
disable 这个字段要特别留意。有些技能在被停用或解绑时，会被自动写入 disable 为 true，这是设计上的正常行为。如果你曾经解绑过某个连接器又装回来，先看一眼这个字段是不是还留着 true。
项目技能和个人技能的区别
技能分两个作用域，很多人只用了其中一个。
- 我的技能：放在用户级目录，所有项目都能用。适合通用能力，比如写作框架、文档处理、代码审查。
- 项目技能：放在工作区内的 .workbuddy/skills 目录，只对这个项目生效。适合带项目私有信息的流程，比如某个客户的报表口径、某个仓库的发布步骤。
判断标准很简单：这个技能里有没有只对当前项目成立的信息。有，就放项目级；没有，放用户级，避免每开一个新项目都要重装一遍。项目级还有一个隐性好处，它跟着仓库走，团队拉代码时自动带上，不用口头传达。
安装失败的五种报错对应什么
| | |
|---|
| | |
| | |
| | 补 name 与 description，检查分隔线 |
| | |
| | 先移除再导，或改 frontmatter 的 name |
这五条覆盖了绝大多数情况。如果报错不在其中，先做一件最朴素的事：把 SKILL.md 用纯文本方式打开，从第一行读到第二行，确认三条短横线是标准的半角减号而不是中文全角符号。全角横线在视觉上几乎看不出来，但解析器一定认不出来。
部署skill的注意事项有哪些
- 别多套一层目录：技能名/SKILL.md 是标准层级，多套一层就静默失效。
- 文件名必须精确：SKILL.md，全大写加扩展名，改一个字母都扫不到。
- 保存为 UTF-8 无 BOM：带 BOM 会让 frontmatter 解析失败。
- 描述比正文重要：正文只在对上任务时才会被读，描述的匹配度决定一切。
- 核对 disable 字段：曾停用或解绑过的技能，重新启用前先看这个字段。
- 覆盖安装会丢改动：市场更新同名技能时，本地手改过的内容会被覆盖，自己的版本另存一份。
- 来源不明的技能要审一遍：技能正文会被读进上下文执行，等于给它一段可执行的指令权，装之前至少通读一遍，看有没有让它读敏感目录或外发数据的步骤。
- 项目技能会进仓库：放进工作区的技能会跟着代码一起提交，别把密钥、客户名单、内部地址写进 SKILL.md。
关于workbuddy部署skill的常见问题
Q：workbuddy 部署 skill 需要重启吗？
A：技能是启动时扫描目录的。手动放进去之后如果列表没出现，先重启客户端让它重新扫描。
Q：技能放在哪个目录？
A：用户级在 ~/.workbuddy/skills 下，项目级在当前工作区的 .workbuddy/skills 下，扫描器会递归进子目录。
Q：一个技能能不能带多个文件？
A：能。SKILL.md 之外可以带 references 目录放参考文档，正文里按需引用，不必全塞进主文件。
Q：为什么装了技能但用的时候没反应？
A：多数是 description 写得太泛，模型匹配不上。把适用场景和不适用的场景都写进描述里。
Q：市场安装和手动放目录有区别吗？
A：结果一样，都落到本地技能目录。区别在市场会做校验并写入来源元数据，手动放没有任何检查。
Q：同名技能会冲突吗？
A：会按名称去重，后加载的通常被跳过。改 frontmatter 的 name 比改目录名可靠。
Q：项目技能和我的技能能同名吗？ A：不建议。同名会让来源判断变模糊，排查问题时很难说清到底加载了哪一份。
Q：能不能先禁用但不删掉？
A：能。frontmatter 里把 disable 写成 true 就会跳过加载，想恢复改回 false 或删掉这一行。
Q：怎么彻底删掉一个技能？
A：从已安装列表里卸载会移除目录；手动删的话，删掉整个技能名目录，不要只删 SKILL.md。
workbuddy 部署 skill 这件事的门槛不在技术，在细节。目录少套一层、文件名写准、描述写具体，三条做到了，剩下都是复制粘贴。真要出错，先看报错原文，那几句话基本已经把原因说完了。
AI 速览
