Claude Code スラッシュコマンド 作り方｜.claude/commands カスタムコマンド完全ガイド【2026年最新版】

.claude/commands/<name>.md にMarkdownを1枚置くだけで /name として使えます。 ただし2026年のアップデートで、カスタムスラッシュコマンドはスキル（Skills）機能に統合されました。現行の公式推奨は .claude/skills/<name>/SKILL.md 形式です（旧形式も引き続き動作します）。

この記事では、Claude Code のカスタムスラッシュコマンドを実務で使える状態まで作り切るために必要な情報を、公式ドキュメント（code.claude.com/docs/en/skills）ベースでまとめます。

この記事でわかること

• スラッシュコマンドの3分類（組み込み・バンドルスキル・カスタム）と違い
• Skills統合で何が変わったか、旧形式と新形式のどちらで書くべきか
• .claude/commands/ と .claude/skills/SKILL.md の作り方を具体的な手順で（最小サンプル付き）
• フロントマター全フィールド・引数プレースホルダー・! によるBash実行・@ によるファイル参照の完全リファレンス
• そのままコピペで使える実務テンプレート6選（/commit・/pr-summary・/review・/test・/refactor・/docs）
• 呼び出し制御（disable-model-invocation / user-invocable）と skillOverrides 設定
• 2026年5月時点の組み込みコマンド最新一覧（/background・/goal・/ultrareview・/run など新規追加分を含む）
• ライブ変更検出とスキルのコンテキストライフサイクル
• うまく動かないときのトラブルシュート（/doctor の使い方含む）

誰向けの記事か

• Claude Code を日常的に使っていて、よく使うプロンプトを1コマンド化したいエンジニア
• .claude/commands/ で書いた資産を新形式（Skills）へ移行したい開発チーム
• チーム内で /commit や /review のような共通ワークフローをGit管理で配布したいリード

Claude Code 本体の全体像を先に掴みたい場合は、Claude Codeとは｜料金・使い方・Cursorとの違い を読んでおくと理解が早くなります。

スラッシュコマンドとは（3種類の整理）

出典: Anthropic（claude.com）

スラッシュコマンドは、Claude Code のプロンプト入力欄で / から始めて実行する機能です。メッセージの先頭でのみ認識され、コマンド名に続くテキストは引数として渡されます。現時点では大きく3種類に分かれます。

組み込みコマンドは削除・追加できませんが、カスタムスキルは Markdown 1枚で作れます。カスタムコマンド／スキルは Claude Code の全プラン（Free / Pro / Max / Team / Enterprise）で追加料金なしで利用可能です。

プラン・プラットフォームによって表示される組み込みコマンドは異なります。たとえば /upgrade や /privacy-settings は Pro / Max 限定、/desktop は macOS / Windows のみです。

【重要】Skills統合で何が変わったか

2026年のアップデートで、カスタムスラッシュコマンドはスキル（Skills）機能に統合されました。公式ドキュメントには次のように明記されています。

Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Your existing .claude/commands/ files keep working.

1. 旧形式 .claude/commands/<name>.md は引き続き動作する（互換維持）
2. 新規作成の公式推奨は .claude/skills/<name>/SKILL.md ディレクトリ形式
3. 同名コマンドがある場合は Skill 形式が優先される

旧形式と新形式の違い

Claude Code のスキルは Agent Skills オープンスタンダード（agentskills.io） に準拠しており、他のAIツールとも互換性があります。Claude Code はこれに呼び出し制御・サブエージェント実行・動的コンテキスト注入といった拡張機能を足しています。

これから新規で作るなら、.claude/skills/<name>/SKILL.md が第一選択肢です。

カスタムコマンドの作り方（旧形式：.claude/commands/）

出典: Anthropic

まずは一番シンプルな旧形式から押さえます。既存プロジェクトの資産を理解するときにも役立ちます。

手順

1. プロジェクトルートに .claude/commands/ ディレクトリを作成
2. <コマンド名>.md を追加
3. そのままプロンプトを本文に書く

最小サンプル：

<!-- .claude/commands/hello.md -->
Hello world と日本語で返事してください。

この1ファイルを置くだけで、Claude Code セッション内で /hello が使えるようになります。ファイル名（.md を除く）がそのままコマンド名です。

保存場所の違い（プロジェクト vs ユーザー）

チーム共有したいコマンド（デプロイ・コミット・PR要約など）はプロジェクト配下に置いてGitにコミット、個人の検索・要約ユーティリティはユーザー配下に置く、が基本方針です。

カスタムスキルの作り方（新形式：.claude/skills/SKILL.md）

2026年以降の公式推奨はこちらです。ディレクトリ形式になることで、サポートファイル（テンプレート・参考コード）を同梱できる・呼び出し制御ができる、といったメリットが得られます。

手順

1. .claude/skills/<コマンド名>/ ディレクトリを作成
2. そのなかに SKILL.md を必須ファイルとして置く
3. 必要ならテンプレートや参考ファイルを同じディレクトリに追加

最小サンプル：

<!-- .claude/skills/hello/SKILL.md -->
---
name: hello
description: 日本語で挨拶を返す。挨拶系の軽い動作確認に使う。
---

Hello world と日本語で返事してください。

これで /hello が使えるうえに、description に書いた条件に合致する文脈で Claude が自動起動する候補にもなります。

ディレクトリ構造（サポートファイルの活用）

.claude/skills/
├── commit/
│   ├── SKILL.md          # ← 必須。本体（500行以内を推奨）
│   ├── examples.md       # ← サポート（Claudeが必要に応じて読む）
│   └── template.txt
└── deploy/
    └── SKILL.md

サポートファイルは SKILL.md 本文から @examples.md のように参照すれば、必要になったタイミングでのみ読み込まれます。SKILL.md 自体は500行以下を目安に保ち、詳細はサポートファイルに分割するのが推奨されます。

保存場所と優先順位（4スコープ）

スキル／カスタムコマンドは4つのスコープが存在します。

優先順位：Enterprise > Personal > Project。プラグインは plugin-name:skill-name の名前空間を持つため、ユーザー定義と名前衝突しません。

モノレポ対応： packages/frontend/.claude/skills/ のようなサブパッケージ内のスキルも自動検出されます。開始ディレクトリからリポジトリルートまで遡る各ディレクトリの .claude/skills/ が全て読み込まれます。

フロントマター完全リファレンス

SKILL.md（または .claude/commands/<name>.md）の先頭に --- で囲んで記述するYAMLメタデータです。すべてオプションですが、description は Claude が自動起動するかどうかを判断する根拠になるため、実務では必ず書きます。

最小限で書くなら description だけでOKです。 副作用がある操作は disable-model-invocation: true を足す、外部ツールを使うなら allowed-tools を足す、特定ファイル種類にのみ反応させたいなら paths を足す、と段階的に加えます。

paths フィールドの活用（モノレポ向け）

paths を指定すると、特定のファイルパターンに一致するファイルを編集しているときだけスキルが自動起動候補になります。TypeScriptファイルの編集中のみ型チェック用スキルを起動したい、など不意のスキル発火を防ぐのにも有効です。

---
name: ts-check
description: TypeScript型エラーを確認する
paths: "src/**/*.ts"
---

引数と文字列置換（プレースホルダー）

/my-command "hello world" branch-a のように渡した引数は、本文中で次の変数で受け取れます。

複数単語の引数はシェル風にクォートで囲めます。/my-skill "hello world" second なら $0 = "hello world"、$1 = "second" です。

本文に $ARGUMENTS が一切書かれていない場合、Claude Code は末尾に自動で ARGUMENTS: <入力> を付けてくれます。

名前付き引数の例

---
name: migrate-component
arguments: [component, from-framework, to-framework]
---
$component を $from-framework から $to-framework に移行してください。

/migrate-component SearchBar React Vue と入力すると、$component = "SearchBar", $from-framework = "React", $to-framework = "Vue" として展開されます。

! でBashコマンドを埋め込む（動的コンテキスト注入）

本文に !`command` と書くと、プロンプト送信前にシェルコマンドが実行され、その出力が本文にそのまま埋め込まれます。

## Pull Request Context
- PR diff: !`gh pr diff`
- Comments: !`gh pr view --comments`

## Your task
上記の PR を3行で要約してください。

重要なポイントは、この ! はClaudeが実行しているわけではないことです。ローカルシェルが走り、結果だけがClaudeに渡ります。gh や git の認証情報を持ったまま実行されます。

複数行を流したい場合は、```! で始まるフェンスドコードブロックを使います。

```!
git log --oneline -n 10
git status --short
node --version
```

! 実行を無効化したい場合は、設定で "disableSkillShellExecution": true を指定します（企業の管理設定で強制適用可）。

制約： !`command` は行頭または空白の直後にのみ有効。また処理は一度のみ（コマンド出力の中にさらに ! があっても展開されない）。

@ でファイル内容を差し込む

@package.json や @src/auth/login.ts のようにファイルパスを @ 付きで書くと、そのファイル内容がプロンプトに埋め込まれます。

以下の設計ドキュメントを要件として、@src/auth/login.ts をレビューしてください。

@docs/auth-spec.md

! が「シェルコマンドの出力埋め込み」なのに対し、@ は「ファイルそのものの内容埋め込み」と覚えると混乱しません。

呼び出し制御（disable-model-invocation / user-invocable）

同じ「コマンド」でも、誰が起動するのかを細かく制御できます。

実務での推奨

• デプロイ・コミット・DB書き込み・Slack送信など「勝手に走ったら困る」操作は disable-model-invocation: true
• コンテキスト要約・テスト生成など「勝手にやってくれた方が嬉しい」操作は既定のまま
• 内部ツール的に Claudeにだけ使わせたい 特殊スキルは user-invocable: false

skillOverrides でスキルの可視性を設定から制御

スキルが増えてくると、不要なものを / メニューから非表示にしたくなります。/skills メニューで Space を押して可視性をサイクル → Enter で設定を保存することで、.claude/settings.local.json に自動書き込みされます。

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

スキルの説明がコンテキストを圧迫している場合は、低優先スキルを "name-only" に設定するとバジェットを節約できます。

サブエージェント実行（context: fork）

重い調査タスクは、メイン会話とコンテキストを分けてサブエージェントに委ねるのが有効です。

---
name: deep-research
description: 指定トピックをリポジトリ全体から徹底調査する
context: fork
agent: Explore
---

$ARGUMENTS について徹底調査してください。
1. Glob / Grep で関連ファイルを洗い出す
2. コードを読み込み、具体的なファイル参照付きで要約する

• context: fork を指定すると、そのスキルは分離されたサブエージェントコンテキストで実行されます
• agent で Explore（探索特化）、Plan（計画）、general-purpose（汎用）などを選択
• メイン会話のトークンを節約しつつ、深い調査を並行して走らせられます

注意： context: fork は具体的なタスク指示が必要です。「このAPIの規約に従う」等のガイドラインのみでは機能しません。

ライブ変更検出とスキルのコンテキストライフサイクル

ライブ変更検出（再起動不要）

~/.claude/skills/ や .claude/skills/ 配下のスキルをセッション中に追加・編集・削除すると再起動なしで即時反映されます。

ただし例外があります：セッション開始時点でトップレベルの skills ディレクトリが存在しなかった場合のみ、セッション再起動が必要です。既存ディレクトリ内のファイル変更は再起動不要。

スキルのコンテキストライフサイクル

スキルを呼び出すと SKILL.md の内容が1つのメッセージとしてセッションに追加され、セッション終了まで残ります。Claude Code は後のターンでスキルファイルを再読み込みしません（内容は会話履歴の一部として存在します）。

自動コンパクション時の挙動：

• 各スキルの最新呼び出し分（最大5,000トークン）を再アタッチ
• スキル合計で25,000トークンの共有バジェット
• 最近呼び出したスキルほど優先的にバジェットを確保（古いスキルは省略される場合あり）
• コンパクション後にスキルが効かなくなった場合は再呼び出しで復元可能

実務で使えるテンプレート6選（コピペ可）

実際に開発で使える最小セットです。.claude/skills/<name>/SKILL.md として配置してください。

1. /commit — ステージング済み差分をConventional Commitsでコミット

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

## 現在の状態
- ステージ済み: !`git diff --cached --stat`
- 差分本体: !`git diff --cached`

## タスク
上記の差分から Conventional Commits（`feat:` / `fix:` / `chore:` / `docs:` / `refactor:` / `test:`）
のフォーマットで、1〜2文のコミットメッセージを作成してください。
作成したら `git commit -m "..."` を実行してください。

2. /pr-summary — PR差分を3行要約

---
name: pr-summary
description: GitHub の現在ブランチの PR を3行で要約する。レビュー依頼前に実行する。
argument-hint: "[pr-number]"
---

## PRの情報
- 基本情報: !`gh pr view $ARGUMENTS --json title,body,commits`
- 差分: !`gh pr diff $ARGUMENTS`

## タスク
この PR を
1. 何を
2. なぜ
3. どう実装したか
の3行で要約してください。

3. /review — 差分の自動コードレビュー

---
name: review
description: 未コミット差分のコードレビュー。ロジック・エラーハンドリング・命名・テストの観点で指摘する。
---

## レビュー対象
!`git diff HEAD`

## タスク
以下の観点で指摘してください（指摘が無い観点はスキップしてOK）：
- ロジックバグ・境界条件
- エラーハンドリングの抜け
- 命名の一貫性
- テストカバレッジの不足
- セキュリティ（入力バリデーション・権限・秘匿情報）
最後に**修正が必要な箇所だけ**をファイル名・行番号付きで箇条書きしてください。

4. /test — テスト追加の提案と生成

---
name: test
description: 指定ファイルのユニットテストを作成する。Vitest / Jest / Pytest を自動判別する。
argument-hint: "[file-path]"
---

## 対象ファイル
@$ARGUMENTS

## プロジェクト設定
- package.json: @package.json

## タスク
1. 上記ファイルの主要な関数・クラスを抽出
2. 正常系・異常系・境界値の3観点でテストケースを設計
3. プロジェクトのテストフレームワークに合わせてテストコードを新規作成

5. /refactor — リファクタリング提案

---
name: refactor
description: 指定ファイルを読み、責務分割・命名・重複排除の観点でリファクタリング案を出す。
argument-hint: "[file-path]"
---

## 対象
@$ARGUMENTS

## タスク
- 責務が混ざっている箇所を指摘
- 抽出すべき関数・クラス候補を提示
- 命名改善の提案
まずは差分を出さず**改善案のサマリ**だけ提示してください。承認後に差分を作成します。

6. /docs — README / API ドキュメント更新

---
name: docs
description: 最近の差分を元に README・docs/ を更新する。破壊的変更があれば冒頭で警告する。
---

## 直近の差分
!`git log --since="1 week ago" --oneline`
!`git diff main...HEAD -- README.md docs/`

## 現状
@README.md

## タスク
- 新機能・API変更があれば README と docs/ に反映
- 破壊的変更は**冒頭で警告**
- 変更点は既存の書式を踏襲

これらはすべて .claude/skills/ にコミットすればチーム全体で共有できます。機密情報（トークン・内部エンドポイント）を本文に直接書かないよう注意してください。

組み込みコマンド主要一覧【2026年5月時点】

/help で全覧を出せますが、用途別に整理します。コマンドの可用性はプラットフォーム・プラン・バージョンによって異なります。

セッション管理・コンテキスト

ワークフロー・エージェント・並列処理

コードレビュー・品質

アプリ実行・検証（v2.1.145 以上必要）

モデル・設定

プロジェクト設定・メモリ

情報・診断

スキル・拡張機能管理

リモート・クロスデバイス

チーム・エンタープライズ運用

MCPプロンプト： MCPサーバーが公開するプロンプトは /mcp__<server>__<prompt> 形式でコマンドとして使用可能です。

廃止済み（注意）

バンドルスキルは頻繁に追加されます。最新の一覧は /skills または /release-notes で確認してください。

旧形式から新形式への移行ガイド

.claude/commands/ を整備済みのチーム向けです。

移行手順

1. .claude/commands/<name>.md → .claude/skills/<name>/SKILL.md にディレクトリごと移動
2. フロントマターに name と description を追加（元ファイルに無ければ）
3. 副作用があるコマンドは disable-model-invocation: true を付与
4. 外部ツール呼び出しがあれば allowed-tools で事前承認するツールを列挙
5. テンプレート・長文の参考資料は SKILL.md から切り出してサポートファイル化
6. /skills で新形式が検出されることを確認

.claude/commands/ 側は残したままでも動作しますが、同名があれば Skill 優先なので新旧を重複させないよう注意してください。段階的に旧形式を削除していくのが安全です。

拡張思考の起動（ultrathink）

スキル本文のどこかに「ultrathink」という単語を含めると、Extended Thinking モードが有効化されます。調査・設計・レビューなど長考させたい場面に有効です。

---
name: plan-feature
description: 新機能の実装計画を長考して作る
effort: high
---

ultrathink

$ARGUMENTS の実装計画を以下の観点で作成してください：
- 影響範囲
- 実装ステップ
- 想定リスク
- 必要なテスト

effort: max と併用すると、さらに予算を積み増しできます。

Skill / サブエージェント / フック / プラグインの使い分け

Claude Code の拡張機能はスラッシュコマンド以外にもあり、似て非なるものが並んでいます。

選び方の原則：

• 「毎回同じプロンプトを打ちたい」→ Skill
• 「副作用が重い／コンテキストを汚したくない」→ サブエージェント（context: fork）
• 「ユーザーが忘れても自動で走らせたい」→ Hooks（例：devサーバー起動検知、コード保存後のレビュー）
• 「上記を他チーム／社外に配布したい」→ Plugin

フックでスキルを呼ぶ、スキルからサブエージェントを立てる（context: fork）など、組み合わせ運用が現場では一般的です。

セキュリティ・運用上の注意点

スラッシュコマンドは便利な一方、本文にシェル実行と外部APIコールが書けるため、共有・運用時のリスク管理が必要です。

1. allowed-tools は最小権限で — 列挙したツールは承認ダイアログなしで走る。必要なツールだけを指定する
2. 副作用のあるコマンドは disable-model-invocation: true — Claudeが勝手に /deploy を走らせるのを防ぐ
3. 機密情報を本文に直書きしない — .claude/skills/ はGitにコミットされ、チーム全員に配布される
4. 管理設定で ! 実行を無効化可能 — "disableSkillShellExecution": true を組織設定で強制
5. /permissions でスキル自体を拒否可能 — Skill ツールを拒否、または Skill(name) / Skill(name *) で個別制御
6. プロジェクトスキルのtrustに注意 — .claude/skills/ のスキルは、ワークスペーストラストダイアログ受け入れ後に allowed-tools が有効化される。信頼しないリポジトリはレビュー前に trust しない

AIコーディング全般のセキュリティ設計については、AIコーディング セキュリティ リスクと対策 を組織展開前に合わせて確認してください。

こんな人におすすめ

• 同じプロンプトを毎日打っている（要約・レビュー・コミットメッセージ作成など）
• チームで /commit や /review を標準化して品質を揃えたい
• モノレポで パッケージごとの固有ワークフローを配布したい
• .claude/commands/ 資産を 新形式（Skills）へ整理したい
• フック・サブエージェントと組み合わせて 独自の開発パイプラインを作りたい

おすすめしない人

• Claude Code をまだ常用していない（先に日常ワークフローを作ってからでOK）
• 1回限りのタスクをスキル化しようとしている（ノーマルプロンプトで十分）
• 認証情報・本番デプロイを制御なしでスキル化しようとしている（disable-model-invocation と allowed-tools の設計を先にする）

トラブルシュート

コマンドが / メニューに出ない

• .md ファイル名に大文字やアンダースコアが入っていないか確認（小文字・数字・ハイフンのみ）
• 保存場所が .claude/commands/ か .claude/skills/<name>/SKILL.md になっているか
• セッション開始時点でトップレベルの skills ディレクトリが存在しなかった場合は、セッション再起動が必要
• Enterprise 設定で該当スキルが拒否されていないか /permissions で確認

Claudeが勝手に起動してしまう

• description に「いつ使うか」を具体的に書く（曖昧だと自動起動が暴発する）
• 副作用がある場合は disable-model-invocation: true を指定

スキルが多すぎて description が切り詰められる

• description + when_to_use の合計は 1,536文字で切り詰め
• /doctor コマンドでスキルのバジェットオーバーフローを確認
• skillListingBudgetFraction 設定（例：0.02 = コンテキストウィンドウの 2%）でバジェットを増加
• 環境変数 SLASH_COMMAND_TOOL_CHAR_BUDGET でも拡張可能
• 似た用途のスキルは1つに集約

セッション中に編集したのに反映されない

• スキル本体は再読込されない（セッション中に一度呼び出すと会話に挿入される）
• 再反映したいときは、もう一度 /<name> で呼び出し直す
• トップレベルの skills ディレクトリを新規作成した場合は再起動が必要

長時間セッションで古いスキルが消える

• コンパクション後のスキル保持は各5,000トークン／合計25,000トークンまで
• 古いスキルは保持対象から外れる可能性あり。再度呼び出せば復帰する

SDKで /clear が効かない

• SDKでは /clear は使えない。query() を再起動するか、resume オプションでセッションIDを指定する

よくある質問（FAQ）

Q1. .claude/commands/ はいつ非推奨になりますか？

公式は2026年5月時点で「引き続き動作する」と明記しているだけで、廃止時期は示されていません。ただし新形式（SKILL.md）が推奨である以上、新規は新形式で作り、既存は計画的に移行するのが安全です。

Q2. 組み込みコマンドと同名のカスタムは作れますか？

組み込みの /help や /clear などを上書きすることはできません。カスタム側の名前を変えてください。

Q3. スキルのサポートファイルはトークンを消費しますか？

SKILL.md は起動時に読み込まれますが、サポートファイルは @filename で参照されたときに初めて読まれます。長い参考資料は分割しておくとトークン効率が良くなります。

Q4. description に日本語を書いても自動起動は効きますか？

効きます。ただし Claude が自動起動判断に使う項目なので、どういうときに呼ぶべきかを動詞＋名詞で具体的に書くのがコツです。「〜を要約する」「〜を生成する」のような能動的な記述が無難です。

Q5. Windows でも使えますか？

使えます。! 構文のシェルを PowerShell にしたい場合はフロントマターに shell: powershell を指定します。環境変数 CLAUDE_CODE_USE_POWERSHELL_TOOL=1 の設定が必要になる場合があります。

Q6. プラグインのスキルと自作スキルが同名だと？

プラグイン側は plugin-name:skill-name の名前空間を持つため、ユーザー定義と名前衝突しません。同じ /deploy でも、プラグインのものは plugin-name:deploy として区別されます。

Q7. 企業で一括管理したい

Enterprise 設定で管理パスを指定すれば、組織の全ユーザーに強制適用できます。シェル実行の一括無効化（"disableSkillShellExecution": true）も可能です。

Q8. /run や /verify が表示されません

v2.1.145 以上が必要です。/status でバージョンを確認し、古い場合はアップデートしてください。

まとめ

• .claude/commands/<name>.md にMarkdown1枚を置けば /name が使える（旧形式・互換維持）
• 2026年のアップデートでカスタムコマンドはスキルに統合。新規は .claude/skills/<name>/SKILL.md が推奨
• フロントマター（description / allowed-tools / disable-model-invocation / paths）で自動起動・権限・対象ファイルを制御
• 引数は $ARGUMENTS / $N / 名前付き、${CLAUDE_EFFORT} / ${CLAUDE_SKILL_DIR} などの特殊変数も利用可能
• ! でシェル動的注入、@ でファイルをプロンプトに差し込める
• 副作用のあるコマンドは disable-model-invocation: true を必ず付ける
• skillOverrides で /skills の可視性を設定ファイルから細かく制御可能
• 2026年5月時点で組み込みコマンドは大幅拡張。/background・/goal・/ultrareview・/run（v2.1.145+）など新機能が続々追加されている
• 旧形式は互換維持だが、新規は新形式で書く。既存資産は段階的に移行する

関連記事：

• Claude Codeとは｜料金・使い方・Cursorとの違い
• Claude Code 使い方ガイド
• Claude Code 料金プラン徹底解説
• AIコーディング セキュリティ リスクと対策
• AIコーディングツール おすすめ比較