ユタラボ
🚀 Claude Code入門 2026.07.26 更新

Claude Codeのカスタムコマンド作成入門｜繰り返す指示を短く再利用する

Claude Codeで繰り返す指示をカスタムコマンドとして再利用する方法を、現在推奨されるSkills形式、保存場所、引数、チーム共有、トラブル対処まで解説します。

Claude Codeで同じ確認手順を何度も入力しているなら、カスタムコマンドにすると短い名前で呼び出せます。2026年7月26日に公式資料を確認したところ、従来のカスタムコマンドはSkillsへ統合されています。.claude/commands/の既存ファイルは引き続き動きますが、新規作成では.claude/skills/<名前>/SKILL.mdが推奨形式です。

この記事ではSkills形式で作ります。常に守らせたい短い規則はCLAUDE.mdの書き方へ、必要なときだけ呼ぶ手順はSkillへ分けます。この分け方の理由も、公式資料を根拠に説明します。

カスタムコマンドは現在Skillsとして作る

Skillとは、指示文・チェックリスト・補助資料をひとつのフォルダにまとめた再利用の仕組みです。/review-articleのような短い名前で呼び出せます。公式のSkillsページは、「同じ指示や複数の手順を何度も貼り付けている」場合にSkillを作るよう案内しています。

「じゃあ昔のカスタムコマンドはもう使えないの？」と不安になるかもしれませんが、廃止ではありません。Agent SDKの公式ページは、.claude/commands/を旧形式(legacy)、.claude/skills/<名前>/SKILL.mdを推奨形式とした上で、両方を引き続きサポートすると明記しています。.claude/commands/deploy.mdも.claude/skills/deploy/SKILL.mdも、どちらも/deployというコマンドになります。既存の資産はそのまま動くので、新しく作るものだけSkills形式にすれば大丈夫です。

Skillに向いているのは、開始条件と終了条件が決まった反復作業です。「変更内容を三点で要約する」「記事を決まった観点で検品する」などに名前を付ければ、長い依頼を貼り直さずに済みます。

逆に、その日だけの相談や、対象ごとに手順が大きく変わる仕事には不向きです。Skillは命令文の再利用であり、結果を保証するプログラムではありません。機械的な検査にはテストやClaude Code Hooksによる自動検品を使います。

最初の1本は、次の条件を満たす作業から選びます。

  • 複数回、ほぼ同じ指示を入力している
  • 対象と期待する出力を言葉で説明できる
  • 読み取りや下書きなど、失敗しても戻しやすい

CLAUDE.md・Skill・Hookを目的で選ぶ

似た仕組みでも、読み込まれるタイミングと役割が異なります。迷ったら、毎回参照する規則はCLAUDE.md、必要なときに呼ぶ手順はSkill、特定のイベントで確実に動かす処理はHookと考えると整理しやすくなります。

仕組み主な役割動くタイミング向いている例
CLAUDE.mdプロジェクト共通の前提や規則セッションを通じて参照使用するパッケージ管理ツール、命名規則
Skill再利用する知識や作業手順手動呼び出し、または説明に合う依頼記事レビュー、定型の調査手順
Hookイベントに連動する自動処理ツール実行前後、編集後、停止時など編集後のLint、危険なコマンドの拒否

この三分法は公式資料の説明に沿っています。メモリの公式ページは、CLAUDE.mdには毎セッションで必要なビルドコマンドや規約を書き、複数の手順に育った内容はSkillへ移すよう案内しています。またCLAUDE.mdは強制の設定ではなく、モデルへ渡す文脈(=参考にする前提知識)として扱われます。

一方でHooksの公式ガイドは、Hookを「モデルの判断に頼らず、決まった時点で必ず実行する仕組み」と説明しています。Skillの出力はモデルの判断を含むため、同じ入力でも表現が完全には一致しない場合があります。必ず同じ判定を適用したい処理は、Skillの文章だけに任せずHookやテストへ分けます。

最小のSkillを作り、引数で使い回す

まず、Skillの保存場所で利用範囲が決まることを押さえます。

使う範囲保存場所用途
個人の全プロジェクト~/.claude/skills/<skill-name>/SKILL.md自分共通の文章整理や確認手順
今のプロジェクト.claude/skills/<skill-name>/SKILL.mdリポジトリ固有の検品や作業手順
組織全体管理設定で配布管理者が統一する手順

同名のSkillがある場合は、管理設定(組織)、個人用、プロジェクト用の順に優先されます。同名の旧.claude/commands/ファイルがある場合は、Skillの方が優先されます。チーム固有ならプロジェクト用、自分共通なら個人用を選びます。

次に、プロジェクト直下の.claude/skills/review-article/SKILL.mdへ次を保存します。

---
description: 記事下書きを読み、構成、根拠、読みやすさを確認する
disable-model-invocation: true
---

指定された記事を読み、次の順で報告してください。

1. 結論と見出しが一致しているか
2. 事実に根拠または要確認表示があるか
3. 初心者が迷う専門用語に説明があるか

ファイルは変更せず、重要な指摘から最大5件を示してください。

呼び出し名はフォルダ名から決まるので、これで/review-articleが使えます。公式のSkillsページによると、frontmatter(=先頭の---で囲む設定欄)の項目はすべて任意です。nameも省略でき、省略時はフォルダ名が表示に使われます。ただしdescriptionだけは書くのがおすすめです。Claudeが「このSkillを今使うべきか」を判断する材料になるからです。disable-model-invocation: trueを付けると自動判断での実行を止め、利用者が/名前で明示したときだけ動きます。

まずは読み取りと報告だけで試します。権限の公式ページの既定では、作業フォルダ内のファイル読み取りは承認不要ですが、編集やシェル実行は承認の対象です。最初のSkillを読み取り専用にすれば、失敗しても壊れるものがありません。編集やコマンドを許可する前に、Claude Codeの権限設定も確認してください。

対象ファイルを毎回変えたいときは、呼び出し名の後ろの文字を引数(=Skillへ渡す値)として受け取ります。

---
description: 指定された記事下書きを検品する
argument-hint: '<記事ファイル>'
disable-model-invocation: true
---

次の記事を読み取り専用で検品してください。

対象: $ARGUMENTS

/review-article src/content/articles/example.mdと入力すると、$ARGUMENTSが入力した文字全体に置き換わります。位置を分けたいときは番号付きの変数を使います。番号は0始まりで、$0が1番目、$1が2番目の引数です。frontmatterへarguments: [file, audience]と宣言すれば、本文で$fileと$audienceという名前でも受け取れます。空白を含む値は/convert-doc guide.md "初めて使う人"のように引用符で囲んで一つの引数にします。

細かい挙動も公式に載っています。対応する値がない番号付き変数は文字列のまま残り、値がない名前付き変数は空文字になります。また、引数付きで呼んだのに本文へ$ARGUMENTSが無い場合は、本文の末尾へARGUMENTS: <入力値>が自動で追加されます。「$fileが空なら変更せず対象を尋ねる」のような保険の一文を書いておくと安全です。

動作確認と、動かないときの確認順

作ったら必ず動かして確かめます。Anthropicの公式Skills実例リポジトリも、重要な用途で頼る前に自分の環境で十分に試すよう明記しています。合格確認は次の順です。

  1. 入力欄で/を打ち、候補一覧にreview-articleが出るか確かめる(/skillsでも一覧を確認できます)
  2. 実際に/review-article 対象ファイルのパスの形で呼ぶ
  3. 出力が指示どおりか、対象外のファイルを変更していないかを確かめる
  4. 期待とずれたら、description・対象・禁止事項・出力形式を具体化して直す。「いい感じに直す」ではなく「変更せず、重大な指摘から最大5件」と書く

呼び出せないときは、次の順で確認します。

  1. パスが.claude/skills/<名前>/SKILL.mdになっているか
  2. ファイル名SKILL.mdの大文字・小文字と、先頭の---が正しいか
  3. 同名の個人Skill・組織Skill・旧commandsと競合していないか(優先順位は組織 > 個人 > プロジェクト、Skill > 旧commands)
  4. /reload-skillsを実行して再読み込みする。公式のCommandsページには、このコマンドがSkillとコマンドのフォルダを再走査すると記載されています(v2.1.152で追加との記載。版が古いと使えないため、お使いの版は公式案内で確認してください)
  5. 起動時に最上位のskillsフォルダ自体が存在せず、後から新設した場合は、Claude Codeを再起動する

もう一つ、共有前に知っておきたい注意があります。frontmatterのallowed-toolsは「使えるツールを制限する欄」ではありません。そのSkillを呼んだターンだけ、列挙したツールを承認なしで使えるようにする事前許可の欄で、許可は次のメッセージで解除されます。さらに、プロジェクト内Skillのallowed-toolsはリポジトリを信頼(workspace trust)した後に効きます。リポジトリ内のSkillが自分へ広い権限を与えられる作りのため、公式は信頼する前にプロジェクトSkillの中身を確認するよう注意しています。よそから持ってきたリポジトリを開くときは、.claude/skills/の中を先に読みましょう。削除・公開・デプロイを行うSkillはdisable-model-invocation: trueで手動実行だけにする設計が安全です。

最後に、肥大化の防ぎ方です。Skill本文は使ったときに会話へ読み込まれ、その後も文脈に残ります。一つのSkillは一目的に絞り、毎回使う指示だけをSKILL.mdへ残して、長い仕様や例は同じフォルダの補助ファイル(reference.mdやexamples.mdなど)へ分けます。公式資料はSKILL.mdを500行未満に保つよう勧めていますが、上限まで埋める目標ではありません。AnthropicはAgent Skillsの設計解説で、最初は名前と説明だけを知らせ、必要になったときに本文や参照ファイルを読む「段階的開示」を中核の考え方として説明しています。短い目次と中核手順だけをSKILL.mdに置くのが、この設計に沿ったやり方です。

よくある質問

Claude Codeのカスタムコマンドは廃止されたのですか？

廃止ではありません。.claude/commands/の既存ファイルは引き続き利用できます。ただし、カスタムコマンドはSkillsへ統合されており、補助ファイルや自動呼び出しの制御を使える.claude/skills/<名前>/SKILL.mdが新規作成の推奨形式です。Agent SDKの公式ページも、旧形式と推奨形式の両方を引き続きサポートすると明記しています。

個人用とプロジェクト用のどちらに置けばよいですか？

複数の案件で共通して使う自分だけの手順は~/.claude/skills/、特定リポジトリの構成やルールに依存し、チームで共有する手順は.claude/skills/が向いています。チーム共有するファイルには、個人の絶対パス・トークン・メールアドレスなどの秘密情報を書きません。

SkillはClaudeが自動で実行しますか？

既定では、利用者が/名前で呼ぶことも、Claudeがdescriptionを見て必要と判断して呼ぶこともできます。自動で呼ばせたくない場合はdisable-model-invocation: trueを設定します。逆にuser-invocable: falseは、/の一覧から隠してClaudeだけが呼べるようにする、向きが反対の設定です。

Skillを作ったのに一覧へ表示されないのはなぜですか？

保存先のパス、SKILL.mdというファイル名、frontmatterのYAMLの区切りを順に確認してください。その上で、現行版にある/reload-skillsで再読み込みします。セッション開始時に最上位のskillsフォルダ自体が存在せず、後から新設した場合は、公式のSkillsページが再起動を案内しています。版によって対処が違うため、直らないときは公式ページの最新の記載を確認してください。

Skillだけで必ず同じ検査結果になりますか？

なりません。Skillはモデルへ手順を渡す仕組みなので、結果を完全には固定できません。毎回必須の機械検査や禁止処理は、テスト・Claude Code Hooksによる自動検品・権限設定へ分けます。Skillは観点の整理や結果の要約に使うのが向いています。

まとめ

新規作成はSkills形式、最初はプロジェクト用の読み取り専用Skill、安定してから引数や補助ファイルを足す。この順番なら、短く呼べて直しやすい仕組みになります。次にやることは3つです。

  • 繰り返し貼っている指示を1つ選び、.claude/skills/<名前>/SKILL.mdへ読み取り専用の最小Skillとして保存する
  • /名前で実際に呼び、出力の中身と「対象外のファイルを変えていないこと」を確かめる。ずれたらdescription・対象・禁止事項・出力形式を直す
  • 安定してから引数・補助ファイル・チーム共有へ広げる。仕様は版で変わりやすいので、広げる前に公開時点の公式Skillsページを開いて確認する

公式一次情報

確認日: 2026-07-26

続き（結論と実データ）はnoteに置いています

ここでは手順のところまで書きました。実際に出た数字、うまくいかなかった条件、そのまま使える設定ファイルは、 note の記事にまとめてあります。

noteで続きを読む Xをフォローする

🚀 入門

Claude Code完全ガイド｜導入・指示・権限・自動化・トラブル対応の全体像

Claude Codeを初めて使う人が、導入からプロジェクトルール、権限管理、Hooks、MCP、検品、引継ぎまでを安全に組み立てるための総合ガイドです。
🚀 入門

Claude Codeが前の指示を忘れるときの対策｜コンテキスト不足を見分けて立て直す

Claude Codeが前の指示を忘れたように見える原因を、コンテキスト不足と仕様不足に分け、短い記録、工程分割、差分確認で安全に立て直す手順を解説します。
🚀 入門

Claude Codeでgit worktreeを使う手順｜複数作業のファイル衝突を防ぐ

Claude Codeの作業をgit worktreeで分離し、複数セッションの編集衝突を防ぐ手順を、作成・起動・統合・片付けまで順番に解説します。