Claude Code カスタムスラッシュコマンドの作り方: .claude/commands と $ARGUMENTS で自分の型を作る

レビューのたびに、同じ観点リストを貼り付けていました。「命名は？型は？テストは？エラー処理は？」——毎回コピペ。リリース前になると、長い手順をSlackの過去ログから探し出す。セッションの終わりには、何をどこまでやったかを手で書き起こす。

ある日ふと数えたら、その「定型プロンプトの貼り付け」だけで一日30分くらい溶けていました。賢いAIを横に置いて、僕は同じ文章を打ち直す係をやっていたわけです。

それをやめさせてくれたのが、カスタムスラッシュコマンドでした。/review と打つだけで、いつものレビュー観点でコードを読む。/handoff で引き継ぎメモが出てくる。プロンプト術が個人の頭から、リポジトリの中の .md ファイルに移った瞬間、チーム全員が同じ型を使えるようになりました。

この記事は、2026年6月時点のClaude Code公式ドキュメントで動作を確認した内容だけを書きます。古い記事に残る未確認の構文は写しません。.claude/commands/ の置き方、$ARGUMENTS と位置引数、frontmatterの設定、スキルとの関係、チーム共有まで、僕が実際に使っている形で順に見ていきます。

この記事の要点

• 自作コマンドの正体は「.md ファイル1枚」。.claude/commands/review.md を置けば、その場で /review が使える。
• 公式ではカスタムコマンドはスキルに統合された。.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy になり、既存ファイルはそのまま動く。
• 引数はまず $ARGUMENTS だけ覚えればいい。位置指定は $0（先頭）$1…、名前付きは frontmatter の arguments: で。
• frontmatter で description argument-hint allowed-tools disable-model-invocation を設定して、誤起動と権限事故を防ぐ。
• チームで使うコマンドはアプリコードと同じく Git 管理してレビューする。破壊的操作は本文に書かない。

自作コマンドの正体は「.mdファイル1枚」

最初に誤解を解いておきます。スラッシュコマンドと聞くと、何かプラグインを書いたり設定をいじったりする話に聞こえますが、違います。やることは、決まったフォルダに Markdownファイルを1枚置くだけ です。

セッション中、メッセージの先頭を / で始めると、それがコマンドとして解釈されます。/review main と打てば、review というコマンドが呼ばれ、後ろの main が引数として渡る。たったこれだけの仕組みです。

そのコマンドの中身が、.claude/commands/review.md というファイル。中にはAIへの指示文（プロンプト）が書いてあります。つまり自作コマンドとは、よく使うプロンプトに短い名前を付けて保存したもの。それ以上でもそれ以下でもありません。

だから身構える必要はないんです。いつも貼り付けているレビュー観点を、そのままファイルにコピーして保存する。それで /review が完成します。

「コマンド」と「スキル」は同じものになった

ここが少しややこしいので、先に整理します。

以前のClaude Codeには「カスタムコマンド」と「スキル（Skills）」が別々にありました。が、現在の公式ドキュメントでは カスタムコマンドはスキルに統合 されています。公式の表現を借りると、「.claude/commands/deploy.md のファイルと .claude/skills/deploy/SKILL.md のスキルは、どちらも /deploy を作り、同じように動く」。

つまり、こう考えればOKです。

• .claude/commands/名前.md … 旧来の手軽な書き方。いまも完全に動く。ファイル1枚で完結する単純なコマンド向き。
• .claude/skills/名前/SKILL.md … 推奨される新しい書き方。フォルダなので、チェックリストやスクリプトなどの 補助ファイルを同梱できる。

スキル形式が増えた利点は、補助ファイルを置けること、frontmatterで自動起動を細かく制御できること、関連する話題のときにClaudeが自分で読み込めること。逆に言えば、ファイル1枚で足りる用途なら .claude/commands/ のままで何も問題ありません。両方が共存でき、同名なら スキルが優先 されます。

この記事では取っつきやすい .claude/commands/*.md を主役に、補助ファイルが要る場面でスキル形式を補足します。プロンプト本体の育て方や棚卸しは、別記事のClaude Codeのプロンプト管理術に寄せているので、合わせて読むと運用まで地続きになります。

どこに置くか: 個人用とプロジェクト用

ファイルの置き場所で「誰が使えるか」が決まります。チームで共有したいなら、リポジトリ配下に置くのが基本です。Gitに含まれるので、レビュー対象になり、変更履歴も残ります。

置き場所	パス例	使える範囲	向いている用途
プロジェクト Command	.claude/commands/handoff.md	このリポジトリ	チーム共通の軽いコマンド
プロジェクト Skill	.claude/skills/team-review/SKILL.md	このリポジトリ	補助ファイル付きの手順
個人 Command	~/.claude/commands/note.md	全プロジェクト	自分だけのメモ系
個人 Skill	~/.claude/skills/my-flow/SKILL.md	全プロジェクト	毎日使う個人ワークフロー

同じ名前が複数の階層にあるときの優先順位は、エンタープライズ > 個人 > プロジェクト の順。サブフォルダで分類することもでき、モノレポなら packages/frontend/.claude/skills/ のように、作業中のパッケージ固有のコマンドも拾われます。

僕の実プロジェクトでは、こんな構成に落ち着きました。単純な互換コマンドは commands/ に、補助スクリプトを持つ手順は skills/ に寄せています。

.claude/
├── commands/
│   └── handoff.md
└── skills/
    ├── team-review/
    │   ├── SKILL.md
    │   └── checklists/
    │       └── review.md
    └── release-prep/
        ├── SKILL.md
        └── scripts/
            └── collect-notes.sh

ファイルを追加したのにセッションに出てこないときは、/reload-skills を実行するか、新しいセッションを開きます。まず / を打って一覧に出るか、説明文が意図どおり表示されるかを確認するのがコツです。

コピペで作る最小コマンド

説明より、作ったほうが早いです。組み込みの /review と名前がぶつからないよう、/team-review として作ってみます。下のブロックをそのままターミナルに貼れば、.claude/commands/team-review.md が出来上がります。

# プロジェクト直下で実行する
mkdir -p .claude/commands

cat > .claude/commands/team-review.md <<'EOF'
---
description: チームのレビュー観点で、現在の変更を読み取り専用でレビューする
argument-hint: [対象ブランチ または パス]
disable-model-invocation: true
---

あなたは読み取り専用のチームレビューを行います。

レビュー対象: $ARGUMENTS

対象が空のときは、どの差分・ブランチ・パスをレビューするか先に確認すること。
ファイルは編集しない。破壊的なコマンドも実行しない。

次の観点で、重大度の高い順にレビューする:
1. 正しさのバグ・境界値の漏れ
2. セキュリティとプライバシーのリスク
3. テスト不足・未検証の箇所
4. 既存コードの書き方との一貫性
5. ドキュメント・移行手順・ユーザー向け文言

出力:
- 指摘を重大度順に先頭へ
- 可能なら該当ファイルと行番号を添える
- 各指摘に短い修正案を1つ
- 問題が無いときだけ「指摘なし」と書く
EOF

あとはClaude Codeを開いて、/team-review main や /team-review src/auth のように呼び出すだけ。後ろに書いた main が、ファイル内の $ARGUMENTS に流し込まれます。

frontmatterの disable-model-invocation: true は、Claudeが勝手にこのコマンドを自動起動しないようにする 設定です。レビューやリリースのように「人間が明示的に実行したい」手順では、誤起動を防ぐために入れておくと安心です。

引数の使い方: まず $ARGUMENTS だけでいい

引数は難しく考えなくて大丈夫です。最初は $ARGUMENTS 一本で十分。/handoff backend reviewer と打てば、$ARGUMENTS には backend reviewer という文字列がまるごと入ります。

もし $ARGUMENTS を本文に書かなくても、入力は捨てられません。公式仕様では、その場合 ARGUMENTS: <入力した値> がコマンド末尾に追加され、Claudeはちゃんと受け取ります。

引数を位置で取り分けたくなったら、次の書き方が使えます。

書き方	意味
$ARGUMENTS	入力された引数すべて（文字列まるごと）
$ARGUMENTS[0]	0始まりで N 番目の引数
$0 $1 …	$ARGUMENTS[N] の短縮形。$0 が先頭
$name	frontmatter の arguments: で宣言した名前付き引数

ここで一つ注意。古いサンプルには「$1 が最初の引数」と書いてあるものがありますが、現在の公式仕様では $0 が最初の引数 です（$1 は2番目）。写経するときは要確認です。

名前付き引数にすると指示文が読みやすくなります。frontmatterに arguments: [issue, branch] と宣言すると、宣言順に位置が割り当たり、$issue が1番目、$branch が2番目になります。

---
description: Issue 単位の作業計画を立てる
argument-hint: [issue] [branch]
arguments: [issue, branch]
disable-model-invocation: true
---

Issue: $issue
Branch: $branch
すべての引数: $ARGUMENTS

次の計画を作る:
1. Issue を平易な言葉で言い換える
2. 最初に読むべきファイルを挙げる
3. 関係しそうなテストを特定する
4. 変更してはいけない箇所を1つ名指しする

複数の単語を1つの引数として渡したいときは、引用符で囲みます。/plan-issue "login redirect bug" fix-login とすれば、$0 は login redirect bug、$1 は fix-login になります。引用符のないスペースは引数の区切りとして扱われる、という点だけ覚えておけば困りません。

frontmatterで挙動を縛る

.md の先頭、--- で囲んだ部分が frontmatter です。ここでコマンドの振る舞いを制御します。よく使うフィールドを、僕の使いどころと合わせて並べます。

フィールド	役割	使いどころ
description	何をするコマンドか	一覧での説明文。Claudeが自動起動の判断にも使う
argument-hint	引数の入力ヒント	/ 入力時の補完で [branch] のように表示
arguments	名前付き引数の宣言	[issue, branch] で $issue $branch を有効化
disable-model-invocation	自動起動の禁止	true で人間だけが実行可。副作用のある手順に
allowed-tools	確認なしで使えるツール	Read Grep のように最小限を列挙
disallowed-tools	使わせないツール	自律ループで触ってほしくないツールを外す
model	このコマンド中のモデル	重い調査だけ上位モデル、など一時的な切り替え

allowed-tools は誤解しやすいので補足します。これは「ここに挙げたツールを 確認なしで使える ようにする」設定であって、使えるツールを制限するものではありません。挙げていないツールも呼べますし、権限の最終判断は通常の権限設定に従います。だから広く Bash を許可しすぎると、確認なしで動く範囲が一気に広がります。まずは読み取り系だけ許可し、必要な権限を1つずつ足すのが現実的です。

プロジェクトに置いた .claude/skills/ の allowed-tools は、そのフォルダの信頼ダイアログを承認したあとに有効になります。リポジトリを信頼する前にスキル本文を読む——これは習慣にしておくと安全です。コマンドが自分自身に広いツール権限を与える、というのも理屈上は可能だからです。

ライブな文脈を流し込む: ! 構文

ここからが、ただのプロンプト保存を一歩超える部分です。コマンド本文に !`コマンド` と書くと、Claudeが本文を読む前にそのシェルコマンドが実行され、出力がその場に埋め込まれます。

たとえばリリースノートの下書きを作るコマンド。git status と git log の結果を、あらかじめプロンプトに差し込んでおけます。

---
description: リリースノート用に読み取り専用の git 情報を集める
allowed-tools: Bash(git status:*) Bash(git log:*)
disable-model-invocation: true
---

現在の状態:
!`git status --short`

直近のコミット:
!`git log --oneline -20`

上の情報からリリースノートを要約する。
書き込み系の操作はしないこと。

このコマンドを呼ぶと、まず git status と git log が走り、その出力が本文に挿入された状態でClaudeに渡ります。だからClaudeは「想像」ではなく「実際の差分」を見て要約できます。

便利な反面、ここが一番の地雷地帯でもあります。!`コマンド` は確認を挟まず実行されるので、破壊的な操作を絶対に入れてはいけません。rm、git clean、git push、npm publish、curl ... | sh、本番に触るコマンド——これらは本文にも補助スクリプトにも書かない。読み取り専用に徹するのが鉄則です。なお ! が行頭か空白の直後にあるときだけこの構文として認識され、KEY=! のように文字の後ろに続く場合はただの文字列として扱われます。

スキルとして育てる: 補助ファイルとチーム共有

コマンドが育ってチェックリストやスクリプトを持ち始めたら、スキル形式に引っ越します。スキルはフォルダなので、SKILL.md を本体に、参照ファイルを横に置けます。

.claude/skills/release-prep/
├── SKILL.md          # 本体（必須）
├── checklists/
│   └── release.md    # 長いチェックリスト
└── scripts/
    └── collect-notes.sh

ポイントは、SKILL.md を薄く保つこと。公式も「SKILL.md は500行以内に」と推奨しています。長い参照資料は別ファイルに逃がし、本文からは「いつ・何のために読むか」を添えて参照する。こうすると、スキルを使うときだけ重い資料が読み込まれ、普段はコンテキストを圧迫しません。スキルに同梱したスクリプトを !`コマンド` から呼ぶときは、${CLAUDE_SKILL_DIR} でスキルのフォルダを指せます（作業ディレクトリがどこでも、同梱ファイルを確実に参照できる）。

チーム共有で効くのは、コマンド自体をレビュー対象にする ことです。理由は単純で、コマンドはチームの作業結果を変えるから。レビュー観点が変われば、見つかるバグも見逃すリスクも変わります。僕が回している運用ルールはこれです。

ルール	目的
.claude/ を Git 管理する	誰がいつ手順を変えたか残す
コマンド変更だけの PR を許可する	手順変更をアプリ差分に紛れ込ませない
CLAUDE.md に一覧を書く	新メンバーが発見しやすくする
破壊的操作の禁止文を入れる	push・publish・削除の事故を防ぐ
月1回だけ棚卸しする	増えすぎたコマンドを減らす

リポジトリ固有の指示はCLAUDE.mdベストプラクティス、自動実行の境界線はClaude Code Hooksガイドと一緒に決めると、コマンド・ルール・自動化が一枚絵でつながります。

僕がやらかした失敗3つ

正直に書きます。最初の数週間は、便利にしようとしては足を撃ち抜いていました。

ひとつ目は、組み込みコマンドと名前をぶつけたこと。環境によっては /review や /code-review が最初から入っています。そこに自分の review.md を被せて、呼んでも意図したほうが動かない。以来、チーム用は /team-review のように接頭辞を付け、作る前に必ず / で一覧を確認するようにしました。

ふたつ目は、個人フォルダにだけ置いて満足したこと。~/.claude/commands/ に作った神コマンドを、僕だけが使えてチームは知らない。共有したい手順は最初からリポジトリの .claude/commands/ に置く、と決めてからチーム全体の速度が変わりました。

みっつ目は、リリースコマンドに publish まで任せたこと。「ついでに公開も」と欲を出した結果、確認の隙が消えて肝が冷えました。今は /release を「公開するコマンド」ではなく「公開前に人間が判断する材料を集めるコマンド」に振り切っています。差分整理とチェックリストまでがコマンドの仕事、最後のボタンは人間。これで夜中のヒヤッとが消えました。

よくある質問

Q. .claude/commands/ はもう古い? スキルに全部書き直すべき? 書き直す必要はありません。公式が「既存の .claude/commands/ ファイルはそのまま動く」と明言しています。ファイル1枚で足りるなら commands/ のままでOK。補助ファイルや自動起動制御が欲しくなったら、その時スキルに移せば十分です。

Q. 作ったのに / 一覧に出てこない。 だいたいは反映待ちです。/reload-skills を実行するか、新しいセッションを開いてください。それでも出ないときは、置き場所（.claude/commands/ か .claude/skills/<名前>/SKILL.md）とファイル名のタイプミス、frontmatterの --- の閉じ忘れを確認します。user-invocable: false を付けていると一覧から隠れる点にも注意。

Q. 引数は $1 から? $0 から? $0 が先頭です。$1 は2番目。古い記事の「$1 が最初」という説明は現在の仕様とずれています。全引数をまとめて使うなら $ARGUMENTS、位置で取るなら $0 から、名前で取るなら frontmatter の arguments: を使います。

Q. コマンドの中で安全にコマンドの結果を使いたい。 !`コマンド` で読み取り専用のものだけ流し込みます。git status --short や gh pr diff のように、状態を変えない取得系に限定してください。allowed-tools も Bash(git status:*) のように対象を絞り、Bash を丸ごと許可しないこと。

Q. チームに配るとき、勝手にAIが実行しないか心配。 副作用のある手順には disable-model-invocation: true を付けます。これでClaudeの自動起動が止まり、人間が /名前 と打ったときだけ走ります。デプロイやコミット、外部送信系には必ず付けておくのが安全です。

実際に試した結果

この型を自分のリポジトリで回してみて、最終的に /team-review・/handoff・/release-prep の3つに絞った構成が一番安定しました。欲張って10個作った時期もありましたが、使うのは結局この3つで、残りは月1の棚卸しで消しました。

一番効いたのは /release を「公開するコマンド」にしなかったことです。差分整理とチェックリスト出力までをコマンドの仕事にして、push と publish は人間の手に残す。これだけで「誤って本番まで進むかも」という常時うっすらある不安が消えました。

カスタムスラッシュコマンドは、自動化を増やす道具というより、チームが同じ基準で立ち止まり、確認し、次へ渡すための道具 です。まずは今いつも貼り付けているプロンプトを1つ、.claude/commands/ に保存するところから始めてみてください。プロンプトをどう整理し続けるかはClaude Codeのプロンプト管理術に、運用の続きをまとめてあります。手元の型を仕事に固定したくなったら、Claude Code教材一覧のテンプレート集もどうぞ。