Claude Code スラッシュコマンド 作り方｜.claude/commands カスタムコマンド完全ガイド【2026年最新版】

.claude/commands/<name>.md にMarkdownを1枚置くと、そのまま /name として使えます。 ただしカスタムコマンドは2026年1月のv2.1.3でスキル（Skills）に統合されており、これから作るなら .claude/skills/<name>/SKILL.md が公式のおすすめです（旧形式のファイルも今まで通り動きます）。

この記事は、Claude Code v2.1.301（2026年10月15日リリース）時点の公式ドキュメント（Skills / Commands / Changelog）を確認して書いています。

この記事でわかること

• スラッシュコマンドの種類（組み込み・バンドルスキル・カスタム・MCPプロンプト・プラグイン）と違い
• Skills統合で何が変わったか、.claude/commands/ のままでよいケースと移すべきケース
• .claude/commands/ と .claude/skills/<name>/SKILL.md の作り方（最小サンプル付き）
• フロントマター全フィールド、引数（$ARGUMENTS / $0 / 名前付き）、! によるシェル出力の埋め込み
• そのまま使える実務テンプレート6本（/commit・/pr-summary・/quick-review・/test・/refactor・/docs）
• 呼び出し制御（disable-model-invocation / user-invocable）と skillOverrides
• 2026年10月時点の組み込みコマンド一覧と、廃止・改名されたコマンド
• 他人が作ったコマンドを入れるときのセキュリティ上の注意
• 動かないときのトラブルシュート

誰向けの記事か

• Claude Code を毎日使っていて、よく打つ指示を1コマンドにまとめたいエンジニア
• .claude/commands/ に書きためた資産をSkills形式へ移すか迷っている開発チーム
• /commit や /review のような共通の手順をGitで配布したいリードエンジニア
• Codex・Gemini CLI・Cursor で使っていたカスタムコマンドをClaude Code に持ってきたい人

Claude Code そのものの全体像は Claude Codeとは？できること・料金・使い方・他ツール比較、インストールから基本操作までは Claude Codeの使い方ガイド にまとめています。

スラッシュコマンドとは（3種類の整理）

出典: Anthropic（claude.com）

スラッシュコマンドは、Claude Code の入力欄で / から始めて実行する機能です。メッセージの先頭に書いたときだけコマンドとして認識され、コマンド名の後ろに続く文字は引数として渡されます。大きく分けると次の3種類で、ここに外部から入ってくる2種類が加わります。

このほか、/deep-research のように多数のサブエージェントに作業を振り分けてバックグラウンドで実行する「Workflow」も同梱されています。

カスタムコマンドを作ること自体に追加料金はかかりません。ただし Claude Code は Free プランでは使えず、Pro・Max・Team・Enterprise のいずれか、または API（Console の従量課金）が前提です。プランごとの金額は Claude Code料金【日本円換算】 で詳しく扱っています。

表示される組み込みコマンドは、OS・プラン・接続先（Anthropic直か Bedrock などのクラウド経由か）で変わります。例えば /desktop は macOS と x64 版 Windows のサブスク利用者にだけ出ます。

【重要】Skills統合で何が変わったか

カスタムコマンドとスキルは、2026年1月のv2.1.3で1つの仕組みにまとめられました。 Changelog には「Merged slash commands and skills, simplifying the mental model with no change in behavior（動作は変えずに統合）」とあります。日本語の解説記事では統合日が「1月24日」「4月のv2.1.101」など食い違っていますが、公式Changelog上はv2.1.3の項目です。

公式Skillsページの説明は次の通りです。

Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Your existing .claude/commands/ files keep working.

実務で押さえておくことは次のとおりです。

1. 旧形式 .claude/commands/<name>.md は今も動く
2. 新しく作るなら .claude/skills/<name>/SKILL.md（補助ファイルを置ける・自動起動の制御ができる）
3. 同じ名前のスキルとコマンドファイルがあればスキルが優先される

旧形式と新形式の違い

Claude Code のスキルは Agent Skills オープン標準（agentskills.io） に沿っていて、そこに「呼び出しの制御」「サブエージェントでの実行」「シェル出力の埋め込み」を Claude Code 独自に足した形です。

commands のままでよいか、skills に移すべきかの判断表

SKILL.md の書き方や、Claude が自動で読み込むスキルの設計を深く知りたい場合は Claude Code Skills 使い方完全ガイド を参照してください。この記事では「/ で自分で呼ぶコマンド」を作る視点に絞って説明します。

カスタムコマンドの作り方（旧形式：.claude/commands/）

出典: Anthropic

一番手早いのはこの形式です。既存プロジェクトに置かれているコマンドを読むときにも、この仕組みを知っておくと迷いません。

手順

1. プロジェクトのルートに .claude/commands/ フォルダを作る
2. <コマンド名>.md を置く
3. 本文に Claude への指示を書く

最小のサンプルです。

<!-- .claude/commands/hello.md -->
Hello world と日本語で返事してください。

このファイルを置けば、セッション内で /hello が使えます。ファイル名（.md を除いた部分）がコマンド名になります。セッション中に作った場合も、既存の監視フォルダ内であれば再起動せずに反映されます。

サブフォルダに置いたときの名前

現行の仕様では、.claude/commands/ の下のサブフォルダはコマンド名に : 区切りで入ります。

以前は「サブフォルダは名前に影響せず、説明欄に (project:frontend) と表示される」という説明が一般的でした。古い記事を参考にする場合はこの違いに注意してください。

保存場所の違い（プロジェクト vs ユーザー）

デプロイ・コミット・PR要約のようにチームでそろえたいものはプロジェクト側に置いてコミットし、自分だけの検索・要約ユーティリティはユーザー側に置く、という分け方が基本です。

カスタムスキルの作り方（新形式：.claude/skills/SKILL.md）

新しく作るならこちらです。フォルダ単位になるので、テンプレートやスクリプトを一緒に置けるうえ、呼び出し方を細かく制御できます。

手順

1. .claude/skills/<コマンド名>/ フォルダを作る
2. その中に SKILL.md を置く（必須）
3. 必要ならテンプレートや参考資料を同じフォルダに追加する

最小のサンプルです。

<!-- .claude/skills/hello/SKILL.md -->
---
name: hello
description: 日本語で挨拶を返す。動作確認のときに使う。
---

Hello world と日本語で返事してください。

これで /hello が使えるほか、description の内容に合う場面では Claude が自分で呼び出す候補にもなります。勝手に動いてほしくないコマンドには、フロントマターに disable-model-invocation: true を足します。

フォルダ構成（補助ファイルの置き方）

.claude/skills/
├── commit/
│   ├── SKILL.md          # 必須。本体（500行以内が目安）
│   ├── examples.md       # 補助。必要なときだけ Claude が読む
│   └── template.txt
└── deploy/
    ├── SKILL.md
    └── scripts/
        └── check.sh

補助ファイルは SKILL.md の本文から「詳しい例は [examples.md](examples.md) を参照」のようにリンクしておくと、Claude が必要になった時点で開きます。SKILL.md 本体は500行以内に収め、長い資料は別ファイルに分けるのが公式のすすめです。スクリプトの場所は ${CLAUDE_SKILL_DIR}/scripts/check.sh のように書けば、どこから起動しても正しいパスになります。

保存場所と優先順位（4スコープ）

スキルやカスタムコマンドを置ける場所は、主に4つのスコープです。これに加えて、モノレポ用のネストした置き場所などがあります。

そのほかの置き場所は次の通りです。

同じ名前がぶつかったときは Enterprise > Personal > Project の順で優先されます。プラグインのスキルは名前空間付きなので、同名でも両方読み込まれます。

モノレポでは、起動したフォルダからリポジトリのルートまでさかのぼって各階層の .claude/skills/ を読み込みます。サブフォルダにある .claude/skills/ は、そのフォルダのファイルに初めて触れた時点で読み込まれます。名前が重なった場合、たとえば apps/web/.claude/skills/deploy/SKILL.md は /apps/web:deploy として区別されます。

なお、synced というフォルダ名と anthropic-skills（および anthropic-skills: で始まる名前）は予約されているので使えません。

フロントマター完全リファレンス

フロントマターは、SKILL.md（または .claude/commands/<name>.md）の1行目から --- で囲んで書く設定です。どれも省略できますが、description だけは実務では必ず書きます。 Claude が「いま使うべきか」を判断する材料になるからです。

書くときの細かい決まりもあります。

• description と when_to_use は合計1,536文字で切り詰められます（設定 skillListingMaxDescChars で変更可）
• 真偽値は true/false のほか yes/no on/off 1/0 も使えます（v2.1.218以降、大文字小文字は問わない）
• YAMLの書き方が壊れていると、フロントマターを無視して本文だけ読み込まれます。/name では動くのに自動起動しない、allowed-tools が効かない、というときはまずここを疑います。claude plugin validate .claude/skills で検査できます（v2.1.233以降）
• claude.ai へのアップロードや Skills API では、name description license compatibility metadata allowed-tools 以外のキーがあるとエラーになります。Claude Code 専用の項目を入れたスキルを claude.ai に持っていくときは削ってください

最初は description だけで十分です。副作用がある操作なら disable-model-invocation: true、シェルの結果を埋め込むなら allowed-tools、特定のファイルでだけ使わせたいなら paths、と必要に応じて足していきます。

paths フィールドの活用（モノレポ向け）

paths を書くと、パターンに合うファイルを扱っているときだけ Claude の自動起動の候補になります。TypeScript を触っているときだけ型チェック用のスキルを使わせたい、といった場面で、関係ないところで誤って起動されるのを防げます。

---
name: ts-check
description: TypeScriptの型エラーを確認する
paths: "src/**/*.ts"
---

/ts-check と手で呼ぶことは、どのファイルを触っていてもできます。

引数と文字列置換（プレースホルダー）

/my-command "hello world" branch-a のように渡した引数は、本文の中で次の書き方で受け取れます。番号は0から始まる点に気をつけてください。

公式の例では、/migrate-component SearchBar JavaScript TypeScript と入力すると $0 が SearchBar、$1 が JavaScript、$2 が TypeScript になります。「$1 が1つ目」と書いている古い解説もあるので、手元のコマンドがずれていないか確認しておきましょう。

ほかにも覚えておくと便利な決まりがあります。

• 空白を含む引数はクオートで囲みます。/my-skill "hello world" second なら $0 が hello world、$1 が second
• 本文に $ARGUMENTS などが1つもない場合は、末尾に ARGUMENTS: <入力> が自動で付きます
• $ を記号のまま書きたいときは \$1.00 のようにエスケープします
• /write-tests /fix-issue 123 のようにスキルを先頭に並べると両方読み込まれ、末尾の 123 が各スキルの $ARGUMENTS に渡されます。並べられるのは最大6個です

名前付き引数の例

---
name: migrate-component
argument-hint: "[component] [from] [to]"
arguments: [component, from, to]
---
$component を $from から $to に書き換えてください。
既存のテストが通ることを確認してから終了してください。

/migrate-component SearchBar React Vue と入力すると、$component が SearchBar、$from が React、$to が Vue になります。引数が3つ以上あるコマンドは、番号より名前で書いた方が読み返したときに分かりやすくなります。

! でBashコマンドを埋め込む（動的コンテキスト注入）

本文に !`コマンド` と書くと、Claude が本文を読む前にそのコマンドが実行され、出力に置き換わります。

## プルリクエストの情報
- 差分: !`gh pr diff`
- コメント: !`gh pr view --comments`

## やること
上のプルリクエストを3行で要約してください。

ここで実行しているのは Claude ではなく、手元のシェルです。Claude には結果のテキストだけが渡ります。gh や git の認証情報を持ったまま動くので、他人が書いたコマンドを入れるときは中身の確認が欠かせません。

複数行のコマンドは、```! で始まるコードブロックに書きます。

```!
git log --oneline -n 10
git status --short
node --version
```

動かすときに引っかかりやすい決まりは次の通りです。

「手で呼んだら途中で止まった」というときは、allowed-tools に該当コマンドが入っているかと、コマンドの終了コードをまず確認します。なお、カスタムコマンドで埋め込んだシェルの行が2回実行される不具合は v2.1.299 で直っています。

@ でファイル内容を差し込む

指示の中で @src/auth/login.ts のようにパスに @ を付けると、Claude にそのファイルを指し示せます。普段の会話で使う @ の参照と同じ感覚で、コマンドの本文にも書けます。

@docs/auth-spec.md の要件に沿っているか、$0 をレビューしてください。

使い分けの目安はこうです。

現行の公式Skillsページは、補助ファイルを SKILL.md からMarkdownリンクで参照する書き方を案内しています。長い資料を毎回読み込ませないためにも、スキルの補助資料はリンクで参照するのがおすすめです。

呼び出し制御（disable-model-invocation / user-invocable）

同じコマンドでも、誰が起動できるかを設定で分けられます。

実務での推奨

• デプロイ・コミット・DB書き込み・Slack送信など「勝手に動いたら困る」ものは disable-model-invocation: true
• 要約・テスト案の作成など「気を利かせて使ってくれると助かる」ものは既定のまま
• Claude にだけ使わせたい内部向けの手順は user-invocable: false

disable-model-invocation: true のスキルは description がコンテキストに載らないので、スキルが増えたときのトークン節約にもなります。

権限ルールでも同じことができます。Skill(commit) は完全一致、Skill(review-pr *) は前方一致で、deny に Skill(deploy *) と書けば Claude からも手動でも使えなくなります。Skill ツールそのものを deny すると、すべてのスキルが止まります。

skillOverrides でスキルの可視性を設定から制御

スキルが増えてきたら、skillOverrides で1つずつ表示や読み込み方を変えられます。/skills 画面で Space を押して切り替え、Enter で保存すると、.claude/settings.local.json に書き込まれます（t でトークン数の多い順に並べ替えられます）。

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

プラグインのスキルには効かない点に注意してください。

スキルが多すぎるときの目安

スキル一覧に使えるコンテキストは、モデルのコンテキストウィンドウの1%が既定です。超えると、使われる頻度の低いスキルから description が一覧から落ち、自動起動されにくくなります。

• /doctor で一覧の量を見積もる
• /skill-doctor（v2.1.252以降）で、スキルごとのトークン量と使用頻度を確認する
• あまり使わないスキルは "name-only" か disable-model-invocation: true にする
• どうしても足りなければ skillListingBudgetFraction（例：0.02）か環境変数 SLASH_COMMAND_TOOL_CHAR_BUDGET で枠を広げる

トークン消費全体の見直し方は Claude Code コスト最適化完全ガイド にまとめています。

サブエージェント実行（context: fork）

重い調査をメインの会話と切り離したいときは、context: fork でサブエージェントに任せます。

---
name: investigate
description: 指定したテーマについてリポジトリ全体を調べる
context: fork
agent: Explore
---

$ARGUMENTS について調べてください。
1. Glob / Grep で関係するファイルを洗い出す
2. コードを読み、ファイル名と行番号を付けて要約する

• SKILL.md の本文が、新しいサブエージェントへの指示になります。それまでの会話履歴は引き継がれません
• agent には Explore（調査向け）、Plan（計画向け）、general-purpose（汎用）や自作のエージェントを指定します
• 既定ではバックグラウンドで動き、結果を待ちません。結果を受け取ってから次に進みたい場合は background: false を付けます。-p での実行、Agent SDK、スケジュール実行などでは自動的に待ちます
• バックグラウンドで動く fork は使えるツールが絞られます。また、そこで行った編集は /rewind では戻せません

/deep-research という同梱コマンドと名前がぶつからないよう、自作する場合は別の名前を付けておきましょう。サブエージェントの設計そのものは Claude Code サブエージェント 使い方 で解説しています。

context: fork には具体的な作業指示が必要です。「このAPIの規約に従う」のような方針だけを書いても、サブエージェントは何をすればいいか分かりません。

ライブ変更検出とスキルのコンテキストライフサイクル

ライブ変更検出（再起動不要）

監視されているフォルダの SKILL.md を編集すると、セッション中でもすぐ反映されます。新しく作ったトップレベルの skills フォルダを読み込ませたいときは、再起動しなくても /reload-skills で取り込めます。

スキルのコンテキストライフサイクル

スキルを呼び出すと本文が会話に追加され、以降のターンにも残ります。あとからファイルを直しても、すでに会話に入った分は書き換わりません。直した内容を使うには、もう一度呼び出します。

自動コンパクション（会話の要約）が実行されたときは、次のように再添付されます。

• スキル1つあたり最大5,000トークン
• 全スキル合計で最大25,000トークン
• 最近使ったスキルが優先され、古いものは外れることがある

長いスキルは後半が切れる可能性があるので、守ってほしい指示は本文の冒頭に書いておくのが安全です。

実務で使えるテンプレート6選（コピペ可）

開発でそのまま使える6本です。.claude/skills/<name>/SKILL.md として置いてください。! でシェルの結果を埋め込むものには、中断を防ぐために allowed-tools を付けています。

命名の注意：v2.1.286以降、プロジェクトか個人のスキルに verify または simplify という名前のものがあると、ドキュメントやテスト以外のコミット前に Claude がそれを実行します。意図せずこの名前を付けないようにしてください（設定 includeGitInstructions をオフにすると無効）。

1. /commit — ステージ済みの差分を Conventional Commits でコミット

---
name: commit
description: ステージ済みの差分から Conventional Commits 形式のメッセージを作ってコミットする。
disable-model-invocation: true
allowed-tools:
  - Bash(git diff *)
  - Bash(git commit *)
---

## 現在の状態
- 変更ファイル: !`git diff --cached --stat`
- 差分: !`git diff --cached`

## やること
上の差分から、Conventional Commits（feat: / fix: / chore: / docs: / refactor: / test:）の形式で
1〜2文のコミットメッセージを作ってください。
作ったら git commit -m "..." を実行してください。差分が空なら何もせずに終了してください。

2. /pr-summary — プルリクエストを3行で要約

---
name: pr-summary
description: 現在のブランチのプルリクエストを3行で要約する。レビュー依頼の前に使う。
argument-hint: "[pr-number]"
allowed-tools:
  - Bash(gh pr view *)
  - Bash(gh pr diff *)
---

## プルリクエストの情報
- 概要: !`gh pr view $ARGUMENTS --json title,body,commits`
- 差分: !`gh pr diff $ARGUMENTS`

## やること
このプルリクエストを
1. 何を
2. なぜ
3. どう実装したか
の3行で要約してください。

プルリクエストがないブランチで実行すると gh が0以外で終わり、呼び出し全体が止まります。必ず番号を渡す運用にするか、各行の末尾に || true を付けてください。

3. /quick-review — 未コミットの差分をレビュー

---
name: quick-review
description: 未コミットの差分をレビューし、ロジック・エラー処理・命名・テスト・セキュリティの観点で指摘する。
allowed-tools:
  - Bash(git diff *)
---

## レビュー対象
!`git diff HEAD`

## やること
次の観点で指摘してください（問題がない観点は省略してかまいません）。
- ロジックの誤り・境界条件
- エラー処理の抜け
- 命名の一貫性
- テストの不足
- セキュリティ（入力チェック・権限・秘密情報）
最後に、直すべき箇所だけをファイル名と行番号付きで箇条書きにしてください。

このテンプレートは /review という名前にしたくなりますが、現在の /review は同梱の /code-review の別名です。自作スキルは同名の組み込みやバンドルスキルを置き換えられる一方、別名は置き換わりません。混乱を避けるため別の名前にしています。本格的なレビューなら同梱の /code-review（--fix で修正まで、--comment でGitHubにコメント）も試してみてください。

4. /test — 指定ファイルのテストを作る

---
name: test
description: 指定ファイルのユニットテストを作る。Vitest / Jest / Pytest などプロジェクトの設定に合わせる。
argument-hint: "[file-path]"
arguments: [file]
---

## 対象
$file

## やること
1. $file を読み、主な関数・クラスを洗い出す
2. package.json や pyproject.toml を見て、使っているテストフレームワークを確かめる
3. 正常系・異常系・境界値の3つの観点でテストケースを設計する
4. 既存のテストの書き方に合わせてテストファイルを新しく作る

5. /refactor — リファクタリング案を出す

---
name: refactor
description: 指定ファイルを読み、責務の分け方・命名・重複の観点でリファクタリング案を出す。
argument-hint: "[file-path]"
arguments: [file]
---

## 対象
$file

## やること
- 責務が混ざっている箇所を指摘する
- 切り出すべき関数・クラスの候補を挙げる
- 命名の改善案を出す
まずは差分を作らず、改善案のまとめだけを出してください。承認されたら差分を作ります。

6. /docs — README と docs/ を更新する

---
name: docs
description: 最近の変更をもとに README と docs/ を更新する。互換性のない変更があれば冒頭で警告する。
disable-model-invocation: true
allowed-tools:
  - Bash(git log *)
  - Bash(git diff *)
---

## 直近の変更
!`git log --since="1 week ago" --oneline`
!`git diff main...HEAD -- README.md docs/`

## やること
- 新機能・APIの変更があれば README と docs/ に反映する
- 互換性のない変更は冒頭で警告する
- 既存の書き方に合わせる

ブランチ名が main でないリポジトリでは、git diff の行を書き換えてください。

これらは .claude/skills/ ごとコミットすればチーム全員で使えます。トークンや社内のエンドポイントを本文に直接書かないようにしてください。

組み込みコマンド主要一覧【2026年10月時点】

/help で全部を表示できますが、v2.1.301時点の公式一覧から、よく使うものを用途別にまとめます。カッコ内は別名です。

応答の途中で送ったコマンドは、基本的にいまのターンが終わってから実行されます。/status /tasks /usage などは例外ですぐ動きます。

/schedule や /loop を使った定期実行は Claude Code Routines 使い方 で、/update-config で触れる設定や権限の考え方は Claude Code チーム導入ガイド で扱っています。

MCPプロンプトもコマンドになる

接続したMCPサーバーがプロンプトを公開していると、/ メニューに /servername:promptname (MCP) の形で出てきます。/mcp__servername__promptname と入力しても実行できます。MCPの接続方法は Claude Code MCP連携ガイド を参照してください。

廃止・改名されたコマンド（注意）

表示されるコマンドは OS・プラン・環境で変わります。最新の一覧は /help か /release-notes で確認してください。

旧形式から新形式への移行ガイド

.claude/commands/ にコマンドを書きためているチーム向けの手順です。

移行手順

1. .claude/commands/<name>.md を .claude/skills/<name>/SKILL.md に移す（サブフォルダにあった frontend/component.md は、名前を frontend-component などに決め直す）
2. フロントマターに description を書く（なければ）
3. 副作用のあるコマンドには disable-model-invocation: true を付ける
4. ! で使うコマンドを allowed-tools に並べる
5. 長いテンプレートや参考資料を補助ファイルに切り出す
6. /skills で新しいスキルが見えるか確認し、元の .claude/commands/ 側のファイルを消す

同名のファイルを両方に残すとスキル側が優先されるため、commands 側を直しても反映されず混乱のもとになります。1本ずつ移して、移したら旧ファイルを消すのが安全です。

Codex・Gemini CLI・Cursor のカスタムコマンドを取り込む

他のツールで作ったコマンドは /import で取り込めます。

コマンドだけでなく、スキル・サブエージェント・MCP設定・指示ファイルもまとめて対象になります。--dry-run を付けると、何が取り込まれるかを先に確認できます。Bedrock・Google Cloud・Microsoft Foundry 経由で使っている場合は利用できません。

思考量の指定（effort）

調査・設計・レビューなどじっくり考えさせたいコマンドは、フロントマターの effort で思考量を上げます。

---
name: plan-feature
description: 新機能の実装計画を作る
disable-model-invocation: true
effort: xhigh
---

$ARGUMENTS の実装計画を、次の観点で作ってください。
- 影響範囲
- 実装の手順
- 想定されるリスク
- 必要なテスト

effort に指定できるのは low / medium / high / xhigh / max です。設定はそのコマンドを呼んだターンにだけ効きます。セッション全体で変えたいときは /effort を使います。

以前は本文に「ultrathink」と書いて長考させる方法がよく紹介されていました。現行の公式Skillsページで案内されているのは effort フィールドと /effort なので、新しく作るコマンドではこちらを使ってください。

Skill / サブエージェント / フック / プラグインの使い分け

Claude Code にはスラッシュコマンド以外にも拡張の仕組みがあり、役割が少しずつ違います。

選び方の目安は次のとおりです。

• 毎回同じ指示を打っている → Skill
• 会話の文脈を汚さずに重い作業をさせたい → サブエージェント（context: fork）
• 「必ず守らせたい」ルールがある → フック。スキルは Claude が守らないこともあるので、公式も強制したいことはフックにするよう案内しています。スキルの hooks フィールドでセットにもできます
• 社外や他チームに配りたい → プラグイン
• 常に知っておいてほしい前提 → CLAUDE.md

それぞれの詳しい使い方は Claude Code Skills vs Hooks 使い分けガイド、Claude Code Hooks 使い方、CLAUDE.md 書き方ベストプラクティス、プラグインの仕組みは Agent Plugins 1.0.0とは で解説しています。

セキュリティ・運用上の注意点

他人が作ったコマンドやスキルは、中身を読んでから使ってください。 本文にシェル実行と事前承認を書けるため、悪意のあるスキルは手元の認証情報を外へ送れてしまいます。

Datadog Security Labs の検証（Malicious skills: supply chain risks in coding agents with dynamic context、2026年5月）では、次のような流れが示されています。

1. クローンしたリポジトリの .claude/skills/ やネストしたフォルダ、プラグイン、--add-dir で足したフォルダから、スキルがセッションに入り込む
2. allowed-tools: Bash(*) で、どんなシェルコマンドも事前承認する
3. ! で gh auth token を実行してトークンを取り出し、curl で外部に送る

! は Claude が本文を読む前に実行されるため、モデル側でプロンプトインジェクションを見抜く仕組みが働く余地がありません。ワークスペースの信頼（trust）を承認しても allowed-tools は止まらない、と公式も明記しています。

導入前のチェック項目

チームで運用するときの設定

1. allowed-tools は必要最小限に：書いたツールは確認なしで動く。Bash(git diff *) のように絞る
2. 副作用のあるコマンドは disable-model-invocation: true：Claude が勝手に /deploy を走らせない
3. 秘密情報を本文に書かない：.claude/skills/ はコミットされてチーム全員に配られる
4. .claude/ の変更はレビュー必須に：CODEOWNERS などでプルリクエストのレビューを必ず通す
5. 管理設定で制限する："disableSkillShellExecution": true で ! を止める。allowManagedPermissionRulesOnly を有効にすると、プロジェクトと個人のスキルの allowed-tools は無視される（v2.1.282以降）。同梱スキルを止めたいなら disableBundledSkills
6. 権限ルールで個別に止める：deny に Skill(deploy *) などを書く

auto モードでは ! の行が権限確認なしで通りやすくなる点も押さえておきましょう。詳しくは Claude CodeのAuto modeとプロンプトインジェクション、全体の安全な使い方は Claude Codeのセキュリティと安全な使い方 と AIコーディング セキュリティ リスクと対策 を参照してください。公開されているコマンド集を探すなら awesome-claude-codeの使い方 や Superpowers for Claude Code 使い方 も参考になりますが、入れる前の確認は同じように行ってください。

コマンドで作った社内向けの小さなツールを、実データや既存の業務システムにつないで使う段階になると、権限の管理や保守の担当、引き継ぎ用の資料といった、コマンドの外側の準備が必要になります。その進め方は AIで作ったアプリを開発会社へ引き継ぐには で整理しています。

こんな人におすすめ

• 同じ指示を毎日打っている（要約・レビュー・コミットメッセージ作成など）
• チームで /commit や /quick-review をそろえて品質のばらつきを減らしたい
• モノレポで、パッケージごとに違う手順を配りたい
• .claude/commands/ の資産をSkills形式に整理したい
• Codex や Cursor で使っていたコマンドを /import で移したい

おすすめしない人

• Claude Code をまだ日常的に使っていない（まず普段の使い方を固めてからで十分）
• 1回しかやらない作業をコマンドにしようとしている（普通に指示した方が早い）
• 本番デプロイや認証情報を扱う手順を、disable-model-invocation と allowed-tools を考えずにコマンド化しようとしている
• 「必ず守らせたい」ルールをコマンドだけで保証しようとしている（フックの出番）

トラブルシュート

コマンドが / メニューに出ない

• 置き場所が .claude/commands/<name>.md か .claude/skills/<name>/SKILL.md になっているか
• サブフォルダに置いた場合、名前が /frontend:component のように : 区切りになっていないか
• 名前に全角スペース・連続したスペース・制御文字・< > などが入っていないか（v2.1.299以降、こうした名前は直すまで候補に出ない）。小文字・数字・ハイフンで付けるのが無難
• 新しく作ったトップレベルの skills フォルダなら /reload-skills
• 権限ルールや skillOverrides で "off" にされていないか（/permissions と /skills で確認）

自分で呼べるのに、Claude が自動で使ってくれない

• フロントマターのYAMLが壊れていないか（壊れていると本文だけ読み込まれる）。claude --debug や claude plugin validate .claude/skills で確認
• description に「何をするか」と「いつ使うか」が具体的に書かれているか
• スキルが多すぎて description が一覧から落ちていないか（/doctor・/skill-doctor で確認）

Claude が勝手に起動してしまう

• description に使う場面を具体的に書く（あいまいだと関係ない場面でも呼ばれる）
• 副作用がある場合は disable-model-invocation: true
• 特定のファイルだけで使わせたいなら paths

呼び出したら途中で止まる

• ! のコマンドが0以外で終わっていないか（許容するなら || true）
• そのコマンドが allowed-tools に入っているか
• Windows で Git Bash が入っていない環境なら、shell: powershell に変える

編集したのに反映されない

• すでに会話に入ったスキルの内容は書き換わらない。もう一度 /<name> で呼び出す
• 同じ名前の commands と skills が両方あると skills が優先される

長いセッションでスキルが効かなくなる

• コンパクション後に残るのは1スキル5,000トークン、合計25,000トークンまで。もう一度呼び出せば戻る
• /rewind の後にスキルが一覧から消える不具合は v2.1.301 で修正済み。古い版なら更新する

個人のスキルが消えた

• ~/.claude/skills/.trash/ を確認する（v2.1.280より前の版では manifest.json があるフォルダがここへ移される不具合があった。ゴミ箱は既定で30日後に削除）

よくある質問（FAQ）

Q1. .claude/commands/ はいつ使えなくなりますか？

2026年10月時点で、公式は「既存のファイルは引き続き動く」としており、廃止の時期は示していません。急いで移す必要はありませんが、補助ファイルや paths が使えるのは skills 形式だけなので、新しく作るものは skills にしておくと後で手間が減ります。

Q2. 組み込みコマンドと同じ名前のコマンドは作れますか？

作れます。公式によると、自分のスキルは同じ名前の組み込みコマンドやバンドルスキルを置き換えます。ただし別名（例：/review → /code-review）は置き換わりません。標準の動きが変わるとチームの他の人が戸惑うので、基本は別の名前にするのがおすすめです。

Q3. スキルの補助ファイルはトークンを消費しますか？

Claude が実際に開いたときだけ消費します。SKILL.md の本文は呼び出したときに読み込まれ、補助ファイルは必要になったときに読まれる仕組みです。長い資料ほど別ファイルに分けておくと節約になります。

Q4. description は日本語で書いても自動起動しますか？

します。判断材料になるので、「差分からコミットメッセージを作る」「プルリクエストを要約する」のように、何をするかと使う場面を具体的に書くのがコツです。

Q5. Windows でも使えますか？

使えます。! のシェルは既定で bash なので、Git Bash が入っていない環境では失敗します。その場合はフロントマターに shell: powershell を書いてください。

Q6. 作ったスキルを claude.ai でも使えますか？

使えますが、claude.ai へのアップロードでは name description license compatibility metadata allowed-tools 以外の項目があるとエラーになります。disable-model-invocation や context など Claude Code 専用の項目は外してからアップロードしてください。逆に claude.ai で有効にしたスキルは、v2.1.273以降ターミナルの ~/.claude/skills/synced/ に同期されます。同期されたスキルでは多くの場合 ! は実行されず、手元で編集しても同期で上書きされます。claude.ai 側でスキルを作る方法は Claude Record a Skillとは で紹介しています。

Q7. 会社で一括管理したいときは？

管理設定（managed settings）のフォルダにスキルを置けば、組織の全員に配布でき、同名の個人・プロジェクトのスキルより優先されます。disableSkillShellExecution で ! を止めたり、allowManagedPermissionRulesOnly で各自の allowed-tools を無効にしたりもできます。

Q8. /run や /verify が表示されません

表示されるコマンドは版・OS・プラン・接続先で変わります。まず /status でバージョンを確認し、古ければ更新してください。/run-skill-generator を使うと、アプリの起動手順をまとめたスキルを .claude/skills/run-<name>/ に作れます。

まとめ

• .claude/commands/<name>.md にMarkdownを1枚置けば /name として使える。サブフォルダは /frontend:component のように : 区切りになる
• カスタムコマンドは2026年1月のv2.1.3でスキルに統合された。新しく作るなら .claude/skills/<name>/SKILL.md
• フロントマターは description から始め、disable-model-invocation・allowed-tools・paths を必要に応じて足す
• 引数は $ARGUMENTS、$0（1つ目）、名前付きの $name で受け取る
• ! はClaudeが読む前に手元のシェルで実行される。allowed-tools での事前承認が必要で、失敗すると呼び出しが止まる
• 副作用のあるコマンドには disable-model-invocation: true を付ける
• スキルが増えたら /skill-doctor と skillOverrides で整理する
• 他人のスキルは ! の行と allowed-tools を読んでから使う。チームでは .claude/ の変更をレビュー必須にする
• 組み込みコマンドは2026年10月時点で /code-review・/import・/skill-doctor などが加わり、/ultraplan や /vim は無くなった

関連記事

• Claude Codeとは？できること・料金・使い方・他ツール比較
• Claude Code Skills 使い方完全ガイド
• Claude Code Hooks 使い方
• Claude Code料金【日本円換算】
• AIコーディングツール おすすめ比較