Skills 发现与加载排障

Skill 不在列表中与 Skill 已发现但未触发是不同问题。先确认发现，再调整描述和任务匹配。

检查位置和深度

教程明确支持 Skill 根目录本身的 SKILL.md，或向下一层的 <skill-name>/SKILL.md；更深嵌套不被发现。推荐一个子目录对应一个 Skill，便于资源一起管理。

确认文件名严格为 SKILL.md。大小写敏感文件系统会忽略 skill.md、Skill.md 等不同名称。

检查 frontmatter

文件必须以 --- 开始，包含 name 和 description，并以单独一行 --- 结束元数据。教程说明前面存在标题、注释或空行都可能使文件静默跳过；不要把说明文字写到 frontmatter 之前。

显示名取自 name，不是目录。名称中的 : \ / < > * ? " | 会替换为连字符，查列表时需要考虑规范化后的名称。

检查信任

工作区 Skill 只在受信任工作区加载。教程提到旧 /trust，当前命令参考使用 /permissions trust [<directory-path>]；本页采用当前入口，按需重启或重载验证。用户范围 Skill 不受相同工作区条件限制。

检查覆盖和禁用

工作区优先于用户，用户优先于扩展，扩展优先于内置。同层 .agents/skills/ 优先于 .gemini/skills/。若两个位置用了同名，修改低优先级版本不会改变当前生效内容。

用 /skills list all 包含内置项目，检查是否被禁用；通过 enable 重新启用时注意默认 user 范围。

重载后仍不触发

/skills reload 或 /skills refresh 重新扫描。已出现在列表但模型不选择时，检查 description 是否准确表达任务和触发条件、是否与另一 Skill 高度重叠。activate_skill 由 Agent 调用，不能在 shell 直接运行同名命令替代发现机制。