Agent Skills
Gemini CLI Agent Skills 的用途：为特定任务加载专门能力、流程、约束和上下文。
Agent Skills 让 Gemini CLI 在特定任务上加载更具体的能力。它适合把重复流程、专门知识、脚本、模板和参考资料打包成可发现的能力。
Skill 是按需能力，不是项目常驻规则。长期项目背景放 GEMINI.md，重复但专门的任务流程才放 Skill。
它和 GEMINI.md 的区别很关键：GEMINI.md 是长期、常驻的项目背景；Skill 是按需激活的专门能力。这样可以避免把所有流程都塞进上下文，只有任务匹配时才加载 SKILL.md 和相关资源。
生命周期
Gemini CLI 的 Skill 流程分五步：
- 启动时扫描已启用 Skill，只把
name和description注入系统提示词。 - 模型判断当前任务是否匹配某个 Skill。
- 匹配后调用
activate_skill。 - 用户在 UI 中确认 Skill 名称、用途和目录访问范围。
- 通过后，
SKILL.md正文和目录结构进入会话，Skill 目录被加入允许读取路径。
这个机制叫 progressive disclosure。元数据常驻，正文按需加载，脚本、模板、参考资料只在需要时读取。
适合 Skill 的任务
- 代码审查。
- 文档生成。
- 测试修复。
- 迁移检查。
- 发布前 QA。
- 特定框架的固定流程。
不适合 Skill 的任务
- 一次性问题。
- 还没跑通的临时实验。
- 只有一句 prompt 就能解决的小任务。
- 含敏感凭据的流程。
| 需求 | 更适合 |
|---|---|
| 项目长期规则 | GEMINI.md |
| 重复任务入口 | Custom command |
| 专门流程 + 模板 + 脚本 | Agent Skill |
| 连接外部系统 | MCP / Extension |
| 临时一次性要求 | 当前 prompt |
发现层级
Gemini CLI 会按优先级发现 Skill：
- 内置 Skill。
- Extension 内携带的 Skill。
- 用户级：
~/.gemini/skills/或~/.agents/skills/。 - 工作区级：
.gemini/skills/或.agents/skills/。
同名时，高优先级位置覆盖低优先级位置。同一层级里，.agents/skills/ 优先于 .gemini/skills/。这点适合多 Agent 工具共用同一套 Skill：想兼容 Claude/Codex/Gemini，就优先考虑 .agents/skills/ 作为互操作入口。
常用管理命令
常用管理动作包括 list、install、link、uninstall、enable、disable。对应命令形如 gemini skills list、gemini skills install <source>、gemini skills link <path>、gemini skills uninstall <name>、gemini skills enable <name>、gemini skills disable <name>。
交互会话里也可以用 /skills list、/skills reload、/skills disable <name>、/skills enable <name> 管理。enable 和 disable 默认作用于 user scope；要管理工作区级 Skill，需要显式使用 workspace scope。
验收方式
新增或安装 Skill 后先运行 /skills list，确认名称、描述和 scope 正确。再用一个明确触发词发起任务，检查 Gemini CLI 是否弹出激活确认。如果没有触发，优先改 description，不要先往 SKILL.md 正文里加更多内容。
如果 Skill 被发现但不触发，通常不是正文不够长，而是描述没有写清“什么时候用”。先检查 name、description、scope、是否被 disable，再检查同名 Skill 是否被更高优先级位置覆盖。
接下来去哪
创建 Skills
继续看什么时候该新建 Skill，以及 SKILL.md 最小结构。
Custom commands
如果只是固定 slash command，不必升级成 Skill。
Extensions
需要分发 Skill、MCP、commands 时，继续看 extensions。