AI Tools 2026年4月15日

Claude Code Skills完全ガイド：カスタムスラッシュコマンドの作り方と活用パターン

Claude Code の Skills 機能を徹底解説。SKILL.md の書き方、allowed-tools・context:fork・disable-model-invocation などのフロントマター、引数展開、チーム共有の方法まで2026年4月の最新仕様でまとめました。

#Claude Code #Skills #スラッシュコマンド #SKILL.md #自動化 #カスタムコマンド

TL;DR

Claude Code の Skills は、Markdown ファイル 1 枚でカスタムスラッシュコマンドを定義できる拡張機能です。/commit・/review・/deploy のようなよく使うワークフローをチーム全員で共有できます。

Skills でできること：

/skill-name で即呼び出せるカスタムコマンドを定義
使用するツール、実行モデルをスキル単位で制限
引数（$ARGUMENTS）を受け取る動的なコマンド
サブエージェントとして独立したコンテキストで実行（context: fork）
Claude が自動判断で呼び出す「バックグラウンド知識」として機能させる

Skills の保存場所

Skills ファイルはスコープに応じて 4 か所に置けます。優先度は下ほど高くなります（プロジェクトスコープがグローバルを上書き）。

スコープ	パス	用途
個人（全プロジェクト共通）	`~/.claude/skills/<name>/SKILL.md`	自分だけが使う汎用コマンド
プロジェクト	`.claude/skills/<name>/SKILL.md`	チーム共有のワークフロー
プロジェクト（旧形式）	`.claude/commands/<name>.md`	後方互換で引き続き動作
エンタープライズ	Managed Settings 経由	組織全体へのポリシー配布

Tips: プロジェクトの .claude/skills/ に置いて Git 管理すると、チームメンバー全員が同じスラッシュコマンドを使えるようになります。

Skills のディレクトリ構造

Skill は SKILL.md 単体でも動きますが、本格的に育てる場合はディレクトリにして補助ファイルを並べる構成が定番です。

.claude/skills/<skill-name>/
├── SKILL.md          # エントリーポイント（必須）
├── references/       # 仕様書・サンプルコード・テンプレ等の参照素材
│   ├── api-spec.md
│   └── style-examples.md
└── scripts/          # 補助スクリプト（任意）
    └── lint.sh

references/ 配下のファイルは SKILL.md から @references/api-spec.md の形で取り込めます。SKILL.md 本体に長い仕様や設定値を書き込むとトークンを毎回消費するので、「初動で読み込む指示」だけ SKILL.md に残し、参照される素材は references/ に分離するのが定石です。

scripts/ は Skill 内から実行する補助コマンド置き場です。allowed-tools: Bash(./scripts/*) のようにスクリプト経由に絞ると、許可ツールの管理が一気にシンプルになります。

SKILL.md の基本構造

---
name: fix-github-issue
description: GitHub Issue を番号で指定して修正する。TDD で実装し PR を作成する。
---

GitHub Issue #$ARGUMENTS を修正してください。

手順：
1. `gh issue view $ARGUMENTS` でイシューの内容を確認する
2. 関連するコードを読み、原因を特定する
3. テストを先に書く
4. 実装を行う
5. `npm test` を実行してすべてのテストが通ることを確認する
6. PR を作成する（タイトルに Issue 番号を含める）

呼び出し方：/fix-github-issue 123

フロントマター一覧

フィールド	デフォルト	説明
`name`	ファイル名	スラッシュコマンド名（`/name` で呼び出す）
`description`	—	Claude がいつ使うかを判断するためのメタ説明
`disable-model-invocation`	`false`	`true` にするとユーザーのみ呼び出し可（副作用があるスキル向け）
`user-invocable`	`true`	`false` にすると Claude のみ自動呼び出し可（ガイドラインとして機能）
`context`	—	`fork` を指定するとサブエージェントとして独立したコンテキストで実行
`allowed-tools`	全ツール	スキル実行中に使用を許可するツールをスペース区切りで指定
`model`	セッションのデフォルト	このスキル用のモデルを上書き指定
`paths`	—	特定のファイルパターンにマッチした時のみ自動ロード

引数の展開

スキル本文中では以下の変数が使えます。

変数	意味
`$ARGUMENTS`	`/skill-name` の後に書いたテキスト全体
`$0`	スキル名
`$1`, `$2`, `$3`…	スペース区切りの引数（`$1` が最初の引数）

---
name: pr-review
description: PR を番号またはURLで指定してコードレビューする
---

PR $1 をレビューしてください。

- セキュリティ上の問題がないか確認する
- パフォーマンスへの影響を評価する
- コーディング規約（CLAUDE.md を参照）への準拠を確認する
- `gh pr view $1 --comments` で既存コメントも確認する

allowed-tools でツールを制限する

スキル実行中に使えるツールを絞り込むと、意図しない操作を防げます。

---
name: read-only-audit
description: コードベースを読み取り専用で監査する（変更は一切行わない）
allowed-tools: Read Glob Grep
---

以下の観点でコードベースを監査してください：
- 認証ロジックの問題点
- 入力バリデーションの漏れ
- ハードコードされた認証情報

変更は一切行わないこと。監査レポートのみ出力する。

ツール名は Read・Bash(git *)（コマンドを絞り込む）・Edit|Write のようにパターン指定も使えます。

context: fork — 独立コンテキストで実行

context: fork を指定すると、スキルがサブエージェントとして実行されます。メインセッションのコンテキストを汚さずに独立したタスクを実行したい場合に使います。

---
name: dependency-check
description: 依存関係の脆弱性チェックを独立して実行する
context: fork
allowed-tools: Bash(npm audit) Bash(yarn audit) Read
---

プロジェクトの依存関係をセキュリティ面で監査してください。

1. `npm audit` または `yarn audit` を実行する
2. CRITICAL・HIGH の脆弱性を一覧化する
3. 修正方法（バージョンアップで解決するもの / 手動対応が必要なもの）を区別する
4. 修正方法を Markdown テーブルで出力する

修正は行わない。レポートのみ作成する。

disable-model-invocation — Claude に勝手に使わせない

デプロイや DB マイグレーションのような副作用が大きいスキルは、disable-model-invocation: true で Claude が自動判断で使えないようにします。

---
name: deploy-production
description: 本番環境にデプロイする（必ずユーザーが明示的に指示すること）
disable-model-invocation: true
allowed-tools: Bash(git *) Bash(npm run deploy)
---

本番環境へのデプロイを実行します。

1. `git log --oneline -5` で最新コミットを確認する
2. `npm run build` でビルドを実行する
3. テストが通っていることを確認する
4. `npm run deploy` を実行する
5. デプロイ後のヘルスチェック URL にアクセスして動作確認する

⚠️ 元に戻せない操作です。実行前に必ずコミット内容を確認してください。

user-invocable: false — Claude 専用の知識として使う

user-invocable: false にすると、スラッシュコマンドとして一覧に表示されなくなり、Claude が文脈に応じて自動的に参照するバックグラウンド知識として機能します。コーディング規約・アーキテクチャ決定記録・よくある失敗パターンなどを Claude に常時読み込ませたい場合に使います。

---
name: error-handling-guidelines
description: このプロジェクトのエラーハンドリング規約。エラー処理を書く際に必ず参照する。
user-invocable: false
---

## エラーハンドリング規約

### 基本方針
- エラーは握りつぶさない。必ず catch して意味のあるメッセージをつけて再スロー
- 外部 API エラーは `ExternalServiceError` でラップする
- バリデーションエラーは `ValidationError` を使う
- DB エラーは直接ユーザーに見せない（内部エラーを隠蔽する）

### 禁止パターン
```typescript
// NG: エラーを握りつぶす
try { ... } catch (e) {}

// NG: any でキャッチする
catch (e: any) { console.error(e) }

推奨パターン

// OK: 意味のあるメッセージをつけて再スロー
catch (error: unknown) {
  throw new DatabaseError('ユーザー取得に失敗しました', { cause: error })
}


---

## シェルコマンドの動的実行（`` !`command` `` 構文）

スキル本文中で `` !`command` `` を使うと、スキルがロードされた時点でコマンドを実行して、その出力を本文に注入できます。

```markdown
---
name: review-pr
description: 現在チェックアウト中のブランチの PR をレビューする
---

現在の PR をレビューしてください。

## 差分
!`git diff main...HEAD`

## 変更ファイル
!`git diff --name-only main...HEAD`

上記の変更について、セキュリティ・パフォーマンス・コーディング規約の観点でレビューしてください。

paths — ファイルパターンに応じた自動ロード

特定のファイルを操作している時だけ自動的に読み込まれるスキルを作れます。

---
name: prisma-best-practices
description: Prisma を使ったDBアクセスの規約。*.prisma や DB 操作ファイルで自動ロード。
user-invocable: false
paths: ["**/*.prisma", "**/repositories/**/*.ts", "**/db/**/*.ts"]
---

## Prisma の使い方規約

- N+1 問題を避けるため、関連エンティティは `include` で一括取得する
- トランザクションは `prisma.$transaction()` を使う
- 生 SQL は原則禁止（パフォーマンス上やむを得ない場合は `$queryRaw` を使い、引数は必ずバインド変数にする）

実践的なスキル集

/commit — 規約に従ったコミットメッセージを生成

---
name: commit
description: ステージングされた変更を Conventional Commits 形式でコミットする
allowed-tools: Bash(git *) Bash(npm test)
---

ステージングされている変更をコミットしてください。

1. `git diff --staged` で変更内容を確認する
2. `npm test` を実行してテストが通ることを確認する（失敗したらコミットしない）
3. Conventional Commits 形式でコミットメッセージを作成する
   - 形式: `type(scope): 件名（日本語）`
   - type: feat / fix / refactor / test / docs / chore
4. `git commit -m "..."` を実行する

/generate-tests — テスト自動生成

---
name: generate-tests
description: 指定ファイルのユニットテストを生成する
---

`$ARGUMENTS` のユニットテストを書いてください。

- テストフレームワークはプロジェクトの設定（package.json を確認）に従う
- 正常系・異常系・境界値をカバーする
- テストファイルは `$ARGUMENTS` と同じディレクトリに `*.test.ts` として作成する
- モックは最小限にする（統合テストを優先する）

/explain — コードの解説

---
name: explain
description: コードやアーキテクチャを日本語で解説する
allowed-tools: Read Glob Grep
context: fork
---

`$ARGUMENTS` について日本語で解説してください。

- 引数が空の場合は現在の会話で話題になっているコードを解説する
- 「なぜそう実装されているか」の背景まで含める
- ジュニア開発者にも分かりやすい言葉を使う

Skills とサブエージェントの使い分け

「結局 Skills とサブエージェントはどう使い分けるのか」は最も混乱しやすいポイントです。役割が異なるので、判断軸を明確にしておきます。

観点	Skills	サブエージェント
主目的	知識・手順の提供（Claude に「どう動くか」を教える）	タスクの委譲（独立コンテキストで実行させる）
コンテキスト	メインと共有	独立（メインを汚さない）
モデル	セッションのデフォルト or `model` 指定	サブごとに自由（Haiku で節約も可）
並列性	直列（メインの中で展開）	並列実行可能
典型用途	コミット規約、デプロイ手順、コーディング規約	コードベース調査、レビュー、テスト生成

判断のコツは「渡したいのは知識か、それとも仕事そのものか」です。コミットメッセージの書き方を統一したい → Skills、認証周りの実装を独立コンテキストで一式調査させたい → サブエージェント、という切り分けになります。

サブエージェントの skills フィールドで Skill を持たせる

サブエージェントの定義から特定の Skill だけを使わせることもできます。サブの責務を絞りつつ、共通ノウハウは Skill 側に集約できる組み合わせ方です。

---
name: pr-reviewer
description: |
  Use PROACTIVELY when reviewing pull requests.
  PR の差分を読み、コーディング規約とセキュリティ観点でレビューする。
tools: Read Glob Grep Bash(gh *)
skills: coding-standards, security-checklist
model: claude-sonnet-4-6
---

サブエージェントごとに「使う Skill だけ」をホワイトリスト化できるので、関係ない Skill が誤発火することがなくなります。チームで Skill を増やしていくときの衛生面でも有効です。

自動呼び出しされない時の切り分け

Skill を作ったのに Claude が呼んでくれない、というのは初期によくある詰まりどころです。確認順序をテンプレ化しておきます。

/ で一覧に出ているか … 出ていなければ配置パス（.claude/skills/<name>/SKILL.md）か name フィールドを再確認
description に具体的な発動条件が書かれているか … 「コードをレビューする」のような汎用すぎる説明だと自動選択されにくい。「PR レビュー時に使用」「Conventional Commits でコミットを作る時」のように when を書く
PROACTIVELY / MUST BE USED キーワード … 似た用途の Skill が複数ある場合は優先度を引き上げる
paths 制約と作業ファイルが整合しているか … paths: ["**/*.prisma"] を指定したのに対象外ファイルで使おうとしていないか
明示呼び出しで動くか … /skill-name で手動実行して機能自体は動くか確認。動けば「自動選択精度」の問題、動かなければ Skill の中身の問題

「自動で呼ばれない」と「手動でも動かない」は原因が全く違うので、最初に手動呼び出しで切り分けると最短で原因に辿り着けます。

ハマりポイント・注意事項

SKILL.md のファイル名がそのままコマンド名になる ~/.claude/skills/fix-issue/SKILL.md なら /fix-issue で呼び出せます。ハイフン区切りのケバブケースが推奨です。

allowed-tools の省略はリスクになりうる 指定しないと Claude Code が使えるすべてのツールを使います。副作用のあるスキルには必ず allowed-tools を設定してください。

disable-model-invocation と user-invocable: false は別物 前者は「ユーザーだけが使える（Claude は使えない）」、後者は「Claude だけが使える（ユーザーは使えない）」です。両方指定すると誰も呼び出せないので注意。

プロジェクトスキルはグローバルスキルを上書きしない（マージされる） 同名のスキルがある場合はプロジェクト側が優先されます。意図的に無効化したい場合は disable-model-invocation: true を使うか、同名でファイルを上書きしてください。

/ コマンドで一覧確認 利用可能な全スキルは / を入力すると一覧表示されます。設定が反映されているか確認するのに使えます。