Claude Codeのカスタムコマンド｜1本目を作る4つの決めごと

「またこの前置きを打っている」。Claude Codeを毎日触っていると、どこかでこの感覚がやってきます。フォーマットの指定、トーンの指定、見てほしい順番。中身はほとんど同じで、差し替えているのは日付や案件名だけです。

カスタムコマンドは、その前置きを/名前という1回の呼び出しに畳む機能です。ただ、思いついた順に増やしていくと、チームで名前がぶつかります。人によって動く中身が変わり、誰の端末で試したかによって結論まで変わります。

この記事は、畳む対象・名前・引数・置き場所という4つの決めごとを順に決める手順と、チームへ配るときの管理の設計までを扱います。素材は公式ドキュメントの仕様で、確かめたのは2026-08-02時点のものです。

聞き役は2人です。若葉さんが言葉の側から、高梨課長が自分の手で動かす側から聞き、鈴木さん（本誌監修）が答えます。

01Claude Codeのカスタムコマンドって、AIエージェントへの前置きを毎回打つのと何が違うんですか？

若葉さん

若葉さんの発言

コマンドにすると、何が変わるんでしょうか。渡す指示の中身は同じですよね。

鈴木さん

鈴木さんの発言

中身は同じです。違うのは置き場所だと思っています。毎回その場で口にしていたことを、紙に書いて棚へ置いておく。呼ぶときは棚の名前だけで済む、という感じですね。

結論から書きます。

1. Claude Codeのカスタムコマンドは、.claude/skills/<名前>/SKILL.mdで実装します。旧来の.claude/commands/<名前>.mdも、同じ/名前という呼び出しになります（出典: Claude Code公式ドキュメント「Skills」）。
2. 決めごとは4つです。畳む対象・名前・引数・置き場所を、この順で決めると手戻りが減ります。
3. チームで使う場合は、個人用の置き場所と衝突しない名前にしないと、人によって動く中身が変わります。

Claude Codeのカスタムコマンドとは、繰り返す指示を/名前という1回の呼び出しに畳む仕組みです。

では、どこからが畳んでよい前置きなのか。公式ドキュメントは、同じ指示やチェックリストを毎回貼り付けている状態を、コマンド化のきっかけとして挙げています（出典: 同ドキュメント）。CLAUDE.mdの一部が、事実の記述ではなく手順の記述に育ってきた場合も同じ合図です。

AIエージェントに渡す仕事の全体像は、Claude Codeの業務活用｜任せる仕事の地図と判断軸4つで整理しています。

02Claude Codeのスラッシュコマンドはスキルに統合されたそうですが、生成AIの設定は書き直しになるんですか？

Claude Codeは、以前カスタムコマンドと呼んでいた仕組みを、スキルという機能へ統合しました（出典: 同ドキュメント）。呼び方が変わっただけで、手元のファイルが壊れるわけではありません。

分かれ目は、一緒に置きたいものがあるかどうかです。指示文だけで完結するなら形を変える理由はなく、下書きのひな型や実行スクリプトを添えたくなった時点で、置ける形が違ってきます。

.claude/commands/deploy.mdと.claude/skills/deploy/SKILL.mdは、どちらも/deployを作ります（出典: 同ドキュメント）。書き直しの緊急性はありません。ただし、テンプレートやスクリプトを同梱したいときは、スキル形式でしか実現できません。

本記事は以降、現在推奨されている.claude/skills/の形式で説明します。.claude/commands/を使う場合も、フロントマターの項目はほぼ共通です。

03カスタムコマンドを作る前に、AIエージェントが動く環境の何を確かめるんですか？

検証環境は、claude-opus-5・Claude Code v2.1.x・macOS 15・2026-08-02検証です。着手前に確かめるのは次の3点です。

• バージョン：機能追加はバージョンで区切られます。複数コマンドを連続で呼び出す機能はv2.1.199以降の対応です（出典: 同ドキュメント）。
• 置き場所の候補：個人用は~/.claude/skills/、プロジェクト用は.claude/skills/です。どちらにするかは後の章で決めます。
• 信頼設定：プロジェクトの.claude/skills/に書いたallowed-toolsは、ワークスペース信頼ダイアログの承認まで効きません（出典: 同ドキュメント）。社外から受け取ったプロジェクトでは、ここを飛ばさないようにします。

3点に共通するのは、見落としても、その場では何も起きないことです。バージョンが足りなければ書き終えてから分かり、信頼の承認が済んでいなければ実行のたびに確認を求められます。作っている最中の画面には、どれも出てきません。

04どの作業をカスタムコマンドに畳むと、AI活用が続くんですか？

高梨課長

高梨課長の発言

作り方は分かりました。ただ、何から作ればいいのかが分かりません。

鈴木さん

鈴木さんの発言

直近1〜2週間を振り返って、同じ指示を2回以上貼り直した作業を書き出すところから始めています。思いつきで作ったものは、たいてい二度と呼ばれないので。

ここからは、毎週の進捗レポートの下書きを例に、4つの決めごとを順に決めます。まず、畳む対象です。

• 入力：直近1〜2週間で、同じ指示を2回以上貼り直した作業を書き出す
• 確認：指示の大部分が毎回同じで、変わるのは日付や対象名など一部の値だけか

「毎週金曜に進捗レポートの下書きを頼む」作業は、フォーマットとトーンの指示が毎回同じで、変わるのは対象期間だけです。この条件を満たす作業が候補になります。

2軸に置き直すと、箇条書きでは見えないものが出てきます。繰り返しが多くても、毎回変わる部分が大きい作業は候補にならないということです。畳めるのは、変わらない部分が大半を占めている作業だけです。

回数の多さから選ぶと、判断や交渉が混ざった作業まで入ってきます。見るのは呼ばれる頻度ではなく、毎回そのまま使える文面の割合です。

05カスタムコマンドの名前は、AIエージェントが取り違えないようにどう決めるんですか？

対象が決まったら、名前です。

• 入力：候補の作業を1〜2語の動詞的な名前にする
• 確認：~/.claude/skills/と.claude/skills/の両方に、同じ名前が無いか

公式ドキュメントの例はdeploy・fix-issue・commitのように動詞的な表現です（出典: 同ドキュメント）。ここではreport-draftとします。呼び出し名はディレクトリ名で決まり、nameは表示ラベルを変えるだけです（出典: 同ドキュメント）。

mkdir -p .claude/skills/report-draft

重なった部分が、そのまま事故の面積になります。やっかいなのは、重なっていること自体が自分の画面には出ないことです。良い名前を考える時間より、両方の棚を開いて見る時間のほうが短く済みます。

06Claude Codeのカスタムコマンドに引数を渡すと、AIエージェントには何が届くんですか？

若葉さん

若葉さんの発言

引数というのは、コマンドのうしろに付ける文字のことですか。

鈴木さん

鈴木さんの発言

そうです。差し替えたい部分だけを、呼ぶときに渡す仕組みですね。書き方が何通りかあって、渡したい値の数で選び分けます。

---
name: report-draft
description: 週次進捗レポートの下書きを作る
argument-hint: [対象期間]
disable-model-invocation: true
---

$ARGUMENTS の期間について、進捗レポートの下書きを作成する:

1. 完了したタスクを箇条書きにする
2. 遅延しているタスクと理由を書く
3. 来週の予定を3行以内でまとめる

書き方が分かれる理由は、渡す値の数です。値が増えるほど、順番を覚えておく負担は呼ぶ側へ移っていきます。

07カスタムコマンドの引数の書き方を選ぶとき、AIエージェントに渡る文はどこが入れ替わるんですか？

書き方を決めたら、実際に渡る文がどう変わるのかを見ておきます。

/report-draft 2026年8月第1週と打つと、$ARGUMENTSの部分が入力どおりに置き換わってClaudeへ渡ります（出典: 同ドキュメント）。

入力：/report-draft 2026年8月第1週

Claudeが受け取る内容：
2026年8月第1週 の期間について、進捗レポートの下書きを作成する:
1. 完了したタスクを箇条書きにする
2. 遅延しているタスクと理由を書く
3. 来週の予定を3行以内でまとめる

たどってみると、置き換えの起きる場所が1か所しかないことが分かります。書き手が$ARGUMENTSを置いた位置に、渡した文字列がそのまま入る。裏を返せば、書き手が位置を指定しなかったときに値が入る場所も、あらかじめ決まっているということです。

複数語の値を1つの位置引数として渡すときは、引用符で囲みます（出典: 同ドキュメント）。

08カスタムコマンドの置き場所で、AI導入を進めたチームの誰の設定が動くかが変わるんですか？

最後に置き場所です。候補は次のとおりです。

（出典: 同ドキュメント）

同じ名前が複数の階層にあるときは、エンタープライズ・個人・プロジェクトの順で優先されます（出典: 同ドキュメント）。

積み上げると、表の並びとは別の関係が出てきます。覆う範囲が広いものほど、優先されるという向きです。組織全体に効くものが、自分の全プロジェクトに効くものより強い。そして、このプロジェクトだけに効くものは、いちばん下に置かれます。

チームへ配るつもりで作ったプロジェクト用が、いちばん弱い側にいるということです。だから、自分の端末に同じ名前の個人用があると、そちらが動きます。この順番を知らないと、自分の端末では個人用が動き、チームでの動作を確認できません。

09Claude Codeのカスタムコマンドをチームで共有するとき、生成AIの設定はどれをGitに入れるんですか？

高梨課長

高梨課長の発言

チームに配るとなると、Gitへ何を入れるかも決めないといけませんね。

鈴木さん

鈴木さんの発言

そうですね。共有する本体と、個人の設定を分けるところからです。個人の設定まで一緒に配ると、他の人の画面が本人の知らないうちに変わってしまうので。

まず、.claude/skills/はチームで共有する本体なのでコミットします。.claude/settings.jsonも、チームで揃えたい許可ルールの置き場所としてコミット対象です。

一方.claude/settings.local.jsonは個人設定用です。Claude Codeはここへ保存する際、未設定なら自動でgitの除外リストへ追加します（出典: 同ドキュメント「Settings」）。

副作用のある操作（デプロイ・送信など）を含むコマンドにはdisable-model-invocation: trueを付けます。Claudeが会話の流れだけで自動実行しないようにするためです（出典: 同ドキュメント「Skills」）。人が/名前と打ったときだけ動く設計は、送信や公開の直前で人の判断を挟むAIエージェントの承認ゲートと同じ考え方です。

分け方そのものは、道具の貸し借りと変わりません。みんなで使うものは棚に出し、自分の都合で変えたものは引き出しにしまう。配る前に、この線を引いておきます。

10チーム全員がカスタムコマンドの実行でAIエージェントに毎回許可を聞かれないようにするには、どこへ書くんですか？

配る本体が決まったら、次は許可の置き場所です。

チーム全員が実行のたびに許可を聞かれたくない場合は、.claude/settings.jsonに許可ルールを書くか、allowed-toolsをコマンドのフロントマターに書きます。許可ルールの基本形はToolまたはTool(指定子)です（出典: 同ドキュメント「Permissions」）。スキル単位ではSkill(名前)やSkill(名前 *)という書き方も使えます（出典: 同ドキュメント「Skills」）。配分の考え方そのものはClaude Codeの権限設定｜AIエージェントに任せる範囲と3列の配分で扱っています。

自社では複数のAIエンジンで同じ定義を使うため、.agents/skills/を中立の正本、.claude/skills/をClaude実行用のミラーとして運用しています。2026-07-28の実測では、両者は59本で一致しています。エンジンが1つならここまでの分離は不要ですが、コマンドが2桁を超えたら正本を先に決めておくと管理が崩れにくくなります。

11AIエージェントの運用でカスタムコマンドがつまずくのは、どの3か所ですか？

1. 個人用と同じ名前でプロジェクト用を作ってしまう：優先順位は個人が勝つため、自分の端末では気づけません（出典: 同ドキュメント「Skills」）。他のメンバーだけがプロジェクト用で動く状態になります。名前を決める前に、自分の~/.claude/skills/を確認します。
2. $ARGUMENTSを書き忘れる：渡した値はSKILL.mdの本文末尾に追加されるだけです（出典: 同ドキュメント）。意図した位置に値が入らず、指示の途中が空欄のまま残ります。
3. 副作用のあるコマンドにdisable-model-invocationを付け忘れる：descriptionが一致すると、Claudeが自動で読み込みます。送信・公開・削除を含むコマンドは、人が明示的に呼び出す設計にします。

3つに共通するのは、症状の出る場所が自分の手元ではないことです。だから気づくのは大抵、誰かが「動かない」「勝手に動いた」と報告したあとになります。いずれも設定を1行加えるだけで防げますが、その1行を足す機会は配る前にしかありません。

12カスタムコマンドが設計どおり動いていると、AI活用の現場では何を見て判定するんですか？

次の4点で判定します。

1. /名前と打ってから、想定した前置きどおりの指示がClaudeに渡っているか
2. 引数を渡したとき、$ARGUMENTSや$1などが意図した位置に置き換わっているか
3. disable-model-invocation: trueを付けたコマンドが、関連する話題を話しても自動では動かないか
4. チームメンバーの端末でも、同じ名前のコマンドが同じ内容で動くか（個人用との衝突がないか）

並べてみると、境目がひとつあります。前の3点は自分の端末で終わりますが、最後の1点だけは他の人の端末が要るということです。ここを飛ばすと、確認したつもりのまま配ることになります。

4点をすべて満たせば、そのコマンドは設計どおりに動いています。1つでも外れる場合は、名前を決めた段階か、置き場所を決めた段階まで戻って確認します。

13よくある質問

14まとめ｜今日やる3つのこと

決めごとは4つでした。畳む対象・名前・引数・置き場所。この順で決めるのは、あとの決めごとが前の決めごとに寄りかかっているからです。対象が決まらないと名前は決まらず、名前が決まらないと置き場所の衝突も見られません。

そして、確かめられることには境目があります。自分の端末で分かるのは前の3点まで。名前の衝突と、他の人の端末での挙動は、配ったあとにしか表に出てきません。だから、配る前の一手のほうが安く済みます。