Skills を作る

SKILL.md の段階的開示と索引設計パターン、description の良い例 vs 悪い例、CLAUDE.md との使い分け判断軸。

最終確認 2026年5月5日 所要時間 約18分 v 2.x 対応

「同じ手順を毎回プロンプトに貼り付けている」「CLAUDE.md の一節が手順書になってきている」── このサインが見えたら Skill に切り出す時である。Skill は Claude Code を自分の手順で拡張する最も基本的な仕組みである。

Skill とは何か

Skill は、Claude が呼び出せる特化した指示セットである。SKILL.md というマークダウンファイルとフロントマターで定義し、必要に応じて Claude が自動的に読み込むか、/skill-name で明示的に呼び出す。

CLAUDE.md との違いは読み込みのタイミング:

CLAUDE.md ─ 全セッションの開始時に必ず読まれる
Skill ─ 関連する場面でだけ読み込まれる (description 一覧は常時、本体はオンデマンド)

つまり、**「全会話で必要ではないが、特定の場面で詳細な手順が要る」**ものは Skill にすると、CLAUDE.md を膨らませずに済む。

いつ Skill、いつ CLAUDE.md か

判断の目安は「関係ないタスクの時にも頭に入っているべきか？」を自問することである。

Yes → CLAUDE.md ─ プロジェクトの前提知識、全タスクに適用すべきコーディング規約など
No → Skill ─ デプロイ手順、特定フォーマットのレポート作成、ライブラリ固有の開発作法など

すでに CLAUDE.md に多くの手順を書き込んでいる場合、「この節は特定の作業の時しか参照しない」と感じるものを Skill に切り出すリファクタリングが有効である。CLAUDE.md が軽くなり、無関係なタスクでコンテキストを食いつぶさなくなる。

最小限の Skill

最小構成はこうなる。

.claude/skills/explain-code/
└── SKILL.md

SKILL.md の中身:

---
description: コードを図解と例えで説明する。コードの動きを聞かれた時、コードベースを学んでいる時、「これどう動く?」と聞かれた時に使う。
---

コードを説明する時は必ず:

1. **例えから始める**: 日常生活の何かに例える
2. **図を描く**: ASCII アートでフローや構造を示す
3. **コードを順を追って解説する**: ステップごとに何が起きるか
4. **ハマりどころを挙げる**: 典型的な勘違いや落とし穴を一つ

ディレクトリ名 (explain-code) がスキル名になり、/explain-code で呼び出せる。description を見て Claude が「今のタスクに関連するか」を自動判定し、関連すれば自分で読み込む。

配置場所のスコープ

Skill も CLAUDE.md と同様、複数の場所に置ける。

場所	適用範囲
`~/.claude/skills/<name>/SKILL.md`	全プロジェクト (個人)
`.claude/skills/<name>/SKILL.md`	現プロジェクト (チーム共有)
プラグイン経由	プラグインがインストールされた場所
管理設定	組織全体

優先順は 管理 > 個人 > プロジェクト > プラグイン。同名スキルがあれば優先度の高い方が勝つ。

フロントマター主要フィールド

フィールド	役割
`description`	Claude が「いつ使うか」を判断する材料。最重要
`disable-model-invocation: true`	自動呼び出しを禁止し、`/name` でしか呼べないようにする
`user-invocable: false`	`/` メニューに出さず、Claude だけが使う背景知識用
`allowed-tools`	スキル中だけ事前承認するツール (`Read Grep` 等)
`model`	このスキル中だけ別モデルに切り替え
`paths`	グロブパターンに一致するファイル作業時のみ有効化

description の書き方

description の質がスキルの自動呼び出し精度を直接決める。コツは**「何をするか」ではなく「いつ使うか」を書く**ことである。読者が自然に発しそうな言葉をいくつか想定して盛り込むと、Claude の判定精度が上がる。

悪い例と良い例を対比する:

❌ 曖昧	✅ 発動条件が明示されている
`コードを説明する`	`コードを図解と例えで説明する。コードの動きを聞かれた時、コードベースを学んでいる時、「これどう動く?」と聞かれた時に使う`
`テストを書く`	`ユニットテストとインテグレーションテストを作成する。テスト追加・修正を頼まれた時、バグ修正の後、PR レビュー前のテスト補完に使う`
`デプロイする`	`本番環境へのデプロイを実行する。リリース準備、デプロイリクエスト、本番反映の依頼があった時に使う`
`コードをレビューする`	`PR のコードレビューを行う。PR のリンクや差分を渡された時、「レビューして」と頼まれた時に使う`
`ドキュメントを書く`	`API ドキュメントと README を作成・更新する。ドキュメント追加の依頼、公開前の仕上げ、未文書化のコードを説明する時に使う`

副作用のあるワークフロー(デプロイ、コミット等)は disable-model-invocation: true を組み合わせ、Claude が勝手にトリガーしないようにするのが安全である:

description: >
  デプロイ手順を実行する。本番デプロイのリクエスト、リリースの準備、
  デプロイ前チェックの依頼があった時に使う。
disable-model-invocation: true

`$ARGUMENTS` で引数を受け取る

スキルは引数を受け取れる。$ARGUMENTS プレースホルダーが、呼び出し時の引数で置換される。

---
name: fix-issue
description: GitHub の issue を修正する
disable-model-invocation: true
---

GitHub issue $ARGUMENTS をコーディング標準に従って修正する:

1. `gh issue view` で issue の詳細を取得
2. 問題を理解
3. 関連ファイルを検索
4. 修正を実装
5. テストを書いて検証
6. 説明的なメッセージでコミット
7. PR を作成

/fix-issue 1234 で呼ぶと、Claude は「GitHub issue 1234 をコーディング標準に従って修正する…」を受け取る。

位置引数 $0 $1 $2 (もしくは $ARGUMENTS[0] $ARGUMENTS[1]) で個別アクセスもできる。

自動呼び出しか、明示呼び出しか

disable-model-invocation フィールドが、両者の使い分けを制御する。

設定	誰が呼べるか	description のコンテキスト読み込み
(デフォルト)	自分 + Claude	常時
`disable-model-invocation: true`	自分のみ	呼び出し時のみ
`user-invocable: false`	Claude のみ	常時

判断の目安:

副作用のあるワークフロー (deploy、commit 等) は disable-model-invocation: true にして、Claude が勝手にトリガーしないようにする
背景知識として使ってほしい ものは user-invocable: false にして、/ メニューを汚さない
一般的な知識 (コーディング規約等) はデフォルトのままで、Claude に判断させる

補助ファイルを束ねる

複雑なスキルは、SKILL.md だけでなく補助ファイルも持てる。

my-skill/
├── SKILL.md           ← 必須、エントリポイント
├── reference.md       ← 詳細な API ドキュメント (必要時に読む)
├── examples.md        ← 使用例
└── scripts/
    └── helper.py      ← 実行用スクリプト

SKILL.md から「詳細は reference.md を参照」のように指示しておくと、Claude が必要時にだけ補助ファイルを読み込む。

段階的開示の仕組み

Skills のロードには 3 段階ある:

description のみ ─ 常時コンテキストに乗る(短い一文)
SKILL.md 本体 ─ description が今のタスクに合致すると Claude が判断した時だけ展開される
補助ファイル ─ SKILL.md 内で参照されており、Claude が必要と判断した時だけ読まれる

この仕組みのおかげで、大きなドメイン知識をまるごと Skills に入れていても、無関係なタスクでコンテキストを圧迫しない。SKILL.md を「索引」として書き、本体を補助ファイルに外出しすることに価値があるのは、この 3 段階構造があるからである。

SKILL.md を索引として書く

ドメイン知識が大きい場合、SKILL.md に全部詰め込むのではなく、「全体観 + 補助ファイルの目次」だけを書く設計が有効である。

例として Django プロジェクト用のスキルを見てみよう:

~/.claude/skills/django-project/
├── SKILL.md            ← 入口(全体観と索引)
├── models.md           ← モデル設計の規約
├── views.md            ← ビュー層の書き方
├── testing.md          ← テスト方針
└── deployment.md       ← デプロイ手順

SKILL.md の中身は「全体観 + どの補助ファイルをいつ読むかの索引」だけにする:

---
description: Django プロジェクトを開発する。モデル設計、ビュー実装、テスト、デプロイに関する作業の時に使う。
---

このスキルは Django 4.2 / PostgreSQL 構成の開発規約を管理する。

## 補助ファイルの構成

作業内容に応じて必要なファイルを参照すること:

- モデル設計・マイグレーション → `models.md` を読む
- ビュー・URL・テンプレート → `views.md` を読む
- テスト戦略と実行方法 → `testing.md` を読む
- ステージング/本番デプロイ → `deployment.md` を読む

## 全体共通ルール

- 変数名はスネークケース
- コメントは英語
- PR ごとに対応するテストを必ず追加する

Claude はモデル設計について聞かれた時に models.md を、デプロイについて聞かれた時に deployment.md を読みに行く。デプロイ作業中にモデル設計の詳細がコンテキストを占有することはない。SKILL.md は 500 行以下に保つのが推奨パターンである。

補助ファイル分割 vs Skill 自体の分割

ドメインが大きい時、「補助ファイルで賄う」か「別の Skill に分ける」かの判断軸を示す:

状況	推奨
同じ作業文脈内でサブトピックを整理したい	補助ファイルで分割
`paths` でファイル種別ごとに発動条件を変えたい	Skill 自体を分割
description を分けて自動呼び出しの精度を上げたい	Skill 自体を分割
別チームに独立した単位で配布したい	Skill 自体を分割

バンドルスキル

Claude Code には /simplify /debug /loop /claude-api などのバンドルスキルが最初から入っている。これらは全 Claude Code セッションで使えるスキルで、自分で書くスキルと同じ仕組み (プロンプト駆動) で動いている。

バンドルスキルを /help で見ると、自分のスキルと並んで表示される。それぞれが何をするかの description があるので、参考になる。

どこから始めるか

まず ~/.claude/skills/ に個人用の小さなスキルを一つ作るのがおすすめ。「いつも書いている説明テンプレート」「自分独自のレビュー観点」など、頻繁に使うけど CLAUDE.md に入れるほどではないものから始めると、感覚がつかみやすい。

慣れたらプロジェクト固有の .claude/skills/ に共有スキルを作り、最終的にはチーム全体に配布する Plugin へ ─ という順で広げていける。

次章は、Skill の隣にあるもう一つの拡張機構 ── Subagent を自分で定義する話に入る。

参考情報

Skills (公式) — SKILL.md のフルリファレンス
Agent Skills 標準 — オープン標準としての仕様