Claude Code のスラッシュコマンドにフラグを追加する方法：実際に使える4つのパターン

Claude Code のスラッシュコマンドにフラグを追加する方法:実際に機能する 4 つのパターン

Claude Code は実際には、カスタムスラッシュコマンドに対して期待されるような方法では --flags を解析しません。しかし、同じ UX を実現する 4 つのパターンがあり、そのうちの 3 つは CLI 解析よりもクリーンです。ここでは、Claude Code のスラッシュコマンドにフラグを適切に追加する方法を、今日すぐにコピーして使える動作確認済みの .md ファイルとともに紹介します。

簡潔な回答:

• Claude Code はカスタムコマンドの CLI フラグ(--json、--verbose)を解析しません。このツールにはフラグパーサーがないためです。
• CLI 風の UX を実現するには、フラグを $ARGUMENTS に記述し、LLM に自然言語として解釈させます。
• 型付きの引数には、位置引数の $1/$2、または arguments: frontmatter フィールドで宣言する名前付き引数を使用します。
• 想定されるフラグは argument-hint: に記載しておくことで、/ のオートコンプリートでユーザーに表示されます。

Claude Code のスラッシュコマンドの引数は実際にはどう動くのか？

Claude Code の仕組みは、コマンドを LLM に送信する前に 3 種類のトークンを置換します。$ARGUMENTS（コマンド名の後に続く文字列全体）、位置指定の $0/$1/$2（シェル形式の引用符付きセグメント）、そして frontmatter で宣言された名前付きの $variableName です。組み込みの CLI フラグパーサーは存在せず、--dry-run はリテラルテキストとしてそのまま $ARGUMENTS に入ります。

ここが誰もが引っかかるポイントです。/deploy --staging --dry-run と入力しても、Claude Code は --staging --dry-run に対して argparse を実行しません。この仕組みは、その文字列全体を .md ファイル内で $ARGUMENTS を参照している箇所に貼り付け、レンダリング済みのプロンプトをモデルへ送信します。LLM は --staging --dry-run をただの英語として受け取り、どうするかを判断します。

これはバグではなく、設計です。この仕組みは置換レイヤーであり、パーサーではありません。/clear や /help といった組み込みコマンド（公式 CLI リファレンスを参照）には確かにフラグがありますが、自分で作成するカスタムコマンドには別のルールが適用されます。

Claude Code の仕組みはトークンを置換し、レンダリング済みのプロンプトを LLM に渡します。フラグパーサーは存在しません。

私たち自身の Claude Code の作業でも、最もよくある混乱はまさにこれで、開発者は LLM こそがパーサーだと気づく前に、なぜ --verbose が「検出されない」のかを解明するのに 1 時間も費やしたりします。Claude Code v2.1.126（2026 年 5 月）の時点で、この動作は公式のスラッシュコマンドドキュメントに記載されており、当面変わることはありません。スラッシュコマンドは Claude Code フックと兄弟関係にあるプリミティブで、どちらもこの仕組みを拡張しますが、コマンドがユーザー入力でトリガーされるのに対し、フックはツールイベントでトリガーされます。

この置換モデルを証明する、最小限のカスタムコマンドがこちらです。

---
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 がプロンプト内に置換された形で届きます。これがメンタルモデルの全体です。コマンドファイルがより広範なスキルシステムとどう関係しているかをさらに詳しく知りたい方は、私たちの Skills 入門をご覧ください。

5分で初めてのパラメトリックスラッシュコマンドを作ろう

3行のフロントマターと、$ARGUMENTS を参照する1行のプロンプトを記述した .claude/commands/greet.md を作成します。Claude Codeを再起動して /greet World と入力すると、LLMに渡される前に World がプロンプト内に置き換えられる様子が確認できます。これで全工程は完了、5ステップ、ビルドツールは不要です。

以下がエンドツーエンドのレシピです：

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 が置換されない場合、10回中9回は $args や $ARGS と入力したことが原因です。このトークンは大文字のリテラルです。

トークンは大文字小文字を区別し、完全に一致しなければなりません。$ARGUMENTS は機能します。$arguments、$args、$ARGS、${ARGUMENTS} はすべてサイレントに失敗し、リテラルテキストとしてLLMに送信されるため、モデルには意味不明な文字列として認識されます。より深いバグを疑う前に、スペルを何度も確認してください。

どのフロントマターフィールドが引数処理を制御するのか？

スラッシュコマンドが引数をどのように処理するかは、5つのフロントマターフィールドによって決まります。argument-hint（オートコンプリートに表示される内容）、allowed-tools（コマンドが呼び出せるもの）、arguments（名前付き引数の宣言）、model（どの Claude バリアントで実行するか）、そして disable-model-invocation（コマンドをユーザー専用の呼び出しに固定する）です。これらを組み合わせれば、必要なパラメータパターンはほぼすべてカバーできます。

以下が、Claude Code v2.1.x のカスタムコマンド用フロントマターの完全なリファレンスです。

モニターに貼ってでも覚えておきたい落とし穴が2つあります。まず、allowed-tools はスペース区切りであり、カンマ区切りではありません。Bash(git:*), Read, Edit と書くと、何もホワイトリストに登録されず、エラーも出ずに失敗します。パーサーが文字列全体を1つの不正なエントリとして扱ってしまうためです。Bash(git:*) Read Edit を使用してください。私たちはこれを痛い目で学びました。同様のパターンについては、設定ファイルの規約に関するCLAUDE.md ベストプラクティスをご覧ください。

2つ目は、model: フィールドは、ユーザーが現在のセッションで選択しているモデルを上書きするという点です。コマンドの計算コストが低く、より小さなバリアントで強制的に実行したい場合に便利です。コマンドの種類に応じて Opus 4.7 と Sonnet のどちらを選ぶかについては、モデル選択に関するガイドをご覧ください。

disable-model-invocation: true フィールドは、破壊的なコマンドに対する安全策です。/deploy-prod や /drop-database に設定しておけば、他のエージェントがそれらのコマンドをプログラムから呼び出すことはできなくなり、チャットに入力した人間だけがトリガーできるようになります。

実際に使う4つの引数パターンとは？

4つのパターンで、実際の Claude Code スラッシュコマンドの約95%をカバーできます。(1) ブール型フラグ（/deploy --dry-run のように、LLM が $ARGUMENTS から解析するもの）、(2) 値付きフラグ（/test --filter auth のように、$ARGUMENTS から抽出するもの）、(3) 必須の位置指定引数 + 任意のフラグ（/fix-issue 123 --priority high のように、$1 と $ARGUMENTS を併用するもの）、そして (4) 厳密に型指定された位置指定引数（/migrate-component SearchBar React Vue のように、$0/$1/$2 を使うもの）です。

コマンドの形に合ったものを選んでください。それぞれについて、動作する .md ファイルを以下に示します。

パターン1: ブーリアンフラグ（--dry-run）

CLIフラグ的なUXが欲しい場合で、そのフラグが単なるオン/オフであるときは、$ARGUMENTS の中からそれを検出する処理をLLMに任せましょう。パース処理も、位置引数のやりくりも不要です。ただ、そのルールをプロンプトの中で説明するだけで済みます。

---
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が担っています。これこそ、まさに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 は任意のフラグも検出できます）。1つの引数が絶対に必要で、残りが自由形式のコンテキストである場合、これが最もクリーンな組み合わせです。

---
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 が解析する自由形式のコンテキスト用です。1年間にわたる Claude Code の日常的な使用を通じて、これが最も投資対効果の高いパターンでした。

パターン4: 厳密な位置指定（型付き）

すべての引数が必須で順序が重要な場合は、$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 を読む人なら誰でも、どのスロットが何を指すか一目で分かります。このパターンは、必須引数が3つ以上あるコマンドで真価を発揮します。GitHub の wshobson/commands のようなコミュニティライブラリでも、このスタイルが見られます。

真偽値フラグや値付きフラグが機能するのは、LLM が柔軟なパーサーだからです。厳密な位置指定が機能するのは、LLM の知能を一切必要としないからです。この2つを組み合わせることこそが秘訣です。

$ARGUMENTS、位置指定、名前付きはいつ使い分けるべきか？

引数がCLIフラグ形式で、LLMによる柔軟なパースを望む場合は $ARGUMENTS を使います。引数が型付けされ、順序が決まっており、LLMの曖昧さをゼロにしたい場合は位置指定の $1/$2 を使います。引数が3つ以上あり、簡潔さよりもオートコンプリートでの明確さを重視する場合は名前付きの arguments: を使います。以下がその判断マトリクスです：

多くの開発者が最初に $ARGUMENTS に手を伸ばすのは、それが慣れ親しんだbashの世界に最も近く感じられるからです。プロトタイプならそれでも構いませんが、コントラクトが安定している場合は、型付きの位置指定の方が本当に優れています。LLMは $1 をパースする必要がなく、すでにクリーンな文字列になっているからです。

大まかな経験則：コマンドのシグネチャを「または」「任意で」という言葉を使わずに一文で説明できるなら、位置指定を選びましょう。それらの言葉が必要な場合は $ARGUMENTS を選びましょう。

スラッシュコマンドはスキルと同じものになったのか？

Anthropic は 2026 年春にカスタムコマンドをより広範なスキルシステムに統合しましたが、.claude/commands/*.md ファイルは引き続き動作し、同じフロントマターを使用します。スキルとはディレクトリ（.claude/skills/foo/SKILL.md と補助ファイル）であり、disable-model-invocation のような追加の起動制御を備えています。コマンドは単一の .md ファイルです。置換ルールは同じで、パッケージングが異なります。

実用上の違いは次のとおりです。

つまり、.claude/commands/ は非推奨ではありません。Anthropic はシステムを統合した際、ファイル形式の動作を明示的に維持しました。バージョン管理にコマンドライブラリを固定しているプロジェクトが多すぎるためです。補助ファイル（スキルが読み込む CONTRIBUTING.md リファレンスや、コピーする template.json など）が必要な場合はスキルを使いましょう。そうでなければコマンドのままにしておいて問題ありません。

この統合は、オープンな agentskills.io 標準に向けたより大きな流れの一環であり、知っておく価値のある v2.1.x の変更点のひとつです。機能の全体像については Claude Code v2.1 の機能まとめ を、スキルの詳しい解説については スキルチュートリアル をご覧ください。

$ARGUMENTS が置換されないのはなぜ？よくあるバグの修正

$ARGUMENTS が置換されないよくある5つの理由：(1) 小文字または短縮形のトークンを使っている（$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 がプレーンテキストとしてそのまま表示され、まるで無視されたかのように見える。 原因: 大文字小文字の誤り、またはスペルミス。このトークンは正確には $ARGUMENTS、8文字、すべて大文字である。 修正: .md を開き、$args、$ARGS、$arguments、${ARGUMENTS} を grep で検索し、$ARGUMENTS に置き換える。$args のタイプミスによるバグは、チームの開発者全員が少なくとも一度は経験しており、「未知のスラッシュコマンド」系統のバグの中で最も発生件数が多い。

複数語の引数が予期せず分割される

症状: /migrate-component Search Bar React Vue を実行すると、$1 は Search、$2 は Bar になります。原因: 空白文字により位置引数が分割されます。修正: 複数語の引数を引用符で囲みます: /migrate-component \"Search Bar\" React Vue。これで $1 は Search Bar になります。これはシェルの挙動と一致しており、use が意図的に模倣しているメンタルモデルです。

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 ファイルを編集したのに何も変わらない

症状: バグを修正してファイルを保存し、コマンドを再実行しても、同じ壊れた挙動のまま。原因: Claude Code はセッション開始時にコマンドファイルをキャッシュします。対処法: Claude Code を終了して再起動するか、/reload に対応しているバージョンの場合はそれを実行してください。

Claude Code はセッション開始時に .md ファイルを読み込みます。コマンドを編集して「変わらない」と感じたら、より深いバグを疑う前にセッションを再起動してください。

これら 5 つに当てはまらないエッジケースについては、Claude Code リポジトリの Issues で検索するのが最適です。私たちが目にしてきた奇妙な置換バグのほとんどは、上記のいずれかの変種です。

よくある質問：Claude Code のスラッシュコマンド引数

Claude Code のスラッシュコマンドに引数を渡すには？

コマンド名の後に引数の文字列を入力します。例：/greet World。コマンドの .md ファイル内では、その値を $ARGUMENTS（文字列全体）、$1（1番目の位置引数）、または $variableName（frontmatter で arguments: [variableName] を宣言している場合）として参照できます。このトークンは、プロンプトを LLM に送信する前に置換されます。

Claude Codeにおける$ARGUMENTSとは？

$ARGUMENTSは、カスタムスラッシュコマンドファイル内で使用される置換トークンで、コマンド名の後にユーザーが入力した引数文字列全体に置き換えられます。ユーザーが/deploy --staging --dry-runを実行した場合、LLMに渡される前のレンダリング済みプロンプト内で、$ARGUMENTSはリテラル文字列の--staging --dry-runになります。

Claude Code のスラッシュコマンドは --json のような CLI 形式のフラグを受け取れますか？

ネイティブではサポートされていません。use にはカスタムコマンド用のフラグパーサーがありません。--json を $ARGUMENTS に書き込み、それを検出して適切に振る舞うよう LLM に指示するプロンプトを記述します。これが機能するのは、Claude が構造化テキストの柔軟なパーサーだからです。/clear や /help といった組み込みコマンドには実際のフラグがありますが、作成したカスタムコマンドは置換のみのルールに従います。

Claude Code の $1、$ARGUMENTS、$name の違いは何ですか？

$1 は最初の空白区切りの位置引数です（$2 は2番目、以降同様）。$ARGUMENTS は引数文字列全体をそのまま保持し、すべての位置引数とフラグを含みます。$name は frontmatter の arguments: [name] フィールドで宣言される名前付き引数で、番号によるインデックス指定をせずに自己説明的な位置スロットを使いたい場合に便利です。

Claude Code では argument-hint はどのように機能しますか？

argument-hint は、/ のオートコンプリートメニューでコマンド名の横に表示される内容を制御するフロントマターフィールドです。argument-hint: <issue-number> [--priority high] を設定すると、ユーザーが / を入力した直後に、まさにそのテンプレートが表示されます。これは UX 専用の機能であり、引数の検証や解析は行いません。それでも設定する価値があります。なぜなら、これほど手軽に書けるドキュメントは他にないからです。

複数の引数を持つカスタムスラッシュコマンドを作成するには？

2つのスマートな方法があります。位置引数の場合：プロンプト本文内で $1、$2、$3 を参照します。名前付き引数の場合：フロントマターで arguments: [first, second, third] を宣言し、$first、$second、$third を参照します。引数が3つ以上ある場合は、名前付きの方が可読性が高くなります。$ARGUMENTS は、必須の位置引数スロットの後に自由形式の末尾文字列をLLMに解析させたい場合のみ使用してください。

.claude/commands/ は .claude/skills/ に取って代わられ、非推奨となったのか？

いいえ。Anthropic は 2026 年春にこの 2 つのシステムを統合しましたが、.claude/commands/*.md についても同じ置換ルールで引き続き動作することを明示的に保証しています。単一ファイルの自動化には commands を、複数ファイルで構成するバンドル（SKILL.md にテンプレートやリファレンスを加えたもの）には skills を使用してください。frontmatter も $ARGUMENTS の挙動も同一で、異なるのはパッケージングの形態だけです。v2.1.126 の時点では、どちらも第一級の機能として位置づけられています。

コマンド内で $ARGUMENTS が置換されないのはなぜ？

発生頻度の高い順に、主な原因は3つです。大文字・小文字の誤り（$args や $arguments ではなく、大文字の $ARGUMENTS でなければなりません）、ファイルの配置場所の誤り（.claude/commands/ または .claude/skills/ に配置する必要があります）、または古いセッション（Claude Code はセッション開始時にコマンドファイルを読み込むため、編集後は再起動してください）。これら3つすべてに問題がなければ、H2 #1 の最小限の例を使って /echo-args foo を実行し、問題を切り分けてください。

特定の引数を必須にできますか？

使用レベルではできません。ネイティブの必須引数バリデーションは存在しません。よくあるパターンは、プロンプト内で LLM に指示することです。「$1 が空の場合は処理を止め、ユーザーにイシュー番号を指定するよう伝えてください」といった具合です。この契約を強制するのはモデルの役割です。万全ではありませんが、実際には日常的な用途で十分に信頼できるレベルであり、特に明確な argument-hint と組み合わせると効果的です。

frontmatter の model: は CLI フラグを上書きしますか？

はい、frontmatter が優先されます。コマンドファイルで model: claude-haiku-4 を宣言している場合、そのコマンドはユーザーがセッションでどのモデルを選択していても、Haiku で実行されます。これは、Opus で実行したくない、低コストで頻繁に呼び出されるコマンドに便利です。コマンドの種類ごとに適切なバリアントを選ぶ方法については、Claude モデルの切り替えに関するガイドをご覧ください。

まとめ

4つのパターンがあります。コマンドの形に合ったものを選んでください。

• 真偽値フラグ（--dry-run）は $ARGUMENTS に書き込み、LLM に検出させます。
• 値付きフラグ（--filter <pattern>）も同じアプローチで、LLM が値を抽出します。
• 必須の位置引数 + 任意のフラグは、必須のものに $1、残りに $ARGUMENTS を使います。
• 厳密な位置引数は、すべてのスロットが必須かつ順序を持つ場合、$0/$1/$2（または arguments: による名前指定）を使います。

コマンドがパラメータ化されたら、次はそれらをエージェントのワークフローに組み込む番です。まずは Claude Skills チュートリアル で複数ファイルのパッケージ化へのアップグレードから始めるか、ハーネスを比較しているなら 代替 AI コーディングツール をご覧ください。いずれにせよ、あなたの .claude/commands/ フォルダはぐっと便利になったはずです。