Claude Code のスラッシュコマンドを使いたいが、検索すると古い .claude/commands の話と新しい skills の話が混ざっていて分かりにくい。/loop や /review のような built-in を使うだけなら困らなくても、自分で /deploy や /review-pr を作ろうとした瞬間に、どこへ置くべきか、何を frontmatter に書くべきか、MCP prompts と何が違うのかで止まりやすいです。
この記事は、Claude Code でスラッシュコマンドを実務投入したい人向けの整理です。結論から言うと、今の Claude Code では「custom slash commands は skills に統合されたが、.claude/commands もまだ動く」という状態です。導入初日の全体像は Claude Code の使い方 実践ガイド、プロジェクト文脈の固定は CLAUDE.md の書き方 設計パターン集、外部接続は Claude Code MCP ガイド、強制ルール化は Claude Code Hooks ガイド に分けています。今回はその間にある「手元の手順を slash command としてどう定着させるか」に絞ります。
先に結論: まずは 3 種類に分けて考える
Claude Code で「スラッシュコマンド」と呼ばれがちなものは、実際には次の 3 種類あります。
- built-in commands
/help、/compact、/mcpのように CLI 自体に実装されているもの
- project / personal commands or skills
- あなたが
.claude/commands/や.claude/skills/に置くもの
- あなたが
- MCP prompts
- MCP server が公開し、
/mcp__servername__promptnameで見えるもの
- MCP server が公開し、
ここを混ぜると設計が崩れます。私なら次の基準で決めます。
| やりたいこと | 置き場 |
|---|---|
| 自分やチームの定型プロンプトを最短で再利用したい | .claude/commands/ または .claude/skills/ |
| 長い手順、補助ファイル、subagent 連携まで持たせたい | .claude/skills/ |
| GitHub や Jira など接続先 server が持つ workflow を使いたい | MCP prompts |
今の docs では、custom commands は skills に統合されています。つまり、新しく育てるなら skills を本命にしつつ、最短導入では .claude/commands もまだ実用という理解で十分です。
.claude/commands はまだ使ってよいのか
はい。少なくとも現行 docs では、.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md は同じ /deploy を作れます。既存の .claude/commands ファイルも引き続き動きます。
ただし、ここで無理に「全部 commands で統一する」と決める必要はありません。私の基準は次のとおりです。
.claude/commands が向くケース
- まず 1 ファイルで試したい
- チームに「とりあえずこの手順を slash command 化しよう」と共有したい
- 自動発火は不要で、手動で
/nameを打てれば十分
.claude/skills が向くケース
- command 本文が長くなってきた
- 参考ファイルやテンプレートを同梱したい
- 自動適用や subagent 実行まで含めたい
- 将来的に project knowledge と reusable workflow を分けたい
このサイト運用でも、短い workflow を一度試す段階では command 形式の方が速いです。一方で、レビュー手順、記事生成、監査チェックのように毎回同じ文脈を大量に読み込ませるものは skills に寄せた方が管理しやすくなります。
最短の作り方: project command を 1 本置く
最初は project scope で十分です。リポジトリにだけ効く slash command を 1 本作ります。
mkdir -p .claude/commandsたとえば PR レビューの定型を command 化するなら、.claude/commands/review-pr.md を置きます。
---
description: Review a pull request with this repository's rules
argument-hint: [pr-number]
arguments: [pr]
disable-model-invocation: true
allowed-tools:
- Read
- Grep
- Bash(git status *)
---
Review pull request #$pr in this repository.
Focus on:
- behavioral regressions
- missing tests
- security or permission risks
- mismatches with local repository conventionsこれで /review-pr 123 のように呼べます。ここで大事なのは、command 名より description の方が重要だという点です。Claude Code は description を使って候補表示や自動読み込み判断を行うため、何をする command かを最初に短く言い切った方が安定します。
引数と frontmatter はどこまで使うべきか
今の skills/docs ベースで押さえるべき frontmatter は多くありません。実務でまず使うのは次の 6 つです。
| 項目 | 役割 |
|---|---|
description | 何をする command / skill か |
argument-hint | 補完時に期待引数を見せる |
arguments | 名前付き引数を宣言し $name で参照する |
disable-model-invocation | Claude の自動発火を止める |
allowed-tools | その command 実行中に使ってよい tool を絞る |
model | 特定 workflow だけモデルを変えたいときに使う |
引数は $ARGUMENTS 一発でも動きますが、私は 2 つ以上あるなら名前付きにします。後で読み返したときの事故が減るからです。
---
description: Prepare a release note from a target range
argument-hint: [from-ref] [to-ref]
arguments: [from, to]
disable-model-invocation: true
---
Summarize the changes from $from to $to and draft a release note.$ARGUMENTS は速いですが、長く生きる command ほど $from や $to の方が保守しやすいです。
command に向くもの、Hooks に向くもの、CLAUDE.md に向くもの
ここを間違えると、せっかく command を作っても使われません。
command に向くもの
- 手動で明示的に呼びたい手順
- 1 回の依頼として独立している作業
- 引数付きで何度も再利用する workflow
例:
/review-pr 123/release-note main HEAD/seo-check src/content/blog/foo.md
Hooks に向くもの
- 毎回必ず走らせたい強制ルール
- 書き込み前の検証
- レビューや commit 前のガードレール
例:
- 編集後に
pnpm run buildを必ず促す - 危険コマンド前に確認を入れる
これは Claude Code Hooks ガイド の領域です。手動 command と強制フックを混ぜると、実行責務が曖昧になります。
CLAUDE.md に向くもの
- プロジェクト固有の前提知識
- よく使うコマンドの一覧
- 禁止事項や設計方針
CLAUDE.md は「毎回読むべき事実」、slash command / skill は「必要時だけ呼ぶ手順」と分けるのが基本です。ここを一緒にすると、CLAUDE.md が肥大化してノイズになります。
! と @ を使うと command は実用レベルになる
ただの定型プロンプトだと、手打ちと大差ありません。実務で効くのは、今の repository 状態をその場で注入できることです。
---
description: Create a commit from current changes
argument-hint: [message]
disable-model-invocation: true
allowed-tools:
- Bash(git status *)
- Bash(git diff HEAD *)
- Bash(git add *)
- Bash(git commit *)
---
## Context
- Current status: !`git status`
- Current diff: !`git diff HEAD`
## Task
Create a commit with message: $ARGUMENTS! は command 実行前に bash 出力を埋め込みます。@src/foo.ts のような file reference も使えます。つまり slash command は単なるショートカットではなく、その時点の diff やファイルを食わせた実行テンプレートとして使うと価値が出ます。
MCP prompts は「自分で書く command」とは別物
MCP server をつないだ後に /mcp__github__pr_review 456 のような command が見えてくることがあります。これは自分が .claude/commands に置いた file ではなく、server 側が公開している prompt です。
私なら、MCP prompts は次のように割り切ります。
- GitHub / Jira / 社内 API など、接続先の workflow を借りる
- 自分の repo ルールや文章トーンは project command / skill 側で補う
- write 系 prompt は read 系 session と分ける
MCP prompts の便利さは discovery にありますが、同時に prompt の定義主体が server 側になるということでもあります。repo 固有ルールまで全部そこへ寄せるより、接続先固有の操作は MCP、repo 固有の判断は project command / skill と切り分けた方が安全です。MCP の導入境界や allowlist は Claude Code MCP ガイド を参照してください。
私ならこう使い分ける
実務では、次の順で育てるのが一番壊れにくいです。
- まず
.claude/commands/に 1 ファイルで置く - 2 週間くらい使って、引数や出力形式が固まるかを見る
- 補助ファイルや subagent が欲しくなったら
.claude/skills/へ移す - 外部接続が必要なら MCP prompts と分担する
例えば記事運用なら、私はこう分けます。
| 作業 | 向いている実装 |
|---|---|
| 記事草稿の型に沿って構成を作る | project command / skill |
| repo の SEO ルールや内部リンク方針を読む | CLAUDE.md |
| build 前の自動検証 | Hooks |
| GitHub PR 一覧取得や issue 参照 | MCP prompts |
この分け方にしておくと、「どこにルールを書くべきか」で迷いにくくなります。
よくある失敗
1. 何でも slash command に押し込む
毎回必要な事実まで command に入れると、結局毎回呼ばないと効きません。事実は CLAUDE.md、手順は command / skill に残してください。
2. disable-model-invocation を考えずに置く
明示実行したい workflow なのに自動発火を許すと、意図しない場面で読まれることがあります。手動 command なら disable-model-invocation: true を基本に考えた方が安定します。
3. write 系 command の allowed-tools を広げすぎる
便利だからと Bash(*) に寄せると、command 単位の安全境界が崩れます。commit 用、review 用、deploy 用で tool を絞った方がよいです。
4. MCP prompts と project ルールを同じ場所に置こうとする
MCP prompts は server が供給するものです。repo ルールやレビュー基準まで server 側に背負わせるより、project command / skill 側に残した方が変更も監査も楽です。
まとめ
Claude Code のスラッシュコマンドは、今では「legacy command か skills か」ではなく、どの責務をどこへ置くかで考えた方がうまくいきます。
私なら、最初は .claude/commands で最短導入し、長く使うものだけ skills に育てます。MCP prompts は外部接続 workflow に限定し、CLAUDE.md には事実、Hooks には強制ルールを書く。この役割分担にすると、slash command は単なる便利機能ではなく、チームの作業手順を再利用可能にする薄い実行面として機能します。