公開日:
Claude Codeカスタムコマンドは、推奨のSkills形式なら3ステップで作成できます。
- 要点1: 旧
.claude/commands/は現在も動作します - 要点2: 新規作成は
.claude/skills/<名前>/SKILL.mdが推奨です - 要点3: 引数、手動実行、ツール権限をfrontmatterで設計できます
対象読者：定型作業をClaude Codeで標準化したい開発者と管理者今日やること：読み取り専用のSkillを1つ作り、手動で動作確認する
この記事の目次
- Claude Codeカスタムコマンドとは
- 現在はSkills形式が推奨される
- commands形式とSkills形式の違い
- 作成前に用途と実行範囲を決める
- 最小のカスタムコマンドを3ステップで作る
- SKILL.mdの基本構造
- 保存場所で利用範囲が変わる
- コマンド名と優先順位を理解する
- 引数は$ARGUMENTSと$0で受け取る
- 動的コンテキストで実データを渡す
- 自動呼び出しと手動呼び出しを制御する
- allowed-toolsは権限の事前承認として使う
- サポートファイルで長い手順を分割する
- 実務で使える3つのテンプレート
- チーム共有ではレビューと所有者を決める
- 旧形式の移行とトラブルを切り分ける
- よくある質問
- まとめ
Claude Codeカスタムコマンドを新しく作るなら、現在はSkills形式を選ぶのが基本です。
検索すると.claude/commands/へMarkdownを置く手順も見つかります。これは誤りではありません。旧形式は今も動きますが、Anthropicの現行ドキュメントではカスタムコマンドがSkillsへ統合され、SKILL.md形式が推奨されています。
保存場所が変わっただけではありません。引数の受け取り、手動実行への限定、サポートファイルの同梱まで設計できます。この記事では、最小構成からチーム運用までを公式仕様に沿って説明します。
Claude Codeカスタムコマンドとは
Claude Codeカスタムコマンドは、繰り返し使う指示や作業手順を保存し、/名前で呼び出す仕組みです。Claude CodeはAnthropicが提供するAIコーディング支援ツールで、ファイルの読解や編集、テスト実行などを対話形式で進めます。
たとえば、変更差分を確認するたびに「重大度順に問題を分類し、根拠となるファイル名を示す」と入力しているなら、その指示は再利用できます。/review-changesだけで同じ観点を呼び出せるため、担当者ごとの指示の揺れも抑えやすくなります。
Claude Code内で/から呼ぶ機能は、実装によって次の3種類に分かれます。
| 種類 | 例 | 動作 |
|---|---|---|
| 組み込みコマンド | /help、/clear |
CLIに固定された処理を実行 |
| バンドルSkill | /code-review、/verify |
Anthropic提供の指示をClaudeが実行 |
| 自作Skill | /review-changes |
利用者が書いたSKILL.mdを実行 |
コマンドはメッセージの先頭で認識され、後ろのテキストは引数になります。組み込み機能の全体像はClaude Code CLI完全リファレンスでも確認できます。
現在はSkills形式が推奨される
現行仕様では、カスタムコマンドはSkillsへ統合されています。Anthropic公式のSkillsドキュメントは、.claude/commands/deploy.mdと.claude/skills/deploy/SKILL.mdのどちらも/deployを作ると説明しています。
ここで「統合された」を「旧形式が廃止された」と読むのは正確ではありません。公式文書は、既存の.claude/commands/が引き続き動くことも明記しています。移行期限も示されていません。
それでも新規作成にSkills形式を勧める理由は、次の機能を使えるからです。
- 参照資料、テンプレート、スクリプトを同じディレクトリに置ける
descriptionを基にClaudeが関連するSkillを選べる- 手動実行だけに限定できる
- 引数、モデル、実行コンテキストをfrontmatterで指定できる
- 特定のファイルに関係する場面だけで自動選択させられる
Skillsそのものを詳しく知りたい場合は、Claude Code Skills完全ガイドも参考になります。
＼ AI導入の進め方を一緒に整理しませんか ／
AI顧問の無料相談はこちらcommands形式とSkills形式の違い
2つの形式は同じ/名前を作れますが、拡張性が異なります。短い指示を1枚だけ保存するなら旧形式でも足ります。手順を育ててチームで保守するならSkills形式が向いています。
| 比較項目 | commands形式 | Skills形式 |
|---|---|---|
| プロジェクト内の場所 | .claude/commands/name.md |
.claude/skills/name/SKILL.md |
| 個人用の場所 | ~/.claude/commands/name.md |
~/.claude/skills/name/SKILL.md |
| サポートファイル | 1ファイルが基本 | 同じディレクトリへ同梱可能 |
| Claudeによる自動選択 | 制約あり | descriptionなどで制御可能 |
| 呼び出し名 | ファイル名 | Skillのディレクトリ名 |
| 新規作成時の選択 | 互換用途 | 推奨 |
既存commandが安定しているなら、形式だけを変えるために急いで移行する必要はありません。サポートファイルを追加したい、呼び出し主体を制御したい、といった要件が生じた時点で移すほうが変更理由を説明できます。
作成前に用途と実行範囲を決める
先に決めるべきなのはファイル名ではなく、Skillが終わったときの状態です。「コードを確認する」だけでは、担当者ごとに結果が変わります。入力、処理、出力、禁止操作、完了条件まで書ける作業を選びます。
最初のSkillは、次の5項目で設計すると検証しやすくなります。
- 入力：対象ファイル、Issue番号、比較するブランチなど
- 処理：読む範囲、評価基準、実行するコマンド
- 出力：表、箇条書き、変更ファイルなど
- 禁止操作：ファイル編集、外部送信、デプロイなど
- 完了条件：テスト結果、件数、保存先、確認項目
初回からデプロイや一括更新を選ぶと、指示の曖昧さがそのまま副作用になります。変更差分の要約や設定ファイルの点検など、読み取り専用で結果を人が評価できる作業から始めると、設計の不足を安全に見つけられます。
＼ 業務自動化のお悩みをAI顧問に相談できます ／
AI顧問の無料相談はこちら最小のカスタムコマンドを3ステップで作る
ここでは、プロジェクト内の未コミット差分を要約する/summarize-changesを作ります。ファイルを書き換えないため、初回の動作確認に適しています。
1. Skill用ディレクトリを作る
プロジェクトのルートで次のコマンドを実行します。
mkdir -p .claude/skills/summarize-changes2. SKILL.mdを書く
.claude/skills/summarize-changes/SKILL.mdを作成し、次の内容を保存します。
---description: 未コミットの変更を要約し、確認が必要な点を示します。差分の説明やコミット前確認に使います。disable-model-invocation: trueallowed-tools: Bash(git diff *) Bash(git status *)---未コミットの変更を確認してください。1. 変更内容を3項目以内で要約する2. 変更されたファイルを列挙する3. テスト不足や設定漏れの可能性を示す4. ファイルは編集しない3. Claude Codeから実行する
Claude Codeをプロジェクトのルートで起動し、入力欄に次のコマンドを入れます。
/summarize-changes成功判定は「返答があったこと」ではありません。未コミット差分と要約が一致し、ファイルが変更されず、不要なコマンドが実行されていないことまで確認します。期待する形式が崩れた場合は、本文の完了条件を具体化します。
SKILL.mdの基本構造
SKILL.mdは、YAML frontmatterとMarkdown本文の2層で構成します。frontmatterはClaude CodeがSkillを発見し、呼び出し方を決めるためのメタデータです。本文はClaudeが実際に従う手順です。
---name: summarize-changesdescription: 未コミットの変更を要約します。差分確認を求められたときに使います。argument-hint: [base-branch]disable-model-invocation: true---$0 を基準に差分を確認し、変更点とリスクを報告してください。開始側の---はファイルの1行目に置きます。公式文書によれば、先頭にない場合はfrontmatterとして処理されず、区切りも本文として扱われます。
descriptionには、機能名だけでなく「いつ使うか」を含めます。「レビュー用」より「未コミット差分の問題を重大度順に報告する」のほうが選択条件を判断しやすくなります。nameは表示名であり、ProjectまたはPersonal Skillの呼び出し名はディレクトリ名で決まります。
＼ AI活用の「次の一手」を一緒に考えませんか ／
AI顧問の無料相談はこちら保存場所で利用範囲が変わる
同じSkillでも、保存場所によって利用者が変わります。チーム標準を個人ディレクトリへ置くと他の担当者に届きません。反対に、個人の実験をプロジェクトへコミットすると全員の候補に現れます。
| スコープ | 保存場所 | 適する用途 |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md |
個人だけが複数案件で使う手順 |
| Project | .claude/skills/<name>/SKILL.md |
リポジトリ固有の手順、チーム共有 |
| Enterprise | 組織の管理設定 | 全社ポリシーや共通手順 |
| Plugin | <plugin>/skills/<name>/SKILL.md |
配布可能な機能群 |
プロジェクトSkillはGitへコミットすれば共有できます。クラウド上のセッションでも、複製されたリポジトリにProject Skillが含まれていれば読み込めます。一方、ローカルのPersonal Skillは別の端末やクラウドへ自動では移りません。
企業利用では「どこに置けるか」より「誰が変更を承認するか」を先に決めます。Project Skillはコードと同じ変更管理へ載せ、Personal Skillは個人補助に限定すると責任範囲が明確です。
コマンド名と優先順位を理解する
Project SkillとPersonal Skillでは、SKILL.mdを格納するディレクトリ名がコマンド名になります。.claude/skills/release-note/SKILL.mdなら/release-noteです。旧commands形式では、.mdを除いたファイル名が使われます。
同名が複数ある場合の優先順位も決まっています。
- スコープ間ではEnterprise、Personal、Projectの順に優先される
- 同じ名前のSkillとcommandがある場合はSkillが優先される
- Plugin Skillは
plugin-name:skill-nameという名前空間を持つ - ネストされたSkillはディレクトリ修飾名で区別される場合がある
プロジェクトへ新しい/deployを追加したのに古い動作が続くなら、Personal Skillが同名で存在する可能性があります。本文だけを直し続けても解決しません。/skillsの一覧で提供元を確認し、命名を分けるか、上位スコープの定義を整理します。
引数は$ARGUMENTSと$0で受け取る
対象ファイルや比較ブランチを毎回変えるなら、Skill本文へ固定せず引数として渡します。Claude Codeは、コマンド名の後ろに続くテキストを引数として扱います。
| 記法 | 受け取る値 |
|---|---|
$ARGUMENTS |
入力された引数全体 |
$ARGUMENTS[0] |
第1引数 |
$0 |
第1引数の短縮形 |
$1 |
第2引数の短縮形 |
$name |
argumentsで宣言した名前付き引数 |
位置指定は0始まりです。$1を第1引数と考えると対象が1つずれます。たとえば/review-file src/app.ts strictでは、$0がsrc/app.ts、$1がstrictです。
名前付き引数を使う場合は、frontmatterで順番を宣言します。
---description: 指定ファイルを指定方針で確認します。arguments: [file, policy]argument-hint: [file] [policy]---$file を読み、$policy の方針で問題を報告してください。複数の単語を1つの引数にしたい場合は引用符で囲みます。/review-file "src/my app.ts" strictなら、空白を含むパスを第1引数として渡せます。
動的コンテキストで実データを渡す
Skill本文へ実行時点の差分や状態を差し込むと、Claudeが推測ではなく実データを基に判断できます。Skillsでは、!`command`の形式でシェル出力を動的に注入できます。
## 現在の変更状況!`git status --short`## 差分の要約!`git diff --stat`上記を基に、変更範囲と確認すべきテストを報告してください。このコマンドは、ClaudeがSkill本文を読む前に実行され、出力へ置き換わります。便利ですが、単なる文章ではありません。外部から取得したSkillを使う前に、!で始まる処理がファイル削除、外部送信、資格情報の表示を含まないか確認します。
引数をシェルへ直接連結する設計も避けます。利用者が入力した文字列を検証せず実行すると、意図しないコマンドへ展開される余地が生じるためです。まずはgit statusのように対象が固定された読み取り処理へ限定します。
自動呼び出しと手動呼び出しを制御する
Skillsは利用者が/名前で呼ぶだけでなく、descriptionに合う場面でClaudeが選ぶこともできます。ただし、副作用のある作業まで自動選択の候補にすると、実行時期を人が管理しにくくなります。
2つのfrontmatterを使い分けます。
| 設定 | 利用者が呼ぶ | Claudeが呼ぶ | 適する用途 |
|---|---|---|---|
| 指定なし | 可能 | 可能 | 読み取り、説明、補助知識 |
disable-model-invocation: true |
可能 | 不可 | デプロイ、送信、確定操作 |
user-invocable: false |
不可 | 可能 | 背景知識、内部ルール |
「自動化したいから、すべてClaudeに選ばせる」という設計は安全性と一致しません。自動化するのは手順であり、実行判断まで自動にする必要はないからです。外部へ影響するSkillは手動限定にし、本文にも確認条件と停止条件を書きます。
allowed-toolsは権限の事前承認として使う
allowed-toolsは、Skillを呼び出したターンで指定ツールを事前承認する設定です。毎回の確認を減らせますが、「列挙したツール以外を使えなくする設定」ではありません。公式文書も、ほかのツールは通常のpermission設定に従って呼び出せると説明しています。
allowed-tools: Bash(git status *) Bash(git diff *) Read Grep読み取り専用Skillなら、必要なコマンドを狭いパターンで指定します。Bash(*)のような広い許可は、手順変更時に想定外の操作まで承認するため避けます。Skillのallowed-toolsによる承認は次のユーザーメッセージで解除され、恒久的な許可にはなりません。
使えるツール自体を減らしたい場合はdisallowed-tools、セッションや組織全体で制御したい場合はsettingsのpermissionルールを使います。権限の考え方はClaude Codeセキュリティ完全ガイドでも解説しています。
Claude Codeの導入範囲や権限設計を社内だけで決めにくい場合は、現状の業務とリスクを整理する段階からご相談いただけます。
サポートファイルで長い手順を分割する
実務のSkillは、例、判定基準、出力テンプレートが増えます。すべてをSKILL.mdへ詰め込むと、実行時に関係のない情報まで読み込まれ、変更箇所も見つけにくくなります。
Skills形式では、同じディレクトリに補助ファイルを置けます。
.claude/skills/review-release/├── SKILL.md├── references/│ └── quality-criteria.md├── templates/│ └── report.md└── scripts/ └── collect-diff.shSKILL.mdには作業の入口、手順、停止条件を残し、詳細な基準は参照ファイルへ分けます。Anthropicの公式文書はSKILL.mdを500行未満に保つよう勧めています。分割の目的は行数だけを減らすことではありません。どの場面で何を読むかを本文から案内し、不要な資料を毎回開かない構造にします。
スクリプトを同梱する場合は、Skill本文と別にテストします。自然言語の手順を直してもスクリプトの副作用は変わらないため、実行権限、入力検証、終了コードをコードとして確認する必要があります。
実務で使える3つのテンプレート
最初から長い業務フローを移すより、結果を比較しやすい定型作業を選びます。次の3つは入力と出力が明確で、読み取り専用から始められます。
変更差分の要約
---description: 未コミット差分を機能単位で要約し、確認漏れを報告します。disable-model-invocation: trueallowed-tools: Bash(git diff *) Bash(git status *)---差分を読み、変更目的、影響範囲、未確認のテストを報告してください。ファイルは編集しないでください。評価では、実際の差分と要約の一致、変更ファイルの取りこぼし、編集が発生していないことを確認します。
指定ファイルのレビュー
---description: 指定された1ファイルを保守性とエラー処理の観点で確認します。argument-hint: [file]disable-model-invocation: trueallowed-tools: Read Grep---$0 を読み、問題を重大度順に報告してください。各指摘に行番号、理由、最小の修正案を付けてください。対象を1ファイルに限定すると、レビュー基準の不足を見つけやすくなります。結果が安定してから複数ファイルへ広げます。
リリースノートの下書き
---description: 指定した基準ブランチとの差分からリリースノート案を作ります。argument-hint: [base-branch]disable-model-invocation: trueallowed-tools: Bash(git log *) Bash(git diff *)---$0 との差分を確認し、利用者への影響がある変更だけを分類してください。事実を確認できない項目は「要確認」と表示してください。公開文を自動確定せず、下書きとして人が確認します。Skillが流暢な文章を返しても、製品仕様との一致は別の検証対象です。
チーム共有ではレビューと所有者を決める
Project SkillをGit管理すれば、同じリポジトリを使うメンバーへ配布できます。ただし、共有ファイルになった時点で、プロンプトの便利さより変更管理が重要になります。指示の1行が、全員の実行手順を変えるからです。
最低限、次の運用を決めます。
- Skillごとに目的と所有者を記録する
SKILL.md、サポートファイル、スクリプトをコードレビュー対象にするallowed-toolsと動的コンテキストの変更を重点確認する- 正常系、引数不足、対象なし、コマンド失敗をテストする
- 期待出力の例と、実行してはいけない操作を残す
- 更新後は小さな検証用リポジトリで試す
プロンプトは「守ってほしい手順」をClaudeへ伝えますが、違反を機械的に止める保証にはなりません。特定操作の前後で必ず検査したい場合はHooksのほうが適します。両者の役割はClaude Code Hooks完全ガイドで確認できます。
外部リポジトリを初めて開く場合は、Claude Codeを実行する前に.claude/配下を確認します。Skillはツールの事前承認やシェル出力の注入を含められるため、アプリケーションコードと同じ水準で出所と差分を見る必要があります。
旧形式の移行とトラブルを切り分ける
旧.claude/commands/は現在も動くため、移行は停止対応ではありません。追加機能が必要なものから段階的に進めます。
移行は次の順序なら戻しやすくなります。
- commands配下のファイル名、用途、利用者を棚卸しする
- PersonalとProjectに同名定義がないか確認する
.claude/skills/<name>/SKILL.mdへ内容を移す- 引数、出力、権限を旧版と比較する
- 新版を共有してから旧ファイルを削除する
同名のSkillはcommandより優先されます。比較中に両方を同名で置くと、旧版を試しているつもりでも新版が動きます。一時的に名前を分けるか、呼び出された提供元を/skillsで確認します。
動かない場合は症状ごとに切り分けます。
| 症状 | 確認する点 |
|---|---|
/メニューに出ない |
保存場所、SKILL.mdの大文字表記、起動位置 |
| 作成直後に見えない | セッション開始後にトップレベルskillsディレクトリを新設していないか |
| Claudeが自動選択しない | descriptionに用途と起動条件があるか |
| 別の内容が動く | Personal、Project、commandsの同名競合 |
| frontmatterが効かない | 開始---が1行目か、YAMLが正しいか |
| 権限確認が出る | allowed-toolsのパターンが実行内容と一致するか |
既存のSkillディレクトリ内にあるSKILL.mdの変更は、通常セッション中に検知されます。ただし、セッション開始時に存在しなかったトップレベルのskillsディレクトリを新設した場合は、Claude Codeを再起動して監視対象へ含めます。仕様は更新されるため、最終確認は公式Skills文書と公式CHANGELOGで行います。
よくある質問
Q. .claude/commands/は廃止されましたか？
廃止されたとは公式発表されていません。Anthropicの現行ドキュメントは、既存の.claude/commands/が引き続き動くと説明しています。ただし、新規作成ではサポートファイルや呼び出し制御を使えるSkills形式が推奨です。
Q. Skillsとカスタムコマンドは同じですか？
現在のClaude Codeでは、カスタムコマンドはSkillsへ統合されています。どちらも/名前で呼べます。ただし、Skillsは自動選択、サポートファイル、実行コンテキストなどの追加機能を持つため、完全に同じファイル形式ではありません。
Q. 第1引数は$0と$1のどちらですか？
第1引数は$0です。位置指定は0始まりで、$1は第2引数になります。引数全体をそのまま使う場合は$ARGUMENTSを指定します。
Q. チームで共有するにはどこへ置きますか？
リポジトリ内の.claude/skills/<name>/SKILL.mdへ置き、Gitで管理します。共有前に本文だけでなく、allowed-tools、動的コンテキスト、同梱スクリプトもレビューします。個人だけで使う場合は~/.claude/skills/を選びます。
Q. Claudeに自動実行させない方法はありますか？
frontmatterへdisable-model-invocation: trueを追加します。利用者が/名前と入力した場合だけ呼び出せるため、デプロイや外部送信など、実行時期を人が決める作業に適しています。
まとめ
Claude Codeカスタムコマンドは、繰り返す指示を/名前で再利用し、作業基準をそろえる仕組みです。現在はSkillsへ統合されており、新規作成では.claude/skills/<name>/SKILL.mdを選びます。旧.claude/commands/は継続動作するため、追加機能が必要なものから移行すれば十分です。
最初の1本は、変更差分の要約など読み取り専用の作業にします。入力、出力、禁止操作、完了条件を決め、期待する結果と実際のファイル変更を確認してください。安定してから引数、サポートファイル、チーム共有へ広げると、問題の原因を切り分けられます。
Claude Codeを含むAI活用の運用設計をご相談ください
株式会社NexaのAI顧問では、対象業務の整理、権限設計、検証方法、社内展開までを支援しています。読み取り専用の小さな試行から始めたい段階でもご相談いただけます。
