Claude Codeのカスタムスラッシュコマンドで作業を効率化する方法

Claude Codeを毎日使っていると、「またこの依頼文を貼り付けている」「毎回同じ手順をAIに説明している」場面が必ず出てきます。これはCLIに自作の関数を定義するべきタイミングで、Claude Codeではカスタムスラッシュコマンドとして登録できます。本記事では、最新仕様（コマンドはSkillsに統合済み）に沿って、作成方法・引数の渡し方・配布の3点を実例ベースで整理します。

結論：.claude/commands/か.claude/skills/にMarkdownを置くだけ

カスタムスラッシュコマンドは、リポジトリ直下の.claude/commands/<name>.mdまたはユーザー共通の~/.claude/commands/<name>.mdに Markdown ファイルを置くだけで作成できます。中身はそのままAIへの依頼文として扱われ、/<name>で呼び出せます。

公式ドキュメントによると、2026年時点でカスタムコマンドはSkillsに統合されました。.claude/commands/deploy.mdと.claude/skills/deploy/SKILL.mdはどちらも/deployコマンドを作成し、ほぼ同じように動きます。.claude/commands/配下の既存ファイルはそのまま動作しますが、.claude/skills/を使うと「補助ファイルをサブディレクトリにまとめる」「Claudeが自動起動できる」などの機能が追加で使えます。新規作成ならSkills形式が公式の推奨です。

判断は単純です。

• 手動で呼びたいだけ：.claude/commands/<name>.mdで十分
• 補助スクリプトや参照資料を同梱したい・Claudeに自動起動させたい：.claude/skills/<name>/SKILL.md

CLAUDE.md自体の書き方は「CLAUDE.mdテンプレート完全版」、CLIコマンド全体は「Claude Codeの基本コマンドと日常的に使う操作まとめ」に任せ、本記事は「自作コマンド」に絞ります。

最小例：30行で動くカスタムコマンド

まずはコマンド形式の最小例を見ます。プロジェクトのリリースノート草案を生成する/release-notesコマンドを作ります。

.claude/
└─ commands/
   └─ release-notes.md

.claude/commands/release-notes.mdの中身は次のようにします。

---
description: 直近のコミットからリリースノート草案を作成する
argument-hint: [前回タグ]
allowed-tools: Bash(git log:*) Bash(git diff:*)
---

直近のコミットを確認してリリースノート草案を作成してください。

## 入力
- 比較基準: $ARGUMENTS（前回タグやコミットハッシュ。未指定なら直近20件）
- コミット履歴: !`git log --oneline -n 20`
- 変更ファイル一覧: !`git diff --name-only $ARGUMENTS HEAD 2>/dev/null || git diff --name-only HEAD~20 HEAD`

## 出力ルール
- ユーザーから見える変更だけを Features / Fixes / Internal の3カテゴリでまとめる
- 内部リファクタは Internal に集約する
- 破壊的変更がある場合は冒頭に **BREAKING:** を付ける
- Markdown 箇条書きで返す

これでClaude Code内で/release-notes v1.2.0と打つと、v1.2.0が$ARGUMENTSに展開され、git logの出力もコマンドに埋め込まれた状態でClaudeに渡されます。

frontmatterの主要フィールド

公式仕様で押さえるべきfrontmatterは次のとおりです。

allowed-toolsは「コマンド実行中だけツール承認を省略する」許可リストです。すべての権限を付与するのではなく、コマンドが本当に必要とするものだけを書きます。たとえばコミット用コマンドなら、Bash(git add *) Bash(git commit *) Bash(git status *)に絞るのが安全です。

disable-model-invocation: trueは副作用のあるコマンドで重要です。/deployや/send-slack-messageのような「Claudeが勝手に判断して呼ぶと困るコマンド」には必ず付けてください。

引数の渡し方：$ARGUMENTSと$0の使い分け

カスタムコマンドの引数は3つの形式で参照できます。

複数引数を扱うときは、frontmatterにargumentsを宣言しておくと読み手にやさしくなります。

---
description: コンポーネントを別フレームワークへ移行する
arguments: [component, from, to]
argument-hint: [component-name] [from-framework] [to-framework]
---

$component を $from から $to に移行してください。既存のテストと挙動は維持してください。

呼び出しは/migrate-component SearchBar React Vueのように書きます。SearchBar React Vueが空白区切りで$component $from $toに割り当てられます。

複数語を1つの引数として渡したい場合はクオートで囲みます。例：/release-notes "v1.2.0 release"。

動的コンテキスト注入：!と@の違い

カスタムコマンドの強みは、ClaudeにファイルやコマンドOutputを渡す前処理を1か所で書けることです。2つの記法を使い分けます。

• !`<command>`：シェルコマンドを実行し、出力をその場に挿入してからClaudeに渡す（前処理）
• @<path>：ファイルを参照対象として読み込ませる

最小例：

## 状況
- 現在のブランチ: !`git rev-parse --abbrev-ref HEAD`
- 最新のテスト失敗ログ: !`grep -E '(FAIL|ERROR)' test.log | tail -20`
- レビュー対象ファイル: @src/lib/auth.ts

!`...`はClaudeが起動する前に手元のシェルで実行され、結果テキストが本文に埋め込まれます。ClaudeがBashツールを呼ぶわけではない点に注意してください。長文を出すコマンドはコンテキストを圧迫します。grep -E '(FAIL|ERROR)' | tail -20のように、必要部分だけ抜き出してから渡すのがコツです。コンテキスト消費の設計全体は「Claude Codeに必要な情報だけ渡すコンテキスト設計」で扱っています。

複数行のシェルブロックを書きたいときは、フェンス記法も使えます。

## 環境
```!
node --version
npm --version
git status --short
```

配布スコープ：個人・プロジェクト・チーム

カスタムコマンドは保存場所で公開範囲が変わります。

優先順位は Enterprise > Personal > Project、プラグインは別名前空間（plugin-name:skill-name）になります。

チームに配布するときの実務的なポイントは次のとおりです。

• .claude/commands/をGit管理し、ワークスペース信頼ダイアログでメンバーに承認させる
• allowed-toolsは最小限。コミット用ならBash(git add *)のように対象を絞る
• 副作用のあるコマンドは必ずdisable-model-invocation: trueを入れて、Claudeの勝手な起動を防ぐ
• 個人専用の実験コマンドは~/.claude/commands/に置き、リポジトリに混入させない

レビュー必須化やチーム運用の枠組み自体は「チームでClaude Codeを導入するときに最初に決めるルール」を参照してください。

実用テンプレ3本

1. /commit：差分要約→コミット

---
description: ステージ済みの差分を確認してConventional Commits形式でコミットする
disable-model-invocation: true
allowed-tools: Bash(git status:*) Bash(git diff:*) Bash(git add:*) Bash(git commit:*)
---

## 現在の状態
- ステータス: !`git status -s`
- ステージ済み差分: !`git diff --cached`

## 手順
1. 差分を要約し Conventional Commits の type を判定する
2. 1コミット=1意図になっているか確認する。混ざっていれば指摘して停止
3. コミットメッセージ案を提示し、ユーザー承認後に `git commit -m` を実行する

2. /pr-summary：PR本文ドラフト

---
description: 現在のブランチのPR本文ドラフトを書く
argument-hint: [base-branch]
allowed-tools: Bash(git log:*) Bash(git diff:*) Bash(gh pr view:*)
---

## 入力
- ベースブランチ: $ARGUMENTS（未指定なら main）
- コミット履歴: !`git log --oneline $ARGUMENTS..HEAD 2>/dev/null || git log --oneline main..HEAD`
- 変更ファイル: !`git diff --name-only $ARGUMENTS...HEAD 2>/dev/null || git diff --name-only main...HEAD`

## 出力
- ## Summary（3〜5行）
- ## Test plan（チェックリスト）
- ## Notes（破壊的変更や注意点があれば）

3. /explore-area：fork実行で並列調査

---
description: 指定ディレクトリの全体像を読み取り専用で調査する
argument-hint: [path]
context: fork
agent: Explore
---

$ARGUMENTS 配下のコード構成を調査してください。

1. Glob と Grep で主要ファイルを特定する
2. 依存関係とエントリポイントを把握する
3. 「触ると怖い箇所」「テストカバレッジが薄い箇所」を指摘する
4. 結論を 200 字以内のサマリにする

context: forkを使うと、サブエージェントで実行されメインの会話履歴を埋めません。大規模な調査依頼で重宝します。サブエージェントの全体像は「Claude Codeのサブエージェントとは？使いどころと注意点」を参照してください。

よくある設計ミス5つ

動作確認と更新

カスタムコマンドはセッション中の変更も即時反映されます（公式の Live change detection）。~/.claude/commands/、./.claude/commands/、--add-dirで追加したディレクトリの.claude/commands/はファイル変更が監視されます。ただし最上位の commands ディレクトリ自体を新規作成した場合はClaude Codeの再起動が必要です。

確認には/helpで一覧を見るか、ターミナルで補完を試します。

起動後に/を入力すると自作コマンドが候補に出ます。挙動が変なときは/doctorで診断します。

導入チェックリスト

• コマンド名はケバブケースで短く動詞起点にした（例: release-notes pr-summary）
• descriptionにトリガー語とユースケースを書いた
• 副作用のあるコマンドにはdisable-model-invocation: trueを付けた
• allowed-toolsはサブコマンド単位の最小権限にした
• !で流し込むログはgrep／tailで行数を絞った
• 個人専用は~/.claude/commands/、共有は.claude/commands/に置き分けた
• チーム共有はGit管理し、ワークスペース信頼ダイアログを通している
• 200行を超えそうな手順は補助ファイルへ分割し@で参照した

次に読むおすすめ記事：

• 「Claude Codeの基本コマンドと日常的に使う操作まとめ」：CLIコマンドとスラッシュコマンド全体像
• 「CLAUDE.mdテンプレート完全版」：コマンドと並ぶ「共通ルール」の集約先
• 「Claude Codeにコード規約を守らせるための書き方」：HooksとSkillsの使い分け