如何為 Claude Code 斜線指令加上旗標：4 種真正有效的模式

如何為 Claude Code 斜線指令加入旗標：4 種真正有效的做法

Claude Code 實際上並不會像你想的那樣為自訂斜線指令解析 --flags，但有四種做法能帶來相同的使用者體驗，其中三種甚至比 CLI 解析還要簡潔。以下是如何正確地為 Claude Code 斜線指令加入旗標，並附上今天就能直接複製使用的 .md 檔案。

快速解答：

• Claude Code 不會為自訂指令解析 CLI 旗標（--json、--verbose），因為根本沒有旗標解析器。
• 若想要 CLI 風格的使用者體驗，可將旗標寫入 $ARGUMENTS，讓 LLM 以自然語言方式解讀。
• 若需要帶型別的參數，可使用位置參數 $1/$2，或在 arguments: frontmatter 欄位中宣告具名參數。
• 在 argument-hint: 中記錄預期的旗標，這樣 / 自動完成功能就會將它們顯示給使用者。

Claude Code 斜線指令的參數實際上是如何運作的？

Claude Code 的 use 在將指令傳送給 LLM 之前，會替換三種 token：$ARGUMENTS（指令名稱後面的整個字串）、位置參數 $0/$1/$2（shell 風格的帶引號片段），以及在 frontmatter 中宣告的具名 $variableName。這裡沒有內建的 CLI flag 解析器，--dry-run 會作為純文字直接進入 $ARGUMENTS。

以下是讓所有人都會卡住的地方。當你輸入 /deploy --staging --dry-run 時，Claude Code 不會對 --staging --dry-run 執行 argparse。use 會將整個字串貼到你的 .md 檔案中引用 $ARGUMENTS 的位置，然後將渲染後的 prompt 傳送給模型。LLM 會將 --staging --dry-run 視為一般英文，並自行決定該如何處理。

這不是 bug，而是設計。use 是一個替換層，而非解析器。內建指令如 /clear 和 /help（參見官方 CLI 參考文件）確實有 flag，但你自行建立的自訂指令遵循的是不同的規則。

Claude Code 的 use 會替換 token，然後將渲染後的 prompt 交給 LLM。這裡沒有 flag 解析器。

在我們自己的 Claude Code 工作中，最常見的困惑正是這個——開發者花了一個小時試圖搞清楚為什麼 --verbose「沒有被偵測到」，最後才發現 LLM 本身就是解析器。截至 Claude Code v2.1.126（2026 年 5 月），此行為已記載於官方斜線指令文件中，短期內不會改變。斜線指令與 Claude Code hooks 是同級的基礎原語，兩者都在擴展 use，但指令由使用者輸入觸發，而 hooks 由工具事件觸發。

以下是能證明替換模型的最小自訂指令：

---
description: Echo whatever the user types after the command
argument-hint: [anything]
---

The user passed these arguments: $ARGUMENTS

Repeat them back verbatim, then describe what the user probably meant.

將其儲存為 .claude/commands/echo-args.md，輸入 /echo-args hello world --foo，LLM 就會看到字面字串 hello world --foo 被替換進 prompt 中。這就是整個心智模型。若要更深入了解指令檔案與更廣泛的 skills 系統之間的關係，請參閱我們的 Skills 入門指南。

五分鐘打造你的第一個參數化斜線指令

建立 .claude/commands/greet.md，內容為三行 frontmatter，以及一行參照 $ARGUMENTS 的提示詞。重新啟動 Claude Code，輸入 /greet World，你會看到 World 在 LLM 讀取之前就替換進了提示詞裡。整個流程就是這樣，五個步驟，不需要任何建置工具。

以下是完整的步驟：

1. 建立目錄。 在專案根目錄下執行 mkdir -p .claude/commands。.claude/ 資料夾與你的程式碼並存，其中的指令會在 Claude Code 啟動工作階段時自動被發現。
2. 撰寫指令檔案。 將下方的程式碼片段儲存為 .claude/commands/greet.md。
3. 重新載入工作階段。 結束並重新啟動 Claude Code（如果你的版本支援，也可以執行 /reload）。指令只會在每場工作階段開始時讀取一次。
4. 呼叫指令。 在對話中輸入 /greet World。
5. 確認替換結果。 開啟對話記錄，確認 LLM 看到的是已插入提示詞主體的 World，而非字面上的 $ARGUMENTS 符記。

以下是完整的檔案內容：

---
description: Greet someone enthusiastically
argument-hint: <name>
---

You are a friendly assistant. Greet the person named "$ARGUMENTS" with one short, warm sentence. Then ask them what they're working on today.

以及終端機的互動過程：

> /greet World
Hey World, great to see you! What are you working on today?

就是這樣。你現在已經擁有一個參數化斜線指令了。argument-hint 欄位會讓 / 自動完成選單在你的指令旁顯示 <name>，小小的 UX 巧思，大大的效果。

如果 $ARGUMENTS 沒有被替換，十之八九是因為你打成了 $args 或 $ARGS——這個符記必須完全使用大寫。

這個符記區分大小寫，而且必須完全一致。$ARGUMENTS 才有效。$arguments、$args、$ARGS、${ARGUMENTS} 全都會無聲無息地失敗——它們會以字面文字的形式傳給 LLM，模型看到的只是一堆亂碼。在懷疑有更深层的問題之前，請先再三檢查拼寫。

哪些 Frontmatter 欄位控制引數處理？

五個 frontmatter 欄位決定了斜線命令如何處理引數：argument-hint（自動完成顯示的內容）、allowed-tools（命令可呼叫的工具）、arguments（命名引數宣告）、model（執行該命令的 Claude 版本），以及 disable-model-invocation（將命令鎖定為僅限使用者觸發）。它們幾乎涵蓋了你會需要的所有參數化模式。

以下是 Claude Code v2.1.x 自訂命令的完整 frontmatter 參考：

有兩個陷阱值得你貼在螢幕旁邊。首先，allowed-tools 是以空格分隔，而非逗號。寫成 Bash(git:*), Read, Edit 會悄無聲地導致白名單完全失效，因為解析器會把整串字串視為一個格式錯誤的項目。請使用 Bash(git:*) Read Edit。我們是踩過坑才學到這個教訓；想了解更多類似模式，請參閱我們關於設定檔慣例的 CLAUDE.md 最佳實踐。

其次，model: 欄位會覆寫使用者目前為該工作階段選取的模型。當命令的運算成本較低、你想強制讓它使用較小的模型版本時，這就很有用；請參閱我們的模型選擇指南，了解如何針對不同命令類型在 Opus 4.7 和 Sonnet 之間取捨。

disable-model-invocation: true 欄位是破壞性命令的安全防線。在 /deploy-prod 或 /drop-database 上設定它，其他代理就無法以程式化方式呼叫這些命令，只有真人在聊天室中輸入才能觸發它們。

你實際會用到的 4 種參數模式是什麼？

有四種模式涵蓋了大約 95% 的實際 Claude Code 斜線指令：（1）布林旗標，例如由 LLM 從 $ARGUMENTS 解析的 /deploy --dry-run；（2）數值旗標，例如從 $ARGUMENTS 擷取的 /test --filter auth；（3）必填位置參數＋選填旗標，例如混合使用 $1 與 $ARGUMENTS 的 /fix-issue 123 --priority high；以及**（4）嚴格型別位置參數**，例如使用 $0／$1／$2 的 /migrate-component SearchBar React Vue。

挑選符合你指令形態的那一種即可。以下提供每種模式各一份可運作的 .md 檔案。

模式一：布林旗標（--dry-run）

當你想要 CLI 旗標的操作體驗，而旗標只有開／關兩種狀態時，直接交給 LLM 在 $ARGUMENTS 裡偵測即可。不用寫解析邏輯，也不用費心處理位置參數，只要在提示詞中說明規則就好。

---
description: Deploy to staging or production
argument-hint: [--dry-run]
allowed-tools: Bash(git:*) Bash(npm:*) Read
---

Deploy the current branch to staging.

Arguments passed: $ARGUMENTS

If "$ARGUMENTS" contains "--dry-run", DO NOT actually deploy. Instead, print the deployment plan: which files would change, which env vars would be set, and which commands would run. Stop after printing the plan.

Otherwise, proceed with the real deployment using `git push staging main` and `npm run deploy:staging`.

輸入 /deploy --dry-run，LLM 看到旗標後會列出計畫，然後停下。輸入 /deploy，它就直接部署上線。使用者完全沒做任何解析，所有工作都由 LLM 完成——而這正是它最擅長的事。

模式 2：帶值旗標（--filter <pattern>）

概念相同，但這次旗標會攜帶一個值。LLM 會從 $ARGUMENTS 中讀取 --filter auth，並使用其後的子字串。

---
description: Run the test suite, optionally filtered
argument-hint: [--filter <pattern>]
allowed-tools: Bash(npm:*) Read
---

Run the project's test suite.

Arguments: $ARGUMENTS

If "$ARGUMENTS" contains "--filter <pattern>", run only tests matching <pattern>. Use `npm test -- --grep <pattern>` for the actual command.

If no `--filter` is present, run the full suite with `npm test`.

Report pass/fail counts at the end.

/test --filter auth 只會執行 auth 相關的測試，/test 則會執行全部測試。LLM 能可靠地擷取 --filter 之後的模式，因為 Claude 確實很擅長這類結構化文字的擷取，遠比多數人預期的還要可靠。

模式 3：必填位置參數 + 選填旗標

這是我們在自己的指令庫中最常使用的混合模式。$1 承載必填參數，$ARGUMENTS 則承載全部內容（因此 LLM 仍能辨識選填旗標）。當有一個參數不可或缺、其餘皆為自由形式的上下文時，這是最簡潔的組合。

---
description: Fix a GitHub issue
argument-hint: <issue-number> [--priority high|medium|low] [context...]
allowed-tools: Bash(gh:*) Bash(git:*) Read Edit
---

Fix GitHub issue #$1.

Full arguments: $ARGUMENTS

Steps:
1. Run `gh issue view $1` to load the issue body.
2. Read the codebase to locate the relevant file(s).
3. If "$ARGUMENTS" contains "--priority high", create a hotfix branch off main. Otherwise branch off develop.
4. Apply the fix, run tests, and open a PR linked to the issue.

Anything else in $ARGUMENTS after the issue number is freeform context — fold it into your understanding of the bug.

呼叫方式如 /fix-issue 1234 --priority high the login form blanks the email field after a failed attempt。$1 會解析為 1234。$ARGUMENTS 則解析為整段尾隨字串，LLM 會欣然從中解析出優先順序旗標與自由形式的描述。

我們在 /fix-issue 指令中正是使用這種 $1 + $ARGUMENTS 組合，$1 用於議題編號，其餘則作為供 LLM 解析的自由形式上下文。在每日使用 Claude Code 的這一年裡，這是投資報酬率最高的模式。

模式 4：嚴格位置（Typed）

當所有參數都是必填、且順序很重要時，請完全捨棄 $ARGUMENTS。改用 $0/$1/$2（或透過 arguments: frontmatter 欄位使用具名參數），來建立明確、帶有型別的插槽。

---
description: Migrate a component between frameworks
argument-hint: <component> <from-framework> <to-framework>
arguments: [component, fromFramework, toFramework]
allowed-tools: Read Edit Write
---

Migrate the component named "$component" from $fromFramework to $toFramework.

1. Read the existing component file (search for `$component.{jsx,tsx,vue,svelte}`).
2. Translate the component idioms from $fromFramework to $toFramework: lifecycle methods, state handling, prop syntax, event binding.
3. Write the new file in the matching extension for $toFramework.
4. Print a diff summary at the end.

If $fromFramework or $toFramework is unsupported, abort and tell the user which frameworks ARE supported (React, Vue, Svelte, Solid).

呼叫方式為 /migrate-component SearchBar React Vue。具名參數的宣告讓自動補全與提示詞主體具備自我說明能力——任何閱讀 migrate-component.md 的人，都能一眼看出哪個插槽對應什麼。這個模式在處理三個以上必填參數的指令時特別出色。在 GitHub 上的 wshobson/commands 等社群函式庫中，也能看到這種風格。

布林旗標與數值旗標之所以有效，是因為 LLM 是一個彈性的解析器。嚴格位置之所以有效，是因為完全不需要 LLM 的智慧。將兩者混合使用，正是其中的秘訣。

什麼時候該用 $ARGUMENTS、位置參數還是命名參數？

當參數屬於 CLI 旗標風格、且你希望由 LLM 彈性解析時，使用 $ARGUMENTS。當參數有型別、有順序，且你希望完全不讓 LLM 產生歧義時，使用位置參數 $1/$2。當參數有 3 個以上，且自動完成中的清晰度比簡潔更重要時，使用命名參數 arguments:。以下是決策矩陣：

大多數開發者的直覺是先使用 $ARGUMENTS，因為它感覺最接近他們熟悉的 bash 世界。這對原型來說沒問題，但當契約穩定時，有型別的位置參數確實更好。LLM 不需要解析 $1，它本身就是一個乾淨的字串。

一個粗略的經驗法則：如果你能用一句英文描述該指令的簽章，且不使用「or」和「optionally」這兩個詞，就用位置參數。如果你需要用到這些詞，就用 $ARGUMENTS。

斜線指令現在跟 Skills 是一樣的東西嗎？

Anthropic 在 2026 年春季將自訂指令整合進更廣泛的 skills 系統，但 .claude/commands/*.md 檔案仍然可以使用，而且使用相同的 frontmatter。Skill 是一個目錄（.claude/skills/foo/SKILL.md 加上支援檔案），並提供額外的呼叫控制，例如 disable-model-invocation。Command 則是單一的 .md 檔案。替換規則相同，只是封裝方式不同。

以下是實際的差異：

所以不是的，.claude/commands/ 並沒有被棄用。Anthropic 在整合兩套系統時明確保留了檔案形式，因為有太多專案的指令庫已經固定在版本控制中。如果你需要支援檔案（例如 skill 載入的 CONTRIBUTING.md 參考資料，或是它會複製的 template.json），那就用 skills。否則繼續使用 commands 即可。

這次整合是朝向開放的 agentskills.io 標準推進的一部分，也是 v2.1.x 多項值得了解的變更之一，請參閱我們的 Claude Code v2.1 功能總覽以了解完整的功能版圖，以及我們的 skills 教學深入了解 skills 的用法。

為什麼我的 $ARGUMENTS 沒有被替換？常見錯誤修正

$ARGUMENTS 無法替換的五個常見原因：(1) 使用了小寫或簡寫 token（$args、$ARGS、$arguments，必須使用完整的 $ARGUMENTS），(2) 多字詞參數未加引號（/cmd hello world 會被拆分；/cmd "hello world" 則會視為一個整體），(3) allowed-tools 使用逗號分隔而非空格分隔，(4) 指令檔案未放在 .claude/commands/ 或 .claude/skills/ 中，(5) 編輯檔案後需要重新載入 Claude Code 工作階段。

$ARGUMENTS 原樣出現在 LLM 提示詞中

**症狀：**你的提示詞在模型回應中以純文字形式顯示出 $ARGUMENTS，就好像它被忽略了一樣。**成因：**大小寫錯誤或拼寫錯誤。這個 token 字面上就是 $ARGUMENTS，八個字元，全部大寫。**修正方式：**開啟 .md 檔，grep 搜尋 $args、$ARGS、$arguments、${ARGUMENTS}，並替換為 $ARGUMENTS。$args 這個拼寫錯誤的 bug，我們團隊每位開發者都至少踩過一次；它是「未知斜線指令」這一族問題中發生頻率最高的 bug。

多字詞引數被意外拆分

症狀： 你執行了 /migrate-component Search Bar React Vue，而 $1 是 Search，$2 是 Bar。原因： 空白字元會拆分位置引數。解法： 將多字詞引數加上引號：/migrate-component \"Search Bar\" React Vue。這樣 $1 就會是 Search Bar。這與 shell 的行為一致，也正是此用法刻意模擬的心智模型。

allowed-tools 未生效

症狀： 指令有執行，但 Claude 拒絕呼叫你以為已加入白名單的工具，或是呼叫了你未列出的工具。原因： 使用了逗號分隔，而非空格分隔。修正方式： 將 allowed-tools: Bash, Read, Edit 改為 allowed-tools: Bash Read Edit。工具子模式請使用 Bash(git:*) Bash(npm:*) Read 格式。

指令未出現在 / 自動完成選單中

**症狀：**你輸入 / 後，指令並未出現在清單中。**原因：**檔案位置錯誤、缺少 frontmatter，或 disable-model-invocation 設定不正確。**解決方式：**請確認檔案位於專案根目錄下的 .claude/commands/yourcmd.md（或 .claude/skills/yourcmd/SKILL.md）。確認 frontmatter 中至少包含 description: 欄位。如果你設定了 disable-model-invocation: true，該指令將不會對其他代理顯示，但仍會出現在使用者手動輸入 / 的選單中。

你編輯了 .md 檔案，但什麼都沒變

症狀： 你修好了 bug、存了檔、重新執行指令，結果行為還是一樣壞掉。原因： Claude Code 會在 session 開始時快取指令檔案。解法： 關閉並重新啟動 Claude Code，或者如果你的版本支援，可以執行 /reload。

Claude Code 會在 session 開始時讀取 .md 檔案。如果你編輯了某個指令卻「沒有變化」，在認定有更深层的 bug 之前，先重新啟動你的 session。

如果遇到這五種以外的邊緣情況，Claude Code 儲存庫的 issues 是最好的搜尋地點。我們見過的大多數奇怪的替換 bug，本質上都是上述某種情況的變形。

常見問題：Claude Code 斜線指令參數

如何傳遞參數給 Claude Code 的斜線指令？

在指令名稱後輸入參數字串即可：/greet World。在指令的 .md 檔案中，你可以使用 $ARGUMENTS（完整字串）、$1（第一個位置參數）或 $variableName（如果你在 frontmatter 中宣告了 arguments: [variableName]）來引用該值。系統會在將提示詞傳送至 LLM 之前自動替換這些 token。

Claude Code 中的 $ARGUMENTS 是什麼？

$ARGUMENTS 是自訂斜線指令檔案中的替換記號，Claude Code 會將其替換為使用者在指令名稱後輸入的完整參數字串。如果使用者執行 /deploy --staging --dry-run，那麼 $ARGUMENTS 就會在提示詞轉譯後、LLM 看到之前，成為字面字串 --staging --dry-run。

Claude Code 的斜線指令能接受像 --json 這樣的 CLI 風格旗標嗎？

原生並不支援，使用者自訂指令沒有旗標解析器。你將 --json 寫入 $ARGUMENTS，再由你的提示詞指示 LLM 偵測該旗標並據此執行對應行為。這之所以可行，是因為 Claude 本身是一個彈性的結構化文字解析器。內建指令如 /clear 和 /help 確實有真正的旗標，但你自行撰寫的自訂指令則完全遵循純替換規則。

Claude Code 中的 $1、$ARGUMENTS 和 $name 有什麼差別？

$1 是第一個以空白字元分隔的位置引數（$2 是第二個，以此類推）。$ARGUMENTS 則是完整的引數字串，原封不動地保留所有位置引數片段與任何旗標。$name 是在 frontmatter 的 arguments: [name] 欄位中宣告的具名引數，當你想要無須使用數字索引、就能自我說明的位置引數槽位時，會非常實用。

Claude Code 中的 argument-hint 如何運作？

argument-hint 是一個 frontmatter 欄位，用來控制 / 自動補全選單在指令名稱旁顯示的內容。設定 argument-hint: <issue-number> [--priority high] 後，使用者輸入 / 時便會精確顯示該範本。它僅涉及 UX 層面，不會驗證或剖析參數。但它仍然值得設定，因為這是你所能寫出成本最低的文件。

如何建立具有多個參數的自訂斜線指令？

有兩種乾淨的做法。位置型（positional）：在提示內容中引用 $1、$2、$3。命名型（named）：在 frontmatter 中宣告 arguments: [first, second, third]，然後引用 $first、$second、$third。當參數超過三個時，命名型的可讀性較佳。只有當你希望 LLM 解析必要位置欄位之後的自由格式尾端字串時，才使用 $ARGUMENTS。

.claude/commands/ 是否已棄用，改由 .claude/skills/ 取代？

並非如此。Anthropic 於 2026 年春季將兩套系統整併，但明確保留 .claude/commands/*.md 的運作，替換規則完全相同。單一檔案的自動化請使用 commands，多檔案的組合包（SKILL.md 加上範本或參考資料）則使用 skills。Frontmatter 相同，$ARGUMENTS 行為也相同，差異僅在封裝形式。自 v2.1.126 起，兩者皆為一等公民。

為什麼 $ARGUMENTS 沒有在我的指令中被替換？

最常見的三個原因，依發生頻率排序：大小寫錯誤（必須使用大寫 $ARGUMENTS，而非 $args 或 $arguments）、檔案位置錯誤（必須放在 .claude/commands/ 或 .claude/skills/ 目錄下）、或是工作階段過期（Claude Code 會在啟動時讀取指令檔，因此編輯後需要重新啟動）。如果以上三項都確認沒問題，請使用 H2 #1 中的最小範例執行 /echo-args foo 來隔離問題。

我可以要求必填某些參數嗎？

在使用層面來說，並沒有原生的必填參數驗證功能。常見的做法是在你的提示詞中指示 LLM：「如果 $1 為空，請停止並要求使用者提供 issue 編號。」由模型來把關這項約定。這並非萬無一失，但實務上對日常使用已足夠可靠，特別是搭配清楚的 argument-hint 時更是如此。

前言中的 model: 會覆蓋 CLI 旗標嗎？

是的，前言的優先順序更高。如果你的指令檔案中宣告了 model: claude-haiku-4，那麼無論使用者在該工作階段中選擇了哪個模型，該指令都會在 Haiku 上執行。這對於成本低廉、頻繁呼叫且你希望避免使用 Opus 的指令非常實用。請參閱我們的指南〈切換 Claude 模型〉，了解如何為不同類型的指令挑選合適的模型版本。

總結

四種模式。挑選適合你指令形式的那一種：

• 布林旗標（--dry-run），寫入 $ARGUMENTS，讓 LLM 偵測它。
• 值旗標（--filter <pattern>），同樣的做法，由 LLM 擷取值。
• 必填位置參數 + 選填旗標，$1 用於必要項，$ARGUMENTS 用於其餘部分。
• 嚴格位置參數，當每個欄位都是必填且有順序時，使用 $0/$1/$2（或透過 arguments: 命名）。

既然你的指令已具備參數化能力，下一步就是將它們串接進代理工作流程。從我們的 Claude Skills 教學 開始，了解多檔案打包升級；如果你正在比較各種工具框架，也可以瀏覽其他 AI 程式編寫工具。無論如何，你的 .claude/commands/ 資料夾剛剛變得更實用了。