スキルで Claude Code を自分好みに拡張しよう

Claude Code を使っていると、「毎回同じ指示を出すのが面倒」「プロジェクト固有のルールを覚えてほしい」と思うことがありませんか？

そんなときに使えるのがスキルです。

スキルとは、SKILL.md というマークダウンファイルに指示を書いておくだけで、Claude の振る舞いを拡張できる仕組みです。たとえば「コードレビューのルール」「リリース手順」「コミットメッセージの書き方」などをスキルとして定義しておけば、Claude が必要なタイミングで自動的に読み込んでくれます。

もちろん /skill-name のようにスラッシュコマンドとして直接呼び出すこともできます。

補足： /help や /compact のような組み込みコマンドについては、公式ドキュメントのインタラクティブモードを参照してください。

以前の .claude/commands/ によるカスタムスラッシュコマンドは、現在もそのまま動作します。スキルはその上位互換で、サポートファイル（テンプレートやスクリプト）を含められたり、Claude の自動呼び出しを制御できたりと、より柔軟な機能が追加されています。

まずはスキルを作ってみよう

ここでは「コードレビューを自動化するスキル」を例に、作成手順を紹介します。

ステップ 1：ディレクトリを作る

プロジェクト直下の .claude/skills/ にディレクトリを作ります。ここに置いたスキルは、そのプロジェクトで作業するメンバー全員が使えます。

mkdir -p .claude/skills/review

Tip： 個人用のスキル（どのプロジェクトでも使いたいもの）は ~/.claude/skills/ に置きましょう。プロジェクト固有のルールは .claude/skills/ がおすすめです。使い分けを最初に決めておくと、あとで散らかりません。

ステップ 2：SKILL.md を書く

スキルの本体は SKILL.md というファイルです。構成は 2 つのパートに分かれています。

• フロントマター（--- で囲まれた YAML 部分）：スキルの名前や説明など、メタ情報を書く
• マークダウン本文：Claude に従ってほしい指示を書く

.claude/skills/review/SKILL.md を以下の内容で作成しましょう。

---
name: review
description: >
  コードレビューを実施する。変更されたファイルを読み、
  バグ・パフォーマンス・可読性の観点でフィードバックする。
---
以下の観点でコードレビューしてください。

## チェック観点
1. **バグの可能性** — null チェック漏れ、境界値、競合状態
2. **パフォーマンス** — 不要な再レンダリング、N+1 クエリ、メモリリーク
3. **可読性** — 命名、関数の長さ、ネストの深さ
4. **セキュリティ** — XSS、SQL インジェクション、認証漏れ

## 出力フォーマット
- ファイルパスと行番号を必ず示す
- 重要度を「Critical / Warning / Suggestion」で分類する
- 修正案のコードも提示する

フロントマターの name がそのままスラッシュコマンド名（/review）になります。description は Claude が「このスキルを今使うべきかどうか」を判断する材料です。

Tip： description は日本語で書いて OK です。普段 Claude に日本語で話しかけるなら、日本語のほうが自動呼び出しのマッチ精度が上がります。

ステップ 3：動作確認

作ったスキルは 2 通りの方法で使えます。

方法 A：自然に頼んで Claude に判断させる

この PR の変更をレビューして

description の内容に合致すれば、Claude が自動的にスキルを読み込みます。

方法 B：スラッシュコマンドで直接呼び出す

/review src/lib/auth.ts

どちらでも、チェック観点に沿った構造化されたレビューが返ってくるはずです。

スキルの保存場所と優先順位

スキルをどこに置くかで、使える範囲が変わります。

同じ名前のスキルが複数の場所にある場合は、Enterprise > Personal > Project の優先順位で適用されます。Plugin スキルは plugin-name:skill-name という名前空間を使うので、他と衝突しません。

CLAUDE.md との使い分け： 「常にすべての作業で守ってほしいルール」は CLAUDE.md に、「特定のタスクのときだけ使いたいルール」はスキルに書くのがおすすめです。たとえば「TypeScript を使え」は CLAUDE.md、「レビューの手順」はスキル、という具合です。

monorepo での自動検出

monorepo のようにサブディレクトリごとに .claude/skills/ を持つ構成もサポートされています。packages/frontend/ 内のファイルを編集していれば、packages/frontend/.claude/skills/ のスキルも自動で検出されます。

スキルディレクトリの構成

スキルは 1 つのディレクトリとして管理します。SKILL.md だけが必須で、その他はオプションです。

review/
├── SKILL.md           # メインの指示（必須）
├── checklist.md       # 詳細なチェックリスト
├── examples/
│   └── good-review.md # レビューの出力例
└── scripts/
    └── lint-check.sh  # Claude が実行できるスクリプト

SKILL.md からこれらのファイルを参照しておけば、Claude は必要に応じて読み込んでくれます。

--add-dir で追加したディレクトリ

claude --add-dir ../shared-config のように追加したディレクトリ内の .claude/skills/ も自動で認識されます。しかもライブ検出されるので、セッション中にスキルを編集しても再起動は不要です。

補足： --add-dir で追加したディレクトリの CLAUDE.md はデフォルトでは読み込まれません。読み込みたい場合は環境変数 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 を設定してください。

スキルの設定を深掘りする

2 種類のスキルコンテンツ

スキルの中身は大きく 2 タイプに分かれます。

リファレンス型：知識を与える

Claude が作業中に参考にしてほしいルールやパターンを書いておくタイプです。呼び出されると、会話のコンテキストにそのまま追加されます。

---
name: nextjs-rules
description: >
  Next.js App Router プロジェクトのコーディング規約。
  コンポーネントやページを書くときに適用する。
---
このプロジェクトの Next.js ルール：
- Server Component をデフォルトにし、"use client" は最小限にする
- データ取得はサーバーサイドで行い、クライアントに props で渡す
- ルートセグメントごとに loading.tsx と error.tsx を用意する
- 画像は next/image、リンクは next/link を必ず使う

タスク型：手順を指示する

リリースやデプロイなど、決まった手順を実行させたいときのタイプです。Claude に勝手に実行させたくない場合は disable-model-invocation: true をつけておきましょう。

---
name: release
description: リリースの準備と実行手順
disable-model-invocation: true
---
以下の手順でリリースしてください。
1. `npm test` で全テストが通ることを確認する
2. `npm run build` でビルドが通ることを確認する
3. package.json のバージョンを $ARGUMENTS に更新する
4. CHANGELOG.md に変更内容を追記する
5. コミットして git tag を打つ

Tip： タスク型のスキルには disable-model-invocation: true をつけるクセをつけておくと安全です。リリースやデプロイを Claude が「親切心」で勝手に始めるのを防げます。

フロントマターの全オプション

SKILL.md の冒頭で設定できるフィールドの一覧です。すべてオプションですが、description だけは書いておくことをおすすめします。

---
name: my-skill
description: このスキルの説明
disable-model-invocation: true
allowed-tools: Read, Grep
---
ここにスキルの指示を書く...

引数を使う

スキルには引数を渡せます。$ARGUMENTS というプレースホルダーが、実行時に実際の値に置き換わります。

---
name: scaffold
description: 新しいコンポーネントの雛形を生成する
disable-model-invocation: true
argument-hint: [ComponentName]
---
以下の仕様で React コンポーネントを作成してください。

コンポーネント名: $ARGUMENTS

1. `src/components/$ARGUMENTS.tsx` に本体を作成
2. props の型定義を含める
3. 基本的なスタイリングを Tailwind CSS で書く
4. `src/components/$ARGUMENTS.test.tsx` にテストも作成

/scaffold UserProfile と実行すれば、$ARGUMENTS が UserProfile に置き換わります。

スキルに $ARGUMENTS を書いていない場合でも、渡された引数は末尾に ARGUMENTS: <値> として自動追加されるので安心です。

個別の引数にアクセスしたい場合は、$ARGUMENTS[0]、$ARGUMENTS[1]... またはその省略形 $0、$1... が使えます。

---
name: rename
description: コンポーネントをリネームする
disable-model-invocation: true
argument-hint: [OldName] [NewName]
---
$0 を $1 にリネームしてください。

1. ファイル名を変更する
2. コンポーネント名・型名をすべて置換する
3. import しているファイルもすべて更新する
4. テストファイルも同様にリネームする

/rename UserCard ProfileCard と実行すると、$0 = UserCard、$1 = ProfileCard に置き換わります。

その他の変数

サポートファイルを活用する

SKILL.md が長くなりすぎたら、参考資料を別ファイルに切り出しましょう。

review/
├── SKILL.md          # 概要とナビゲーション
├── checklist.md      # 観点別の詳細チェックリスト
├── examples.md       # 良いレビュー / 悪いレビューの例
└── scripts/
    └── lint-check.sh # pre-review で走らせるスクリプト

SKILL.md から以下のようにリンクしておけば、Claude は必要に応じて読み込みます。

## 参考資料
- 詳細なチェックリスト → [checklist.md](checklist.md)
- レビューの出力例 → [examples.md](examples.md)

Tip： SKILL.md は 500 行以内に収めるのがおすすめです。長くなるほどコンテキストを食うので、詳細は別ファイルに分けて Claude に必要時だけ読ませましょう。

呼び出しの制御

誰がスキルを使えるか

デフォルトでは、ユーザーも Claude もスキルを呼び出せます。これを制限するための設定が 2 つあります。

disable-model-invocation: true — ユーザーだけが呼び出せるようにする

/release や /send-notification のように、「Claude が勝手に実行したら困る」タスク向けです。コードが完成したように見えても、Claude が勝手にリリースを始めることはありません。

user-invocable: false — Claude だけが使えるようにする

ユーザーが直接呼び出す意味がないバックグラウンド知識向けです。たとえば「この API は v1 と v2 で認証方式が違う」のような内部事情のスキルは、Claude が必要なときに自動で参照すれば十分です。

まとめると以下のようになります。

ツールを制限する

allowed-tools を使えば、スキル実行中に Claude が使えるツールを限定できます。

---
name: audit
description: コードベースの監査。読み取りのみで変更しない
allowed-tools: Read, Grep, Glob, Bash(wc *)
---

この例では、ファイルの閲覧と wc コマンドだけ許可しています。Bash(パターン) のように書けば、特定のコマンドだけを許可することもできるので、「テストの実行だけ許可」のような使い方も可能です。

高度なパターン

動的コンテキストの注入

!`コマンド` という構文を使うと、スキルが Claude に渡される前にシェルコマンドを実行し、その結果をスキルの中に埋め込めます。

たとえば、直近の変更から CHANGELOG のドラフトを自動生成するスキルを考えてみましょう。

---
name: changelog
description: 直近のリリースからの変更をまとめる
context: fork
agent: Explore
disable-model-invocation: true
---

## 変更情報
- 前回タグからのコミット一覧：!`git log $(git describe --tags --abbrev=0)..HEAD --oneline`
- 変更されたファイル：!`git diff --name-only $(git describe --tags --abbrev=0)..HEAD`

## やること
上記の変更情報を元に、CHANGELOG のドラフトを作成してください。
- カテゴリ別に分類する（機能追加 / バグ修正 / 改善 / 破壊的変更）
- 各項目は 1 行で簡潔にまとめる

実行の流れはこうなります。

1. !`git log ...` などのコマンドがまず実行される
2. その出力でプレースホルダーが置き換わる
3. Claude は実際の git データが入った完成形のプロンプトを受け取る

つまり、これは「前処理」です。Claude がコマンドを実行しているわけではなく、スキルの読み込み時に自動で埋め込まれます。

Tip： スキル内で拡張思考（Extended Thinking）を有効にしたい場合は、本文のどこかに ultrathink という単語を含めてください。

subagent で隔離して実行する

フロントマターに context: fork を追加すると、スキルはメインの会話とは切り離された別の subagent で実行されます。会話履歴にはアクセスできなくなりますが、重い処理を分離できます。

注意： context: fork は「やるべきタスク」が明記されたスキルにだけ使ってください。「API 規約を守ること」のようなガイドラインだけ書いても、タスクがないため subagent は何もせずに返ってきます。

以下は Explore エージェントを使って未使用コードを洗い出すスキルの例です。

---
name: find-unused
description: 使われていないエクスポートや関数を探す
context: fork
agent: Explore
disable-model-invocation: true
---
以下の手順で未使用コードを探してください。

1. Grep で `export` されている関数・変数・型の一覧を取得する
2. 各エクスポートが他のファイルから import されているか確認する
3. どこからも参照されていないものをリストアップする
4. ファイルパスと行番号つきで報告する

対象ディレクトリ: $ARGUMENTS

実行の流れ：

1. 新しい隔離コンテキストが作られる
2. subagent がスキルの内容をプロンプトとして受け取る
3. agent フィールドで指定したエージェント（ここでは Explore）が処理を実行
4. 結果がまとめられ、メインの会話に返される

agent には組み込みエージェント（Explore、Plan、general-purpose）や、.claude/agents/ に定義したカスタム subagent を指定できます。省略すると general-purpose が使われます。

Tip： context: fork を使うと、調査結果だけがメインの会話に返ってくるので、途中経過でコンテキストが汚れません。コードの調査・分析系のスキルは fork にしておくと快適です。

スキルのアクセス制御

Claude が使えるスキルを制限する方法は 3 つあります。

1. すべてのスキルを無効にする

/permissions の拒否ルールに Skill を追加します。

Skill

2. 特定のスキルだけ許可 / 拒否する

# 許可
Skill(review)
Skill(scaffold *)

# 拒否
Skill(release *)

Skill(name) で完全一致、Skill(name *) で引数つきのプレフィックス一致です。

3. 個別のスキルを Claude から隠す

フロントマターに disable-model-invocation: true を追加すれば、そのスキルは Claude のコンテキストから完全に除外されます。

補足： user-invocable: false は / メニューの表示を制御するだけで、プログラム的な呼び出しはブロックしません。Claude による自動呼び出しを防ぎたい場合は disable-model-invocation: true を使ってください。

スキルを共有する

スキルの共有方法は、誰に使ってもらいたいかで変わります。

• チーム内で共有 → .claude/skills/ をリポジトリにコミット
• プラグインとして配布 → プラグインの skills/ ディレクトリに配置
• 組織全体に展開 → Enterprise の管理設定を利用

Tip： チームでスキルを共有するとき、fe-review、be-scaffold のようにプレフィックスをつけると、フロントエンド / バックエンドで棲み分けできて管理しやすくなります。

応用：スクリプトをバンドルする

スキルにはスクリプトファイルをバンドルできます。Claude 単体では難しい処理（ファイルシステムの一括スキャン、外部 API の呼び出し、HTML レポートの生成など）を、Python や Bash スクリプトに任せて Claude にオーケストレーションさせる、という使い方です。

たとえば「プロジェクトの依存パッケージの脆弱性をチェックするスキル」なら、こんな構成になります。

security-check/
├── SKILL.md
└── scripts/
    └── check-deps.sh

---
name: security-check
description: 依存パッケージの脆弱性を調査する
disable-model-invocation: true
allowed-tools: Bash(bash *), Read
---

## 依存パッケージの脆弱性チェック

以下のスクリプトを実行して、結果を分析してください。

```bash
bash .claude/skills/security-check/scripts/check-deps.sh
```

スクリプトの出力を読み、以下を報告してください。
- Critical / High の脆弱性があればすぐ対応が必要な旨を伝える
- 各脆弱性の影響範囲と推奨される対応策をまとめる
- 自動で `npm audit fix` で直せるものと手動対応が必要なものを分ける

このパターンは他にも、テストカバレッジレポート、DB マイグレーションの差分チェック、デッドコードの検出など、さまざまな用途に応用できます。

うまくいかないときは

スキルが呼び出されない

1. description に、ユーザーが自然に使いそうなキーワードを含めているか確認する
2. 「どのスキルが使える？」と Claude に聞いて、一覧に表示されるか確認する
3. リクエストの言い回しを description に近づけてみる
4. /skill-name で直接呼び出して、スキル自体が動くか確認する

スキルが意図しないタイミングで呼ばれる

1. description をもっと具体的にして、適用範囲を狭める
2. 手動でしか使わないなら disable-model-invocation: true を追加する

Claude が一部のスキルを認識しない

スキルの説明文はコンテキストに読み込まれますが、スキルが多すぎると文字数の上限（コンテキストウィンドウの 2%、フォールバック 16,000 文字）を超えることがあります。/context を実行すると、除外されたスキルがないか確認できます。

上限を変更したい場合は、環境変数 SLASH_COMMAND_TOOL_CHAR_BUDGET で調整してください。

関連リソース

• Subagent — タスクを専門のエージェントに委任する仕組み
• プラグイン — スキルを含む拡張パッケージの配布方法
• フック — ツール実行前後にシェルコマンドを自動実行する仕組み
• メモリ — CLAUDE.md で永続的なプロジェクト設定を管理する方法
• 権限 — ツールやスキルのアクセス制御