# Skills 发现与加载排障

> 定位信任、路径深度、frontmatter 和同名覆盖导致的缺失。

- 网址：https://funcoding.ai/agents/gemini-cli/build/skills-discovery/
- 核实日期：2026-10-08（命令、配置和价格以官方文档为准）
- 官方来源：[Gemini CLI 官方文档：Skills tutorial](https://geminicli.com/docs/cli/tutorials/skills-getting-started)、[Gemini CLI 官方文档：Agent Skills](https://geminicli.com/docs/cli/skills)、[Gemini CLI 官方文档：CLI commands](https://geminicli.com/docs/reference/commands)

---
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 直接运行同名命令替代发现机制。