---
title: "Custom commands"
description: "Gemini CLI custom commands：把重复任务沉淀成 slash command，用户级、项目级和 extension 命令的使用边界。"
verifiedAt: "2026-05-09"
---

Custom commands 用来把重复任务变成可调用的 slash command。官方 command reference 提到 `/commands list` 和 `/commands reload` 会从用户级、项目级、MCP prompts 和 extensions 重新加载命令。

> [!NOTE]
> **适合沉淀重复流程**：比如“跑 lint + typecheck + 总结失败”、“按项目规范审查 diff”、“生成 PR 描述”。

## 常用命令

```text
/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`，否则帮助菜单会从文件名生成说明。

```toml
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 命令测试确认弹窗显示的命令和预期一致，再放到真实项目里使用。

## 接下来去哪

<Cards>
  <Card title="Generation settings" description="命令稳定后，继续看什么时候才需要调整模型生成参数。" href="/docs/gemini-cli/official/02-context-config/25-generation-settings" />
  <Card title="Shell 命令" description="如果 command 内嵌 shell，回看 shell 执行和确认边界。" href="/docs/gemini-cli/official/01-cli-workflow/14-shell-commands" />
  <Card title="Extensions" description="需要把 commands 打包分发时，继续看 extensions。" href="/docs/gemini-cli/official/03-tools-mcp/38-extensions" />
</Cards>

## 官方来源

- [Gemini CLI custom commands](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/custom-commands.md)
