---
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="/zh-Hant/docs/gemini-cli/official/02-context-config/25-generation-settings" />
  <Card title="Shell 命令" description="如果 command 內嵌 shell，回看 shell 執行和確認邊界。" href="/zh-Hant/docs/gemini-cli/official/01-cli-workflow/14-shell-commands" />
  <Card title="Extensions" description="需要把 commands 打包分發時，繼續看 extensions。" href="/zh-Hant/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)
