Skill 跨 agent 会静默失效

更新于 2026-08-27

**「磁盘上有」≠「本 session 能用」。** 技能目录存在、软链也在，但 agent 的 `available_skills` 里没有它 —— 这不是没装，而是**加载阶段整体跳过**，且不报错。

一、静默失效的根因：frontmatter 不兼容

同一个 SKILL.md 在不同 agent 里的解析规则不同。写入了某家专属字段（如 tools / argument-hint / user-invocable），别的 agent 解析 frontmatter 失败，处理方式是整个跳过该 skill，而不是忽略未知字段、降级加载。

排查顺序（先证伪再改）：

确认文件/软链确实在目标 agent 的 skills 目录下；
对比同目录下能正常加载的 skill（如 grill-me）的 frontmatter —— 差异字段就是嫌疑；
删掉非通用字段，重启 agent 再看 available_skills。

二、第二个坑：skill 内部路径写死到某个 agent 的目录

SKILL.md 里 SCRIPT=~/.claude/skills/<x>/scripts/... 这种绝对路径，一旦 skill 被分发到别的 agent 目录，路径就断了 —— 即使加载成功也跑不起来。

规则：skill 要共享，内部引用就必须相对自身目录（或由运行时注入），不能硬编码到某一个 agent 的配置目录。

三、为什么会同时踩两个坑：集中分发放大了兼容性

技能由 skillhub 集中管理（~/.skillshub/ 是仓库，各 agent 的 skills 目录里放软链指向它），一份技能同时挂在多个 agent 下。

好处是改一处全体生效；代价是任何一处兼容性问题会被复制到所有 agent，而且第一个暴露它的往往是「平时不用的那个 agent」。所以新增/迁移 skill 时，要在每个接入的 agent 里各验证一次加载，而不是只测写它的那家。