导读 本文围绕「AI 技能匹配失效四个坑」做一手实测与机制拆解，含完整步骤、适用边界与避坑清单。
凌晨三点多，我把一个图像生成技能装进了 WorkBuddy。终端显示 37 个文件、5 份说明文档、22 个脚本语法全过，技能列表里也确实多了那一行。我当时觉得这事完了。
第二天随口说了句「生张图」，跳出来的是内置工具，不是刚装的那个。
我以为装坏了。翻了一圈，文件没少，密钥没写错，开关也开着。后来才明白，问题不在装没装好，而在叫不叫得动。
装完还有一条路要走
技能落盘之后，后面还串着几步：注册、索引、会话加载、触发词匹配。任何一环断了，表面现象都长得一样，你说话，它没反应。
安装文件 → 资产注册 → 索引扫描 → 会话加载 → 触发词匹配
我当时只做了第一格。下面把四个坑按踩到的顺序摊开。
坑一 文件放对了，注册没做
仓库文件我是直接复制进 skills 目录的。省事，也确实能跑：显式点名调用技能，完整文档立刻返回。
但官方导入会多做一步，把技能登记进资产表、生成启用记录。这步被我跳过了。所以缓存里那个 disable=false 只是扫描器补的默认值，不代表系统真的认了它。
查法很简单：
Get-Content ~/.workbuddy/.skill-list-cache.json -Raw | ConvertFrom-Json
看 results 里有没有这个技能，有没有对应的 overrideKey。再打开 unified-asset/local-assets.json，我那天的 skills 是个空对象。专家、连接器都有登记，唯独技能一个没有。
结论有点反直觉：能手动加载，不等于完成了安装。
坑二 当前会话不会重刷
官方文档写得很直白，已经加载进当前会话的技能在本会话内还能用，新发起的会话才会完全生效。
反过来同样成立，会话中途装的东西，不一定进当前这个会话的匹配池。前一天晚上我还根据「列表里能看到」下了个无需重启的结论，隔天就被打脸。
改法简单到有点亏：新开一个任务再测。
坑三 套件被当成一个技能
这个仓库是四个子技能打包在一起的：
agnes-flash-suite-skills/ ├── SKILL.md 只这一份进了索引 ├── agnes-3.0-flash/SKILL.md ├── agnes-2.5-flash/SKILL.md ├── agnes-2.5-image-flash/SKILL.md └── agnes-2.5-video-flash/SKILL.md
浅层扫描只认根目录那一份。于是我在界面里搜 agnes-2.5-image-flash，什么都没有；按子技能名召唤，也找不到。四个能力挤在同一个条目底下，各自没有独立的开关。
想让它们各自可匹配，就按 README 里的第二种方式，把四个子目录分别提到 skills 顶层，每个都带自己的 SKILL.md。
坑四 触发词撞了车
所以越通用的词，越轮不到你。要么点名：
/agnes-2.5-image-flash
要么在提示里写全称，别只说两个字。
我最后怎么修的
把手抄的那套文件整个删掉，打成 zip，走侧边栏「添加技能 → 上传技能」重新导入，再新开一个任务测。装完目录里多出一个 _user_meta.json，资产表也终于有了记录。
有个后续坑值得记一笔：仓库 zip 里只有 .env.example，不带 .env。官方导入完不补密钥，生图照样跑不起来。我把 Key 补进根目录 .env，收紧成仅当前用户可读，再跑一次文生图，看见返回图片链接，才敢说这事结束。
下次装完先做这五步
- 显式点名调用一次。能返回完整文档，说明文件没问题，往下查。
- 看资产表的 skills 是不是空的。空的就别折腾配置，直接重传。
- 新开一个任务再测自动匹配，别在当前会话里反复试。
- 索引里只出现一条、子技能搜不到，就是套件嵌套，拆成顶层目录。
- 通用触发词没反应，先点名召唤，再考虑是不是被内置工具截了胡。
收尾
这回最花时间的不是修，是一开始把「列表里看得见」当成了「能用」。这俩不是一回事。以后装完技能，我会先新开一个任务点名喊一次，确认有回应，再开始写东西。
你装技能时卡在哪一步，留言说说，我挑高频的再拆一期。
如果觉得有帮助，欢迎关注我的公众号，持续输出 AI 与安全方向的技术拆解。
