Custom commands
Gemini CLI custom commands：把重複任務沉澱成 slash command，使用者級、專案級和 extension 命令的使用邊界。
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。