Custom commands
Gemini CLI custom commands：把重复任务沉淀成 slash command，用户级、项目级和 extension 命令的使用边界。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| Custom commands | 自定义命令 | 把常用流程做成可调命令。 |
| 参数 | args | 命令的输入参数。 |
| 复用 | reuse | 团队共享自定义命令。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你把一个常用流程做成可复用的 Gemini CLI 自定义命令。
你是 Gemini CLI 自定义命令创建顾问。
【角色】
Gemini CLI 自定义命令创建顾问，按最小够用、安全优先的原则给可落地方案，每条结论都落到能照做的步骤或示例，不停留在空泛建议。
【输入】
- 想做成命令的常用流程：___
- 触发场景和频率：___
- 是否需要参数：___
- 个人用还是团队共享：___
- 现有的手动做法：___
【工作流程】
1. 判断流程是否值得做成命令
2. 设计命令结构和参数
3. 写清触发和用法
4. 处理团队共享和命名
5. 给调用和验证
【输出规范】
▌一、是否值得做成命令
▌二、命令结构 + 参数
▌三、触发与用法
▌四、共享 + 验证
【硬约束】
- 流程没跑稳先别急着固化
- 参数设计清晰，避免歧义
- 团队共享注意命名冲突
- 不要替我臆测情况或编造不存在的配置项，信息不全先问清
- 不确定的配置或字段一律以官方文档为准，禁止照搬过时写法Custom commands 用来把重复任务变成可调用的 slash command。官方 command reference 提到 /commands list 和 /commands reload 会从用户级、项目级、MCP prompts 和 extensions 重新加载命令。
适合沉淀重复流程：比如“跑 lint + typecheck + 总结失败”、“按项目规范审查 diff”、“生成 PR 描述”。
常用命令
/commands list
/commands reload文件位置和覆盖关系
| 层级 | 适合内容 |
|---|---|
| 用户级 | ~/.gemini/commands/，你所有项目通用的个人命令 |
| 项目级 | <project>/.gemini/commands/，只适合当前项目的任务 |
| extension | 随扩展分发的命令 |
同名命令冲突时，项目级命令覆盖用户级命令。命令名来自文件路径：~/.gemini/commands/test.toml 会变成 /test，<project>/.gemini/commands/git/commit.toml 会变成 /git:commit。
TOML 结构
命令文件必须是 .toml。最小字段只有 prompt，推荐补 description，否则帮助菜单会从文件名生成说明。
description = "Summarize staged changes and propose a commit message."
prompt = """
Read the staged diff and write one Conventional Commit message.
Diff:
!{git diff --staged}
"""这个例子会在执行前显示实际 shell 命令并要求确认。失败时，命令输出和退出码会注入 prompt，模型能看到失败原因。
参数和注入
{{args}}：把用户在 slash command 后输入的参数注入 prompt。!{...}：执行 shell 命令并注入输出；其中的{{args}}会被 shell escaping。@{path}：注入文件内容或目录内容，支持文本，也支持部分多模态文件；会尊重.gitignore/.geminiignore。
如果 prompt 里没有 {{args}}，但用户仍传了参数，Gemini CLI 会把完整命令追加到 prompt 末尾。要做稳定工作流，建议显式使用 {{args}}，并在 prompt 里定义输入格式和输出格式。
写作原则
- 命令名短而明确。
- 只做一类任务。
- 输入和输出要固定。
- 不把密钥写进命令。
- 涉及写操作、删除、发布时保留确认步骤。
- 涉及复杂 shell 时，优先调用仓库脚本，不在 TOML 里堆长命令。
执行顺序和安全检查
官方 custom commands 的解析顺序是先处理 @{...} 文件注入，再处理 !{...} shell 注入，最后处理 {{args}} 参数替换。这个顺序会影响排错：如果命令失败，要先确认文件路径能读到，再确认 shell 命令能执行，最后才看参数有没有被正确替换。
!{...} 不是静默执行。Gemini CLI 会在执行 shell 前展示最终命令并请求确认；使用 {{args}} 放进 shell 时，参数会被 shell escaping，降低命令注入风险。教程里展示含 shell 的 command 时，不要只给 TOML，还要说明确认弹窗里应该看到什么。
项目命令覆盖用户命令。团队教程建议把项目命令放在 <project>/.gemini/commands/ 并进入版本管理；个人命令放 ~/.gemini/commands/，不要混进团队仓库。
适合沉淀的命令
适合沉淀的是“每周都要做、流程固定、验收固定”的任务，例如 /review:diff、/git:commit、/qa:release、/docs:sync。不适合沉淀的是一次性探索、临时 debug、依赖个人本机路径的命令。
| 候选任务 | 是否做成 command | 判断依据 |
|---|---|---|
| 每次 PR 都要审查 staged diff | 是 | 输入、输出、验证标准固定 |
| 临时排查一次依赖冲突 | 否 | 过程不稳定，沉淀后很快过期 |
| 发布前固定 QA 清单 | 是 | 复用频率高，遗漏成本高 |
| 读取个人 Downloads 某个路径 | 否 | 依赖本机路径，不适合共享 |
项目级 command 应该尽量调用仓库已有脚本，而不是把复杂 shell 直接写进 TOML。这样脚本可以单独测试，command 只负责把任务说明、输入和输出格式固定下来。
命令命名要考虑未来扩展。比如 /review 很快会变成泛用入口，不如一开始拆成 /review:diff、/review:security、/review:release。namespace 来自目录结构，路径分隔符会被转换成冒号，所以目录设计本身就是命令体系设计。
验收方式
新增或修改命令后执行 /commands reload，再用 /commands list 确认命令名、namespace 和描述正确。对包含 !{...} 的命令，先用只读 shell 命令测试确认弹窗显示的命令和预期一致，再放到真实项目里使用。
接下来去哪
Generation settings
命令稳定后，继续看什么时候才需要调整模型生成参数。
Shell 命令
如果 command 内嵌 shell，回看 shell 执行和确认边界。
Extensions
需要把 commands 打包分发时，继续看 extensions。