Claude Codeのスラッシュコマンドを作る手順と設定ファイルの書き方

Claude Codeでスラッシュコマンドを作る最短手順

結論から言うと、.claude/commands/ にMarkdownファイルを1つ置けば、そのファイル名がそのままスラッシュコマンドになります。review.md を作れば /review で呼び出せる、という単純な仕組みです（2026年7月時点）。プラグインもビルド手順も不要で、ファイルに書いたプロンプトがそのまま送信される。Hooksや設定ファイルの編集に比べて、この手軽さが持ち味です。

コマンド定義ファイルを置くディレクトリと命名ルール

配置場所は2種類。プロジェクト直下の .claude/commands/ はリポジトリに含めてチーム共有でき、ホーム配下の ~/.claude/commands/ は自分専用です。ファイル名がコマンド名になるので、日本語や空白は避け、gen-pr.md のようなケバブケースが無難。サブディレクトリに置けばその名前が名前空間になり、整理と衝突回避に役立ちます。

Markdownに書いたプロンプトが呼び出されるまでの流れ

/gen-pr と入力すると、対応するMarkdownの本文がプロンプトへ展開されてClaudeに渡されます。要するにコマンドは「定型プロンプトのテンプレート」です。この仕組みを押さえておくと、後述する引数の埋め込みや、展開がブロックされる不具合の切り分けが一気に楽になります。

スラッシュコマンド設定ファイルの書き方と引数の渡し方

ファイルは、先頭のYAML frontmatterと、その下の本文（プロンプト）で構成します。frontmatterは省略できますが、実運用ではメタ情報と権限を明示しておくと事故が減ります。

frontmatterで指定できる項目と役割

よく使うのは次の4つです。

description：コマンド一覧に表示される説明文。
argument-hint：引数の入力例。補完のヒントになる。
allowed-tools：本文でシェルを実行する際に許可するツールを限定する。
model：そのコマンドだけ別モデルで走らせたいときに指定する。

とくに allowed-tools の指定漏れはハマりどころで、本文にコマンド実行を書いても許可されず止まります。設定ファイル全般の考え方はClaude Codeをカスタマイズする設定ファイルの書き方も参考になります。

ユーザー入力やファイル内容をコマンドに埋め込む記法

引数は $ARGUMENTS で全体を、$1 $2 で位置指定して受け取れます。@ファイルパス でファイル内容を差し込み、行頭の ! でシェル出力を埋め込めます。

---
description: 差分からPR説明を生成
argument-hint: [対象ブランチ]
allowed-tools: Bash(git diff:*)
---

現在の変更点: !`git diff main`

上記をもとに $ARGUMENTS 向けのPR説明文を書いてください。

プロジェクト共有用とユーザー個人用コマンドの使い分け基準

判断基準は「チーム全員に同じ挙動をさせたいか」の一点です。コミットメッセージ規約やレビュー観点のように成果物の品質を揃えたいものは、.claude/commands/ に置いてバージョン管理へ。自分だけのメモ整形やお気に入りの調べ物プロンプトは ~/.claude/commands/ に。ここを混ぜると、リポジトリに個人的なコマンドが漏れたり、共有すべき規約が自分の環境にしか無かったりと、属人化を招きます。EC-CUBEのように複数案件を並行で触る現場ほど、この線引きが効いてきます。

参考までに、筆者は個人用として ~/.claude/commands/ に8個のコマンドを運用しています。中でも重宝しているのがコミット用コマンドで、課題管理ツールの課題番号をコミットタイトルの先頭に自動で付けます。厄介なのは案件ごとに番号の書き方の規約が違う点で、ある案件では接頭辞を外して数字だけを付け、別の案件では課題キーをそのまま付ける、という分岐をコマンド定義1ファイルの中に書いて吸収しています。ほかにも、EC-CUBE4系でEntityに項目を追加したあとDocker内で php bin/console eccube:schema:update --dump-sql --force を実行してマイグレーションファイルを書かずに済ませるスキーマ更新用、前日のログを日次で見るログ点検用、改竄・マルウェア・不審ユーザーの有無を日次で確認するセキュリティ点検用、cherry-pickで作ったリリースブランチのコンフリクトを確認するリリース確認用など、いずれも自分の作業リズムに合わせたものなので個人用に置いています。

作ったコマンドが認識されない・展開されない時の原因切り分け

まず疑うのはファイルの場所と拡張子です。.md でない、commands のスペルミス、frontmatterのYAML破損（コロンの後の空白抜けなど）があると、コマンド一覧に出ないか、出ても本文が空扱いになります。/ を打った直後の候補に自作コマンドが並ぶか、まず目視で確認してください。

UserPromptExpansionで展開をブロックしてしまうケース

見落としやすいのがHooksとの干渉です。UserPromptExpansion はコマンドがプロンプトへ展開される直前に発火し、ここで展開を止められます。安全対策で入れたHookが特定パターンを弾いていると、コマンドは認識されているのに中身が届かない、という紛らわしい状態に陥ります。設定を疑う前に、Claude Code Hooksで開発作業を自動化する実践設定で導入したHookのブロック条件を確認するのが近道です。