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

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

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

この記事でわかること

• スラッシュコマンドの基本と、ビルトイン／カスタムの違い
• 2026年1月のSkills統合で何が変わったか、旧形式と新形式のどちらで書くべきか
• .claude/commands/ と .claude/skills/SKILL.md の作り方を具体的な手順で（最小サンプル付き）
• フロントマター全フィールド・引数プレースホルダー・! によるBash実行・@ によるファイル参照の完全リファレンス
• そのままコピペで使える実務テンプレート6選（/commit・/pr-summary・/review・/test・/refactor・/docs）
• 呼び出し制御（disable-model-invocation / user-invocable）とセキュリティ上の推奨設定
• Skill / サブエージェント / フック / プラグインの使い分け
• うまく動かないときのトラブルシュート

誰向けの記事か

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

スラッシュコマンドとは（現時点の事実）

スラッシュコマンドは、Claude Code のプロンプト入力欄で / から始めて実行する機能です。用途は大きく2種類に分かれます。

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

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

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

【重要】2026年1月のSkills統合で何が変わったか

2026年1月のアップデートで、カスタムスラッシュコマンドはスキル（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.

要点は3つです。

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

旧形式と新形式の違い

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

これから新規で作るなら、.claude/skills/<name>/SKILL.md が第一選択肢です。 旧資産の移行は後ほど解説します。

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

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

手順

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          # ← 必須。本体
│   ├── examples.md       # ← サポート（Claudeが必要に応じて読む）
│   └── template.txt
└── deploy/
    └── SKILL.md

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

保存場所と優先順位

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

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

モノレポの場合は packages/frontend/.claude/skills/ のようなサブパッケージ内のスキルも自動検出されます。

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

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

最小限で書くなら description だけでOKです。 副作用がある操作は disable-model-invocation: true を足す、外部ツールを使うなら allowed-tools を足す、と段階的に加えます。

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

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

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

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

! で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
```

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

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

@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

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

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

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

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

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

サブエージェントを本格的に使う場合は、Claude Code のサブエージェント機能そのものを知っておく必要があります（詳細は別記事で整理予定）。

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

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

1. /commit — 現在のステージングをAIがコミットメッセージ化

---
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/ にコミットすればチーム全体で共有できます。ただし、機密情報（トークン・内部エンドポイント）を本文に直接書かないよう注意してください。

ビルトインコマンド主要一覧

/help で全覧を出せますが、よく使うものをカテゴリで整理します（2026年4月時点）。

基本

モデル・思考予算

プロジェクト運用

拡張機能

バンドルスキル（デフォルトで入っている Skill）

バンドルスキルは頻繁に追加されます。最新の一覧は /skills または /release-notes で確認してください。/vim は v2.1.92 で、/pr-comments は v2.1.91 で削除済みなど、バージョン差分があります。

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

2025年頃に .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
• 「副作用が重い／コンテキストを汚したくない」→ サブエージェント
• 「ユーザーが忘れても自動で走らせたい」→ 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 *) で個別制御

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

こんな人におすすめ

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

おすすめしない人

• 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文字で切り詰め
• SLASH_COMMAND_TOOL_CHAR_BUDGET 環境変数で拡張可能
• 似た用途のスキルは1つに集約

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

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

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

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

SDKで /clear が効かない

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

よくある質問（FAQ）

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

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

Q2. ビルトインコマンドと同名のカスタムは作れますか？

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

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

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

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

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

Q5. Windows でも使えますか？

使えます。! 構文のシェルを PowerShell にしたい場合はフロントマターに shell: powershell を指定します。

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

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

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

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

まとめ

• .claude/commands/<name>.md にMarkdown1枚を置けば /name が使える
• 2026年1月のアップデートでカスタムコマンドはスキルにマージ。新規は .claude/skills/<name>/SKILL.md が推奨
• フロントマター（description / allowed-tools / disable-model-invocation）で自動起動と権限を制御
• 引数は $ARGUMENTS / $N / 名前付き、! でシェル、@ でファイルを差し込める
• 副作用のあるコマンドは disable-model-invocation: true を必ず付ける
• 旧形式は互換維持だが、新規は新形式で書く。既存資産は段階的に移行する

関連記事：

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