Gemini CLI 的自定义命令功能让你把最常用的 Prompt 保存为 /命令名 格式的快捷指令：在 ~/.gemini/commands/ 或项目 .gemini/commands/ 下创建 .toml 文件，支持 参数注入、!{shell命令} 动态执行和 @{文件路径} 内容注入。本页是完整的自定义命令创建指南。

自定义命令

自定义命令让你把常用的 Prompt 保存为个人快捷指令，在任何项目中直接用 /命令名 调用，省去每次重新输入相同 Prompt 的麻烦。

命令文件位置与优先级

位置	路径	范围
用户命令（全局）	~/.gemini/commands/	所有项目可用
项目命令（本地）	<项目根目录>/.gemini/commands/	仅当前项目，可提交到 git

同名命令时，项目命令优先级更高，可以覆盖全局命令。

命令命名与命名空间

• 文件路径决定命令名：commands/test.toml → /test
• 子目录创建命名空间，目录分隔符转为冒号：
  • commands/git/commit.toml → /git:commit
  • commands/refactor/pure.toml → /refactor:pure

修改 .toml 文件后，用 /commands reload 热重载，无需重启 CLI。

TOML 文件格式

# 必填：发送给模型的完整 Prompt
prompt = "请分析当前代码库中的安全漏洞，重点关注认证和输入验证。"

# 可选：在 /help 菜单中显示的描述
description = "安全审计：扫描认证和输入验证漏洞"

参数注入（）

直接注入

在 Prompt 主体中使用 ，用户输入的参数原样替换占位符：

# /git:fix "按钮对齐错误"
description = "为指定问题生成修复代码"
prompt = "请为以下问题提供代码修复：{{args}}。"

模型收到：请为以下问题提供代码修复："按钮对齐错误"。

Shell 命令中的安全注入

在 !{...} 块内使用 时，参数会自动 Shell 转义，防止命令注入：

prompt = """
请总结以下搜索结果，模式：`{{args}}`

搜索结果：
!{grep -r {{args}} .}
"""

运行 /search-code It's complicated 时， 在 Shell 命令中被转义为 "It\'s complicated"，确保安全执行。

执行 Shell 命令（!{...}）

用 !{命令} 语法在 Prompt 中动态注入 Shell 命令的输出：

# /git:commit
description = "根据暂存改动生成提交信息"
prompt = """
请根据以下 git diff 生成一条 Conventional Commit 格式的提交信息：

```diff
!{git diff --staged}

"""

运行 `/git:commit` 时，CLI 先执行 `git diff --staged`，把输出注入 Prompt，再发送给模型。

**安全提示**：执行 Shell 命令前会出现确认对话框，显示将要执行的具体命令，确认后才执行。

## 注入文件内容（`@{...}`）

用 `@{路径}` 语法把文件内容直接嵌入 Prompt：

```toml
# /review FileCommandLoader.ts
description = "按最佳实践指南审查代码"
prompt = """
你是资深代码审查员。请审查 {{args}}，参照以下最佳实践：

@{docs/best-practices.md}
"""

• @{path/to/file.txt} → 文件内容
• @{path/to/dir/} → 目录下所有文件内容
• 支持图片、PDF 等多模态文件
• 文件注入在 Shell 命令和参数替换之前处理

示例：创建全局重构命令

1. 创建目录和文件：

macOS/Linux：

mkdir -p ~/.gemini/commands/refactor
touch ~/.gemini/commands/refactor/pure.toml

Windows PowerShell：

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini\commands\refactor"
New-Item -ItemType File -Force -Path "$env:USERPROFILE\.gemini\commands\refactor\pure.toml"

2. 写入命令定义：

# ~/.gemini/commands/refactor/pure.toml
# 调用方式：/refactor:pure

description = "将当前上下文的代码重构为纯函数"

prompt = """
请分析我提供的代码，将其重构为纯函数。

你的回答应包含：
1. 重构后的纯函数代码块
2. 关键改动及其原因的简要说明
"""

3. 使用命令：

> @my-messy-function.js
> /refactor:pure

下一步

• 了解更多项目级规范设置：GEMINI.md 上下文文件
• 探索 Skills 系统实现更复杂的工作流：Skills 工作流

常见问题

Q: 自定义命令支持多行 Prompt 吗？

A: 完全支持。TOML 使用三重引号 """...""" 语法定义多行字符串，参见上面的示例。

Q: 修改命令文件后需要重启吗？

A: 不需要，在 CLI 中运行 /commands reload 即可热重载所有命令文件。

Q: 命令名可以包含中文吗？

A: 技术上可以，但建议使用英文加冒号分隔的命名空间格式，方便跨系统使用和团队共享。