Claude Code カスタムスラッシュコマンド実践：引数・フロントマター・実例集
Claude Code のカスタムスラッシュコマンドを Skills との関係から整理。$ARGUMENTS と 0 始まりの位置引数、arguments による名前付き引数、description / allowed-tools / argument-hint のフロントマター、実用コマンド例までを集約。
TL;DR
- 公式ではカスタムコマンドは Skills へ統合済み。
.claude/commands/<name>.mdは動作するが互換パス扱い - 引数は
$ARGUMENTS（全部まとめて）と$0$1$2…（位置引数、0 始まり）と、argumentsで宣言する$name（名前付き）の3種類 - フロントマターでは
description（一覧での説明）、allowed-tools（権限制限）、argument-hint（入力ヒント）の3つが運用上の必須セット - これから作るなら
.claude/skills/<name>/SKILL.md形式。旧形式はname/pathsが無視され、同名の skill に負ける
公式ドキュメントでは、カスタムコマンドは Skills へ統合されました。
Custom commands have been merged into skills. A file at
.claude/commands/deploy.mdand a skill at.claude/skills/deploy/SKILL.mdboth create/deployand work the same way. Your existing.claude/commands/files keep working. — Skills | Claude Code Docs
slash-commandsの独立ページは廃止され、Skills ページへ統合されています。これから作るなら Skills 形式を使ってください（公式も “Skills are recommended” と明記）。本記事は.claude/commands/に既存資産がある場合の互換情報と、引数まわりの実践に絞ります。Skills 全般は Skills 完全ガイド を参照してください。
配置場所と Skills との関係
カスタムコマンドの実体は Skills と同じ Markdown フォーマットです。3 種類の配置パスがすべて有効です。
| 配置 | 形式 | 状態 |
|---|---|---|
.claude/skills/<name>/SKILL.md | Skills 形式 | 推奨。サポートファイル・自動起動制御が使える |
.claude/commands/<name>.md | 旧来形式 | 動作するが互換パス。新規作成には非推奨 |
~/.claude/skills/<name>/SKILL.md | 個人用 | 全プロジェクト共通の自分専用 |
旧形式に残る制約
.claude/commands/ 側で押さえておくべき差分です。
- **
nameとpathsフロントマターは無視される。**コマンド名はファイル名から決まります - **同名の skill があれば skill が優先される。**移行途中に両方置くと、commands 側は無効になります
- サポートファイル（
scripts/references/assets/）を伴う構成にできません
「とりあえず短いプロンプトを呼び出したい」だけなら旧形式でも動きますが、サポートファイルが増える / チームで共有する / 自動起動させたいなら Skills 形式に寄せてください。
サブディレクトリも有効です。.claude/commands/git/commit.md と置けば /git:commit で呼び出せます。コマンド数が増えてきたら名前空間で整理します。
最小構成
---
description: 直前の git diff の要約を作る
---
`git diff` の差分を読み、変更点を 5 行以内で要約してください。ファイルを .claude/commands/diff-summary.md として置き、Claude Code を再起動（または /help を叩く）と一覧に出ます。/diff-summary で呼び出せます。
引数の取り扱い
$ARGUMENTS ：全文をまとめて使う
---
description: エラーメッセージを分析して原因を特定
argument-hint: <error message>
---
以下のエラーメッセージを読み、原因と対処方法を整理してください。
エラー:
$ARGUMENTS呼び出し例：
/analyze-error TypeError: Cannot read property 'foo' of undefined at App.tsx:42$ARGUMENTS には /analyze-error 以降のテキストがそのまま入ります。改行・記号・スペースを保持できるので、長いエラーログをそのまま流し込む用途に向きます。
$0 $1 $2 ：位置引数で受ける
インデックスは 0 始まりです。
$0が第1引数、$1が第2引数です。公式ドキュメントの原文は次のとおりです。
$N— Shorthand for$ARGUMENTS[N], such as$0for the first argument or$1for the second. — Skills | Claude Code Docsコマンド名を参照する変数は存在しません。
$0をコマンド名だと解説している記事（本記事の旧版を含む）を見かけたら、現行仕様と食い違っています。
---
description: 2つのファイルを比較
argument-hint: [ファイル1] [ファイル2]
---
@$0 と @$1 を比較し、差分の意味を説明してください。
特に重要な差分があれば強調してください。呼び出し例：
/compare-files src/old.ts src/new.ts$0 = src/old.ts、$1 = src/new.ts になります。$ARGUMENTS[0] $ARGUMENTS[1] と書いても同じです。
名前付き引数で読みやすくする
位置番号は取り違えやすいので、arguments フロントマターで名前を付けられます。名前は宣言順に位置へ対応します。
---
description: 2つのファイルを比較
arguments: [before, after]
---
@$before と @$after を比較し、差分の意味を説明してください。$0 / $1 より意図が読み取れるので、引数が2つ以上あるなら基本的にこちらを使ってください。
スペースを含む引数
**シェル同様のクォートが効きます。**複数語をひとつの引数として渡したい場合はクォートで囲ってください。
/my-skill "hello world" secondこの場合 $0 は hello world、$1 は second になります。
引数が足りない時の挙動
挙動が2種類あるので区別してください。
| 記法 | 対応する引数が無いとき |
|---|---|
$0 $1 などの位置指定 | 置換されず、そのまま文字列として残る（$2 と書かれたまま） |
arguments で宣言した $name | 空文字列に展開される |
位置指定が置換されずに残ると、プロンプトに $2 という文字列が紛れ込みます。対策は2つです。
- プロンプト内で「引数が空なら現在の会話のコードを対象とする」のような分岐を明示する
argument-hintを必ず書く（入力時に必要な引数を促せる）
なお、文中で $1.00 のようにリテラルの $ を書きたい場合は \$1.00 とバックスラッシュでエスケープします。
フロントマター運用必須セット
description
スラコマ一覧（/ 入力時）に出る説明文です。
---
description: PR レビュー用の差分・コミット履歴を整理する
---「これがなくても動く」ですが、書かないと一覧で「何だったか」が思い出せず、後から自分で書いたコマンドを呼び忘れる原因になります。1行 = 約 60 字以内で「いつ使うか」が伝わるように書きます。
allowed-tools
そのコマンド実行中だけツールを絞れます。事故防止と「誤発火しても破壊が起きない」設計のために重要です。
| 指定 | 意味 |
|---|---|
Read, Grep, Glob | 読み取り系のみ。レビュー / 監査向け |
Bash(git:*), Read, Edit | git 系シェルだけ許可 + ファイル編集 |
Bash(npm test), Read | テスト実行だけ許可 |
| 省略 | セッションの権限を継承（ゆるくなりがち） |
---
description: コードを読み取り専用で監査する
allowed-tools: Read, Grep, Glob
---副作用のあるコマンド（デプロイ・DB マイグレーション系）は逆に allowed-tools を狭く絞って disable-model-invocation: true を併用し、「ユーザーが明示的に呼んだ時だけ動く」設計にします。
argument-hint
入力ヒントです。コマンド一覧で /foo <hint> のように表示されるので、必要な引数を視覚的に伝えられます。
---
description: ブランチを切ってマイグレーションファイルを作る
argument-hint: <branch-name> <migration-name>
---実用コマンド例
安全なコミットコマンド
---
description: ステージ済みの変更を Conventional Commits でコミット
allowed-tools: Bash(git:*), Bash(npm test)
---
ステージされている変更をコミットしてください。
1. `git diff --staged` で内容を確認
2. `npm test` を実行して通ることを確認（失敗したらコミットしない）
3. Conventional Commits 形式（feat/fix/refactor/test/docs/chore）でメッセージを作成
4. `git commit -m "..."` を実行PR レビュー準備
---
description: PR レビュー用の情報を集約
argument-hint: <branch-name> <category>
arguments: [branch, category]
allowed-tools: Bash(git:*), Bash(gh:*), Read
---
PR レビュー前の情報を準備してください。
- 対象ブランチ: $branch
- 変更カテゴリ: $category
1. `git log main..$branch --oneline` でコミット一覧
2. `git diff main...$branch --stat` で変更ファイル一覧
3. $category の観点（例: security / performance / readability）で重点レビューポイントを 3 つ抽出
4. 結果を Markdown で出力エラーログ解析
---
description: 貼り付けたエラーログから原因を絞り込む
argument-hint: <error log>
allowed-tools: Read, Grep, Glob
---
以下のエラーログを分析してください。
ログ:
$ARGUMENTS
1. 直接の原因と思われる行を特定
2. 関連しそうなソースコードを Grep / Glob で探す
3. 原因仮説を 3 つ、優先度順に並べる
4. 最も可能性が高い仮説について検証手順を提示環境チェック
---
description: 開発環境の前提が揃っているか確認
allowed-tools: Bash(node *), Bash(git *), Bash(docker *), Read
---
このプロジェクトの開発環境チェックを行ってください。
- Node.js のバージョン（package.json の engines と一致するか）
- git のクリーンさ（uncommitted changes はないか）
- Docker / Docker Compose の起動状態
- .env.example と .env の差分
問題があれば修正コマンドを提示してください。修正は実行しないこと。反映タイミングとデバッグ
- 追加 / 編集後の反映:
/helpか/skillsで一覧を再ロードすると認識されます。場合によっては Claude Code を再起動 - 動かない時の確認順: ファイル名 →
descriptionの有無 → 配置パス（.claude/commands/か.claude/skills/<name>/SKILL.md） →allowed-toolsで必要なツールが落ちていないか - 手動呼び出しで動くか:
/skill-name fooで手動実行して動けば「自動選択精度」の問題、動かなければ定義そのものの問題と切り分けられる
関連ドキュメント
- Skills 完全ガイド（同じ仕組みのフルセット解説）
- サブエージェント活用ガイド（コマンドではなく独立コンテキストで委譲する場合）
- Hooks 完全ガイド（決定論的に走らせたい処理はこちら）