Claude Codeで繰り返し同じプロンプトを入力していませんか。カスタムコマンドを使えば、よく使う指示をMarkdownファイルひとつで登録し、/コマンド名の短い入力で呼び出せます。
カスタムコマンドとは、.claude/commands/ディレクトリに配置したMarkdownファイルがそのままスラッシュコマンドになる仕組みです。ファイル名がコマンド名、ファイルの中身がClaude Codeへの指示になります。バージョン2.1.3以降は「Skills」という上位概念に統合され、サポートファイルの同梱やClaudeによる自動呼び出しにも対応しました。
カスタムコマンドの基本構造
カスタムコマンドの作成は3ステップで完了します。
手順1: ディレクトリを用意する
mkdir -p .claude/commands
プロジェクトルートの.claude/commands/に置いたコマンドは、そのプロジェクト内だけで有効です。全プロジェクト共通で使いたい場合は~/.claude/commands/に配置します。
手順2: Markdownファイルを作成する
<!-- .claude/commands/review.md -->
このプロジェクトのコードをレビューしてください。
## チェック観点
- 型安全性に問題がないか
- エラーハンドリングの漏れ
- パフォーマンス上の懸念
- セキュリティリスク（OWASP Top 10）
問題を発見した場合は修正案もコードで示してください。
手順3: Claude Codeで実行する
claude
> /review
これだけでカスタムコマンドが動作します。
保存場所による適用範囲の違い
カスタムコマンドは配置するディレクトリによって利用できる範囲が変わります。
| 配置場所 | パス | 適用範囲 |
|---|---|---|
| プロジェクト | .claude/commands/<名前>.md | 該当プロジェクトのみ |
| ユーザー個人 | ~/.claude/commands/<名前>.md | 全プロジェクト共通 |
| Skills形式 | .claude/skills/<名前>/SKILL.md | 該当プロジェクト（拡張機能付き） |
| エンタープライズ | マネージド設定で配布 | 組織全体 |
同名のコマンドが複数の階層に存在する場合、エンタープライズ → ユーザー個人 → プロジェクトの優先順位で解決されます。
チーム開発では.claude/commands/をGitリポジトリに含めることで、メンバー全員が同じコマンドを共有できます。
front matterで動作を細かく制御する
Markdownファイルの先頭にYAML front matterを記述すると、コマンドの動作を詳細に制御できます。
---
name: safe-deploy
description: 本番環境へのデプロイを実行する
argument-hint: "[environment]"
disable-model-invocation: true
allowed-tools: Bash(npm run build:*), Bash(git push:*)
---
各フィールドの役割は次のとおりです。
| フィールド | 用途 | 設定例 |
|---|---|---|
name | コマンド名（省略時はディレクトリ名） | safe-deploy |
description | 用途の説明。Claudeが自動判断に使用 | 本番環境へのデプロイ |
argument-hint | 補完時に表示される引数のヒント | [issue-number] |
disable-model-invocation | trueでClaude側からの自動呼び出しを禁止 | true |
user-invocable | falseでユーザーの/メニューから非表示 | false |
allowed-tools | 許可確認なしで使えるツール | Read, Grep, Glob |
model | 使用するモデルの指定 | sonnet |
context | forkでサブエージェントとして実行 | fork |
agent | context: fork時のエージェント種別 | Explore |
hooks | Skillライフサイクルに紐づくHooksの設定 | （Hooks設定オブジェクト） |
allowed-toolsの実践的な書き方
allowed-toolsにはツール名のほか、パターン指定も使えます。
# 特定のgitコマンドだけ許可
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
# 読み取り専用にしたい場合
allowed-tools: Read, Grep, Glob
# GitHub CLIだけ許可
allowed-tools: Bash(gh *)
デプロイや削除など副作用の大きいコマンドでは、allowed-toolsで許可範囲を絞ることでミスを防止できます。
disable-model-invocationとuser-invocableの使い分け
この2つのフィールドは「誰がコマンドを呼び出せるか」を制御します。
| 設定 | ユーザーが実行 | Claudeが自動実行 | 用途 |
|---|---|---|---|
| デフォルト（未設定） | 可能 | 可能 | 汎用的なコマンド |
disable-model-invocation: true | 可能 | 不可 | デプロイ・コミットなど副作用のある操作 |
user-invocable: false | 不可 | 可能 | コーディング規約などのバックグラウンド知識 |
$ARGUMENTSで引数を受け取る
$ARGUMENTSプレースホルダーを使うと、実行時に値を渡せます。
---
name: fix-issue
description: GitHub Issueの内容に基づいて修正する
argument-hint: "[Issue番号]"
disable-model-invocation: true
---
GitHub Issue $ARGUMENTS の内容を読み取り、修正を実装してください。
## 手順
1. `gh issue view $ARGUMENTS` でIssueを確認
2. 要件を把握し、修正を実装
3. テストを追加
4. 変更内容をサマリーとして報告
実行方法:
/fix-issue 42
位置引数で複数の値を受け取る
$ARGUMENTS[N]（0始まり）または短縮形$Nで個別の引数にアクセスできます。
---
name: migrate
description: コンポーネントを別フレームワークに移行
argument-hint: "[コンポーネント名] [移行元] [移行先]"
---
$0 コンポーネントを $1 から $2 に移行してください。
既存の動作とテストをすべて維持すること。
実行例:
/migrate SearchBar React Vue
この場合、$0がSearchBar、$1がReact、$2がVueに置換されます。
実務で役立つカスタムコマンド集
カテゴリ別に、そのまま使えるコマンド例を紹介します。
コードレビュー系
---
name: security-check
description: セキュリティ観点でコードをレビュー
allowed-tools: Read, Grep, Glob
---
セキュリティの観点でコードベースを点検してください。
## 検査項目
- SQLインジェクションの可能性（プレースホルダ未使用のクエリ）
- XSS脆弱性（ユーザー入力のサニタイズ漏れ）
- 認証・認可のバイパス経路
- 機密情報のハードコード（APIキー、パスワード）
- 依存パッケージの既知脆弱性
問題を発見した場合、CWE番号・影響度・修正案を報告してください。
Git操作系
---
name: smart-commit
description: 変更内容に基づいてConventional Commitsで自動コミット
disable-model-invocation: true
allowed-tools: Bash(git *)
---
## 手順
1. `git status`と`git diff`で変更内容を確認
2. 変更の意図を分析し、Conventional Commits形式でメッセージを作成
- 形式: `type(scope): subject`
- type: feat / fix / refactor / test / docs / chore
3. 適切な粒度でステージングとコミットを実行
## 注意
- 1コミット1目的を徹底する
- 大きな変更は論理単位で分割する
- .envや認証情報は絶対にコミットしない
テスト生成系
---
name: gen-test
description: 指定ファイルのテストコードを生成
argument-hint: "[対象ファイルパス]"
allowed-tools: Read, Write, Bash
---
$ARGUMENTS に対する包括的なテストコードを生成してください。
## テスト設計方針
- 正常系: 想定される入力パターンの動作確認
- 異常系: 不正入力・エッジケース・境界値
- モック: 外部依存は適切にモック化
## 制約
- プロジェクトで使用中のテストフレームワークに準拠
- カバレッジ80%以上を目標
- テスト名は「何を」「どういう条件で」「どうなるか」を明示
ドキュメント生成系
---
name: update-readme
description: 実装の変更に合わせてREADMEを更新
allowed-tools: Read, Write, Glob
---
プロジェクトの現状を調査し、READMEを更新してください。
## 更新対象
- セットアップ手順（依存パッケージの変更を反映）
- 環境変数一覧（追加・削除された変数を反映）
- ディレクトリ構成（新規追加のモジュールを反映）
- APIエンドポイント一覧（ルーティングの変更を反映）
現在のコードベースと乖離している箇所のみ修正してください。
Skills形式への移行と追加機能
バージョン2.1.3以降、カスタムコマンドはSkillsという上位概念に統合されました。既存の.claude/commands/ファイルは引き続き動作しますが、Skills形式にすると追加機能が使えます。
commandsとSkillsの違い
| 機能 | commands形式 | Skills形式 |
|---|---|---|
基本動作（/で実行） | 対応 | 対応 |
| front matter | 対応 | 対応 |
| サポートファイルの同梱 | 非対応 | 対応 |
| Claudeによる自動呼び出し | 対応 | 対応 |
| サブエージェント実行 | 非対応 | context: forkで対応 |
| 動的コンテキスト注入 | 非対応 | !`command``で対応 |
Skills形式のディレクトリ構造
.claude/skills/
└── my-skill/
├── SKILL.md # メインの指示（必須）
├── template.md # テンプレートファイル
├── examples/
│ └── sample.md # 出力サンプル
└── scripts/
└── validate.sh # 実行可能なスクリプト
SKILL.mdがエントリーポイントで、同一ディレクトリに参考資料やスクリプトを同梱できます。SKILL.mdからは相対パスで参照します。
## 参考資料
- API仕様の詳細は [reference.md](reference.md) を参照
- 出力例は [examples/sample.md](examples/sample.md) を参照
動的コンテキスト注入
Skills形式では!`コマンド``構文を使い、シェルコマンドの実行結果をプロンプトに埋め込めます。
---
name: pr-review
description: PRの変更内容をレビュー
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
## PRの情報
- 差分: !`gh pr diff`
- コメント: !`gh pr view --comments`
- 変更ファイル: !`gh pr diff --name-only`
## レビュー方針
上記の差分を分析し、バグ・設計上の問題・改善点を報告してください。
Claudeがプロンプトを受け取る前に!`…``の部分がシェル実行され、その結果に置換されます。GitHub CLIやgitコマンドの出力を直接コンテキストに含められるため、事前に手動でコピーする必要がありません。
サブエージェントとの連携
front matterにcontext: forkを指定すると、カスタムコマンドをサブエージェント内で実行できます。メイン会話のコンテキストとは分離されるため、大量のファイル分析などでコンテキストウィンドウを圧迫しません。
---
name: deep-research
description: コードベースを徹底調査
context: fork
agent: Explore
---
$ARGUMENTS に関連するコードを徹底的に調査してください。
1. Glob・Grepでファイルを特定
2. コードを読み込み、構造を分析
3. 発見事項をファイルパスとともにまとめる
agentフィールドにはExplore（読み取り専用の高速調査）、Plan（設計立案）、general-purpose（全ツール利用可）のほか、.claude/agents/に定義したカスタムサブエージェントも指定できます。
CLAUDE.md・カスタムコマンド・Hooks・Skillsの使い分け
Claude Codeには指示を与える仕組みが複数あります。目的に応じて適切な手段を選ぶことが重要です。
| 仕組み | 適した用途 | 実行タイミング |
|---|---|---|
| CLAUDE.md | コーディング規約・プロジェクト構成など常時適用するルール | セッション開始時に自動読み込み |
| カスタムコマンド / Skills | 特定のワークフロー（レビュー、テスト生成、PR作成など） | ユーザーが/で明示実行、またはClaude判断で自動実行 |
| Hooks | ツール実行前後のバリデーションやログ取得 | ツール呼び出し時に自動実行 |
| サブエージェント | 専門分野に特化した処理の委任 | Claude判断またはSkillsから呼び出し |
判断基準の目安:
- 常に適用したいルール → CLAUDE.md
- 手動で繰り返し実行する定型作業 → カスタムコマンド（
disable-model-invocation: true） - Claudeに状況判断で使わせたい知識 → Skills（
user-invocable: false） - ツール実行のたびに自動チェック → Hooks
- 大量処理をメインコンテキストと分離 → サブエージェント（
context: fork）
運用を安定させるためのTips
namespace（名前空間）で管理する
コマンドが増えてきたら、ディレクトリ階層で分類します。
.claude/commands/
├── git/
│ ├── commit.md
│ ├── create-branch.md
│ └── create-pr.md
├── review/
│ ├── security.md
│ └── performance.md
└── gen/
├── test.md
└── component.md
呼び出しは/git:commit、/review:securityのように名前空間付きになります。補完も効くため、コマンド名を暗記する必要はありません。
命名規則を統一する
チームで運用する場合、命名ルールをあらかじめ決めておくと混乱を防げます。
- 動詞＋対象の形式:
create-pr、gen-test、check-security - 数字プレフィックスで実行順を示す:
01-fix-issue、02-create-pr、03-address-review
数字プレフィックスを使うと/01のように入力するだけで補完され、ワークフローの順番も一目でわかります。
コマンド内で別コマンドを呼ばない
カスタムコマンドの内部から別のカスタムコマンドを呼び出すと、内側のコマンドが完了した時点でClaudeがユーザー入力待ちになることがあります。処理の連鎖が必要な場合は、1つのコマンドに手順をまとめるか、Read @構文で別ファイルの内容を参照する方法が安定します。
## 実行手順
1. Read @~/.claude/commands/guidelines.md の内容に従いチェック
2. 問題がなければコミットを実行
スクリプト生成の有無を制御する
Claudeはプロンプトの内容に応じて一時スクリプトを生成し実行することがあります。実行のたびに結果がばらつく原因になるため、安定性が求められるコマンドでは制御が必要です。
- スクリプトを使わせたくない場合: コマンド内に「スクリプトファイルを作成せず、直接処理を行うこと」と明記
- スクリプトを使わせたい場合: スクリプトをSkillsのサポートファイルとして同梱し、パスを明示
よくあるトラブルと対処法
コマンドが/メニューに表示されない
.claude/commands/のパスが正しいか確認（プロジェクトルートからの相対パス）- ファイル拡張子が
.mdであるか確認 - Skillsが多すぎてキャラクター予算を超えている場合、
/contextで警告が表示される。環境変数SLASH_COMMAND_TOOL_CHAR_BUDGETで上限を変更可能
Claudeが意図しないタイミングでコマンドを自動実行する
descriptionの文言をより限定的にするdisable-model-invocation: trueを設定し、手動実行のみに限定する
サブエージェント実行時に結果が不十分
context: forkはメイン会話のコンテキストを引き継がないため、SKILL.md内に必要な情報をすべて含める- ガイドライン的な内容だけでタスク指示がない場合、サブエージェントは何もせず終了する
まとめ
.claude/commands/にMarkdownファイルを1つ配置するだけで、繰り返しのプロンプト入力をスラッシュコマンドに置き換えられます。front matterによるツール制御や引数の受け渡し、Skills統合によるサブエージェント連携まで、用途に合わせて段階的に活用の幅を広げられます。
まずは日常的に繰り返しているプロンプトを1つ選び、.claude/commands/に.mdファイルとして保存するところから始めてみてください。
カスタムコマンドの公式ドキュメントはClaude Code Skillsで確認できます。