Claude Code のカスタムスラッシュコマンド(スキル)を作る:繰り返す指示をコマンド化する

「このプロジェクトのルールでコードレビューして」「Conventional Commits 形式でコミットメッセージを書いて」のように、毎回同じ長い指示を打っているなら、それはスラッシュコマンドにする候補です。

Claude Code では、Markdown ファイルを 1 つ置くだけで /review や /commit のような自分専用のコマンドを定義できます。この記事では、現在の主流である スキル形式を中心に、従来の commands 形式との関係、引数の扱い、チーム共有の方法をまとめます。

2 つの形式:スキルとコマンド

形式	置き場所	呼び出し	特徴
スキル	.claude/skills/<名前>/SKILL.md	/<名前> または Claude が自動判断	補助ファイル(スクリプト、テンプレート)を同じフォルダに同梱できる
コマンド	.claude/commands/<名前>.md	/<名前>	1 ファイルで完結。以前からある形式

現在はスキル形式が推奨です。description に「いつ使うか」を書いておくと、ユーザーが /名前 と打たなくても、Claude が状況に応じて自動で読み込みます。明示的に呼び出したいだけなら、どちらの形式でも動作は同じです。

ユーザー全体で使うものは ~/.claude/skills/ や ~/.claude/commands/ に置きます。プロジェクトとユーザーで同名のコマンドがある場合、区別のために接頭辞付きで表示されます。

最小構成のスキルを作る

mkdir -p .claude/skills/review

.claude/skills/review/SKILL.md:

---
name: review
description: 変更中のコードをこのプロジェクトの規約に沿ってレビューする。ユーザーが「レビューして」と言ったときにも使う。
---

現在の git diff を対象に、次の観点でレビューしてください。

1. CLAUDE.md の規約違反(型、命名、禁止ライブラリ)
2. エラーハンドリングの漏れ
3. テストが追加・更新されているか
4. セキュリティ上の懸念(入力検証、秘密情報のハードコード)

指摘は「重大 / 改善提案 / 軽微」に分類し、ファイル名と行番号を添えてください。
問題がない観点は「問題なし」と 1 行で書いてください。

保存後、対話中に /review と入力すると実行されます。新しく追加したコマンドが一覧に出ないときは、セッションを再起動してください。

引数を受け取る

$ARGUMENTS は入力された引数全体、$1、$2 は空白区切りの個別引数に置き換わります。

.claude/skills/fix-issue/SKILL.md:

---
name: fix-issue
description: GitHub Issue 番号を受け取り、内容を確認して修正する
argument-hint: <issue番号>
---

GitHub Issue #$1 を `gh issue view $1` で読み、次の手順で対応してください。

1. 再現手順を整理し、必要なら失敗するテストを先に書く
2. 原因を特定して修正する
3. テストを実行し、結果を報告する
4. コミットメッセージは「fix: <要約> (#$1)」の形式にする

/fix-issue 123 のように呼び出します。argument-hint は入力補完に表示されるヒントです。

Bash の実行結果を埋め込む

本文中に ! で始まる行を書くと、コマンド実行前にそのシェルコマンドが実行され、結果が指示に埋め込まれます。実行を許可するツールは allowed-tools で限定します。

.claude/skills/commit/SKILL.md:

---
name: commit
description: ステージ済みの変更から Conventional Commits 形式のコミットメッセージを作成してコミットする
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(git commit:*)
---

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

## 指示
上記の差分から Conventional Commits 形式(feat / fix / docs / refactor / test / chore)のコミットメッセージを日本語で作成し、コミットしてください。
1 行目は 50 字以内、本文には変更理由を書いてください。

差分の内容がそのまま指示に含まれるため、Claude が改めて git diff を実行する手間が省けます。

frontmatter で使える主なオプション

キー	意味
name	コマンド名(スキルでは必須。省略時はフォルダ名)
description	説明。自動呼び出しの判断材料になる
argument-hint	引数のヒント表示
allowed-tools	このコマンド内で確認なしに使えるツール
model	このコマンド実行時に使うモデル(例: claude-sonnet-5)

正確なキー名や新しいオプションは公式ドキュメントで確認してください。

補助ファイルを同梱する(スキルの利点)

スキルのフォルダには、テンプレートやスクリプトを一緒に置けます。

.claude/skills/new-component/
├── SKILL.md
├── template.tsx
└── template.test.tsx

SKILL.md から「template.tsx をコピーして命名を置き換える」と指示すれば、毎回同じ雛形からコンポーネントを生成できます。長い指示をコマンド本文に書くよりも、雛形を実ファイルとして置く方が結果が安定します。

運用のコツ

• CLAUDE.md との分担: 常に守るルールは CLAUDE.md、特定の作業手順はスキルに書きます。すべてを CLAUDE.md に書くとコンテキストを圧迫します(CLAUDE.md の書き方)。
• 自動呼び出しを抑えたい場合: description を「ユーザーが /名前 と明示したときだけ使う」と書くと、意図しない自動実行を減らせます。
• サブエージェントとの組み合わせ: 長いレビューは、スキルからサブエージェントを呼ぶと本体のコンテキストを汚しません(サブエージェントの作り方)。

まとめ

• .claude/skills/<名前>/SKILL.md を置くだけで /<名前> コマンドになる
• $ARGUMENTS / $1 で引数、!`コマンド` で Bash の実行結果を埋め込める
• allowed-tools でコマンド内の自動許可範囲を限定する
• 常時ルールは CLAUDE.md、作業手順はスキル、という分担にする