Claude Codeのカスタムコマンドの作り方|commandsとスキルの違い

Claude Codeのカスタムコマンドの作り方|commandsとスキルの違い
📅 公開日: 2026年11月20日🔄 最終更新: 2026年11月21日

Claude Codeの自作コマンドは、プロジェクトの.claude/commands/にMarkdownファイルを置けば、今もそのまま動きます(Claude Codeドキュメント(スラッシュコマンドとスキル))。

ただし公式は、カスタムコマンドはスキルに統合されたと説明し、新しく作るならスキルを優先するよう書いています(Claude Codeドキュメント(スラッシュコマンドとスキル))。

この記事では、既存のコマンドファイルの書き方、引数の渡し方、スキルへ移す手順、動かない時の確認先を整理します。

確認日は2026年11月19日です。

目次

カスタムスラッシュコマンドとは|commandsフォルダのMarkdownがそのまま呼べる

LINEでインスタ大学の受取案内を見る

LINEでインスタ大学の受取案内を見る

インスタ大学の受取案内をLINEで確認できます。

LINEでインスタ大学の受取案内を見る

カスタムスラッシュコマンドとは、.claude/commands/に置いたMarkdownファイルを、ファイル名のコマンドとして呼び出せる仕組みです(Claude Codeドキュメント(スラッシュコマンドとスキル))。

公式の説明では、既存の.claude/commands/のファイルは引き続き動きます。

Claudeが、コマンド名を打たなくても必要な場面で呼び出せる点も書かれています(Claude Codeドキュメント(スラッシュコマンドとスキル))。

自動で呼ばれたくない場合は、フロントマターにdisable-model-invocation: trueを足します(Claude Codeドキュメント(スラッシュコマンドとスキル))。

仮の例:チームで「リリース前の点検」という手順書を.claude/commands/release-check.mdとして置くと、/release-checkで呼び出せます。

人が打った時だけ動かしたい手順なら、上のフラグを付けておくと安全です。

コマンドとスキルの違い|どちらを使うかの判断表

両者の違いは、補助ファイルを持てるかどうかと、公式がどちらを勧めているかです。新しく作るならスキルが公式の推奨です(Claude Codeドキュメント(スラッシュコマンドとスキル))。

項目commandsのMarkdownスキル
置き場所.claude/commands/名前.md.claude/skills/名前/SKILL.md
公式の位置づけ古い形式だが今も動く新規作成で優先する形式
補助ファイル(スクリプトなど)置けない同じフォルダに置ける
同じ名前がある時スキルが優先されるこちらが実行される

この表の内容は、Claude Codeドキュメント(スラッシュコマンドとスキル)の記述によります(確認日は2026年11月19日)。

スキルそのものの作り方は、別の記事にまとめています。

置き場所や呼び出し方は、Claude Codeのスキル(Skills)の使い方|設定と呼び出し方を読んでください。

コマンドファイルの書き方|フロントマターで指定できる項目

コマンドファイルは、先頭のフロントマター(YAML)と本文のMarkdownでできています。指定できる項目は、スキルからnameとpathsを除いたものと同じです(Claude Codeドキュメント(スラッシュコマンドとスキル))。

主な項目は次のとおりです。

  • description:Claudeがいつ使うかを判断する説明。公式は書くことを勧めています。
  • argument-hint:入力補完に出す引数のヒント(例:[issue-number])。
  • arguments:$nameで置き換える名前つき引数の宣言。
  • allowed-tools:そのターンで確認なしに使えるツール。
  • disable-model-invocation:Claudeの自動呼び出しを止める。
  • model・effort・context・agent・hooks・shellなどの項目もあります。

以上は、Claude Codeドキュメント(スラッシュコマンドとスキル)のフロントマター表によります。

注意点が1つあります。

項目名は表と完全に一致させる必要があり、ハイフンも含みます。

認識されない項目は、エラーを出さずに無視されます(Claude Codeドキュメント(スラッシュコマンドとスキル))。

効かない設定があれば、まず綴りを疑うのが近道です。

仮の例として、現在のブランチの変更を要約するコマンドは次のように書けます。

---
description: 現在のブランチの変更を要約する
argument-hint: [重点にしたい観点]
---

このブランチの変更点を要約してください。
特に次の観点を重視してください:$ARGUMENTS

これを.claude/commands/summarize-branch.mdとして保存すると、/summarize-branch 速度のように呼び出せます。

引数の渡し方|$ARGUMENTSと$0・$1の使い分け

引数は、本文に$ARGUMENTSや$0、$1を書いておくと、呼び出し時の入力に置き換わります(Claude Codeドキュメント(スラッシュコマンドとスキル))。

書き方意味
$ARGUMENTS入力した引数をそのまま全部
$ARGUMENTS[N]・$N0始まりの位置で指定する引数
$nameフロントマターのargumentsで宣言した名前つき引数

この表は、Claude Codeドキュメント(スラッシュコマンドとスキル)の引数の節によります(確認日は2026年11月19日)。

引用符でくくると、空白を含む文字列を1つの引数として渡せます。

公式の例では、"hello world" secondと入力すると、$0がhello world、$1がsecondになります(Claude Codeドキュメント(スラッシュコマンドとスキル))。

本文に置き換え先を1つも書かないまま引数を渡すと、末尾にARGUMENTS: <入力>が自動で付け足されます(Claude Codeドキュメント(スラッシュコマンドとスキル))。

ドル記号そのものを書きたい時は、\$1.00のようにバックスラッシュで打ち消します(Claude Codeドキュメント(スラッシュコマンドとスキル))。

公式の例では、次のコマンドを/migrate-component SearchBar JavaScript TypeScriptで呼ぶと、3つの値が順に入ります。

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

allowed-toolsとフォルダ構成|確認の省略と名前空間

allowed-toolsについて、列挙したツールは確認なしで使える、列挙しないツールは権限設定が引き続き効く、効力は次のメッセージで消えることを3枚に並べた図。
allowed-toolsは確認を省く項目で制限ではない

allowed-toolsは、そのコマンドを呼んだターンの間だけ、列挙したツールを確認なしで使えるようにする項目です。ツールの利用を制限する項目ではありません(Claude Codeドキュメント(スラッシュコマンドとスキル))。

公式は、列挙しなかったツールも呼び出せること、権限設定が引き続き効くことを明記しています(Claude Codeドキュメント(スラッシュコマンドとスキル))。

許可の効力は、次のメッセージを送ると消えます。

公式の例は、Bash(git add *) Bash(git commit *) Bash(git status *)のように、空白区切りでツールを並べる形です。

権限ルールの決め方は、Claude Codeの権限設定(permissions)の使い方で整理しています。

なお、allowManagedPermissionRulesOnlyを使う環境では、プロジェクトや個人のスキルのallowed-toolsが無視されると公式に書かれています(v2.1.282以降が対象。Claude Codeドキュメント(スラッシュコマンドとスキル))。

フォルダを分けると、コマンド名に名前空間が付きます。

公式の例では、.claude/commands/frontend/component.mdは/frontend:componentになります(Claude Codeドキュメント(スラッシュコマンドとスキル))。

プラグインのスキルは/プラグイン名:スキル名の形で呼び出します(Claude Codeドキュメント(スラッシュコマンドとスキル))。

実践用の「Claude Code・Codex 最初の安全設定と仕事の渡し方」を無料で配布しています。LINE で「AIエージェント設定」と送ると届きます。LINEで受け取る

本文でシェルコマンドを実行する|!の書き方と失敗時の動き

本文に!とバッククォートで書いたコマンドが、送られる前にシェルで実行され出力が差し込まれる流れと、失敗時の動き3点をまとめた図。
!によるシェル実行の流れと失敗時の動き

本文に!とバッククォートでコマンドを書くと、内容がClaudeに送られる前にシェルで実行され、出力がその場所に差し込まれます(Claude Codeドキュメント(スラッシュコマンドとスキル))。

1行で書く形は、行頭か空白の直後に!がある時だけ認識されます。

複数行の場合は、```!で始まるコードブロックを使います(Claude Codeドキュメント(スラッシュコマンドとスキル))。

失敗時の動きは、次の3点に注意してください。

  1. コマンドが1つでも失敗すると、その呼び出し全体が中止されます。差し込み部分だけが空になるわけではありません。
  2. 標準のbashでは、終了コードが0以外なら失敗です。検索や比較コマンドの終了コード1は例外です。
  3. 0以外で終わると分かっているコマンドには、|| trueを付けます。

この3点は、Claude Codeドキュメント(スラッシュコマンドとスキル)のシェル実行の節によります(確認日は2026年11月19日)。

差し込むコマンドは、先に権限ルールで検査されます。

denyルールに当たるコマンドがあると、呼び出しは中止されます(Claude Codeドキュメント(スラッシュコマンドとスキル))。

管理者は、"disableSkillShellExecution": trueで、ユーザー・プロジェクト・プラグインの各提供元のこの機能を止められます(Claude Codeドキュメント(スラッシュコマンドとスキル))。

共有するコマンドに!を入れる前に、組織の設定でこの機能が止められていないかを確かめてください。

commandsからスキルへ移す手順

commandsのdeploy.mdをスキルへ移す手順を、フォルダを作る、SKILL.mdへ移す、補助ファイルを置く、古いファイルは不要の4段で左から右へ並べた図。
commandsからスキルへ移す4つの手順

スクリプトなどの補助ファイルを付けたい時は、コマンドをスキルに移します。.claude/commands/deploy.mdを.claude/skills/deploy/SKILL.mdへ動かすと、フォルダ名がコマンド名になります(Claude Codeドキュメント(スラッシュコマンドとスキル))。

移した後も、打つコマンドは/deployのままです。

  1. .claude/skills/deploy/フォルダを作ります。
  2. 元のdeploy.mdを、そのフォルダにSKILL.mdという名前で移します。
  3. 補助のスクリプトがあれば、同じフォルダに置きます。
  4. 同じ名前の.claude/commands/deploy.mdが残っていると、スキル側が実行されます。古いファイルを残す必要はありません。

手順の根拠は、Claude Codeドキュメント(スラッシュコマンドとスキル)の「同名ならスキルが実行される」という記述です。

個人用に置く場合のフォルダは~/.claude/skills/、チームで共有する場合は.claude/skills/をバージョン管理に入れます(Claude Codeドキュメント(スラッシュコマンドとスキル))。

プラグインとして配る方法は、Claude Codeのプラグインの使い方|インストール・自作・配布までに書いています。

動かない時の確認先

コマンドが呼ばれない、または効かない時は、項目名の綴り、フロントマターの書式、名前の衝突の3つから確かめます。

症状まず確認すること
設定したはずの項目が効かない項目名の綴りとハイフン。認識されない項目はエラーなしで無視される
Claudeが説明を見て選んでくれないdescriptionに、利用者が自然に使う言葉が入っているか
/名前が認識されない名前が拒否されていないか、同名のスキルが優先されていないか
勝手に呼ばれて困るdisable-model-invocation: trueを足す
書式が崩れて説明が読まれないフロントマターのYAMLが壊れていないか。--debugで解析エラーを確認する

この表は、Claude Codeドキュメント(スラッシュコマンドとスキル)のトラブルシューティングの節をもとにしています(確認日は2026年11月19日)。

公式によると、YAMLが壊れている場合でも、本文は空のメタデータで読み込まれ、/スキル名の呼び出し自体は動きます。

ただし説明文が読まれないため、Claudeによる自動選択は働きません(Claude Codeドキュメント(スラッシュコマンドとスキル))。

守らせたい規則が毎回確実に必要な場合は、コマンドの文章ではなくhookに移す方法が公式に示されています。

hookの設定は、Claude Codeのフック(hooks)の使い方|設定の書き方とイベント一覧で確認できます。

よくある質問(FAQ)

Q1. .claude/commandsのファイルは、もう使えませんか?
使えます。公式は、既存の.claude/commands/のファイルは引き続き動くと説明しています(Claude Codeドキュメント(スラッシュコマンドとスキル))。
Q2. 新しく作るなら、commandsとスキルのどちらですか?
公式は、新規作成にはスキルを勧めています。スキルは補助ファイルを持てるためです(Claude Codeドキュメント(スラッシュコマンドとスキル))。
Q3. 引数は何個まで渡せますか?
個数の上限は、確認した公式ページには書かれていません。位置指定の$0、$1、$2のように、本文で使う分だけ並べます(Claude Codeドキュメント(スラッシュコマンドとスキル))。
Q4. allowed-toolsに書かないツールは使えなくなりますか?
なりません。列挙するのは確認を省くツールで、制限ではありません。列挙しないツールは、権限設定のとおりに扱われます(Claude Codeドキュメント(スラッシュコマンドとスキル))。
Q5. フォルダを分けるとコマンド名はどうなりますか?
.claude/commands/frontend/component.mdは/frontend:componentになります(Claude Codeドキュメント(スラッシュコマンドとスキル))。

読み終わったら、手元に残す

Claude Code・Codex 最初の安全設定と仕事の渡し方

中身

  • 最初に決める6項目(契約・場所・権限・承認・使用量・検収)
  • Claude Code と Codex の操作の違い
  • 最初の仕事を小さく渡す方法

LINE を友だち追加して「AIエージェント設定」と送ると、無料で届きます。

LINEで「AIエージェント設定」を受け取る

まとめ

既存の.claude/commands/のコマンドは、今も動きます。

新しく作る時は、補助ファイルを持てるスキルが公式の推奨です。

引数は本文の置き換え記号で渡し、allowed-toolsは確認を省くだけで制限にはなりません。

本文の!によるシェル実行は、1つでも失敗すると呼び出し全体が止まります。

動かない時は、項目名の綴り、YAMLの書式、同名スキルの優先の順に確認します。

確認日は2026年11月19日です。

このサイトは株式会社S.Lineが運営しています。記事内の店舗予約・LINE登録・講座の案内には、当社または当社が集客を担当するサービスの広告(PR)が含まれます。
よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

この記事を書いた人

株式会社S.Line 代表取締役。偏差値39から起業し、AIとSNSの活用で「普通の人」が成果を出す方法を発信。

目次