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。