この記事の目次
Claude Codeの「スキル」の正体 ― 名前だけでは分かりにくい機能の仕組み
Claude Codeの「スキル」とは、特定の作業手順や知識をSKILL.mdという1つのMarkdownファイルにまとめておき、Claudeが必要な場面でそれを自律的に読み込んで使う仕組みです。
「スキル」という言葉から、プラグインやコマンドのようなものを想像するかもしれませんが、実体は驚くほど単純です。1つのフォルダに1つのSKILL.mdを置くだけで成立し、そこにはYAML形式のnameとdescription、そして本文となる手順や知識がMarkdownで書かれています。特別なプログラミング言語もビルド手順も不要で、テキストファイルを書く感覚で作れる点が、他の拡張手段と大きく異なります。
SKILL.mdというファイルの実体（1フォルダ1スキル、name/descriptionを含むという最小構成）
最小構成のスキルは、name（識別名）とdescription（何をする機能で、いつ使うか）を持つfrontmatterと、本文の手順説明だけで成立します。参照用のスクリプトやテンプレートを追加するかどうかは任意で、まずはこの2項目だけで書き始められます。
CLAUDE.md・サブエージェント・MCPとは何が違うのか（役割の要点比較のみ）
スキルと混同されやすい機能として、CLAUDE.md・サブエージェント・MCPの3つがあります。いずれも「Claudeの動きをカスタマイズする」という点は共通していますが、何を定義し、どう呼び出されるかがそれぞれ異なります。
| 機能 | 何を定義するか | 呼び出され方 | 主な用途 |
|---|---|---|---|
| CLAUDE.md | プロジェクトの前提やルール | 会話の開始時に常に読み込まれる | プロジェクト全体の方針共有 |
| サブエージェント | 独立した役割を持つ別人格のClaude | 明示的な指示、または委譲判断で呼び出す | 調査・レビューなど専門作業の切り分け |
| MCP | 外部ツールやデータへの接続方法 | ツールとして必要な時に呼び出す | 外部システムとの連携 |
| スキル | 特定作業の手順や知識 | descriptionとの一致でモデルが自律的に読み込む | 定型作業の手順化 |
それぞれの詳しい書き方や設計の考え方は、CLAUDE.mdの書き方ガイド、サブエージェントの使い方ガイド、MCPの導入ガイドで個別に扱っています。本記事ではスキルに絞って解説を進めます。
スキルはいつ、どうやって呼び出されるのか？ ― 自動起動の仕組み
スキルはコマンドのように明示的に呼び出す機能ではなく、Claudeがタスクの内容とスキルのdescriptionを照らし合わせ、関連性があると判断した時に自律的に読み込む仕組みです。
この起動モデルを理解する上で押さえておきたいのが、2段階の読み込み方式です。まず各スキルのnameとdescriptionは常にClaudeの視界に入っており、これは軽量な情報なので多数のスキルを登録していても負担になりにくい設計になっています。そして実際にタスクとの関連性が高いと判断されたスキルだけ、SKILL.md本文が読み込まれます。この仕組みの詳細は後述しますが、まずは「常に見えているのはdescriptionだけ」という前提を押さえてください。
モデルがdescriptionを読んで判断する仕組み
Claudeは会話中のタスクと各スキルのdescriptionを比較し、一致度が高いと判断したスキルの本文を読み込みます。つまり起動の可否は、コード側の設定ではなくdescriptionという自然文の書き方に依存しています。
個人／プロジェクト／プラグインという置き場所の違いとスコープ
スキルの置き場所には、ホーム配下に置いて全プロジェクトで使う個人用、リポジトリ内の.claude/skillsに置いてチームで共有するプロジェクト用、そしてプラグインに同梱して配布する形の3種類があります。どこに置くかによって、そのスキルが有効になる範囲（スコープ）が変わります。設定ファイルの置き場所を考える上での基本的な発想は、MCPの設定ガイドで扱っている考え方とも近いものがあります。
「思った通りに動かない」理由 ― 誤発火・不発火が起きる構造的原因
スキルの起動判断はdescriptionの記述だけに依存するため、書き方が曖昧だと発火せず、逆に範囲を広く書きすぎると意図しない場面でも発火してしまいます。
これはバグというより、この仕組みが持つ構造的な性質です。原因を理解しておけば、対処の方向性も見えてきます。
descriptionが曖昧・広すぎる／狭すぎる場合に何が起きるか
descriptionが「〇〇を手伝う」のような漠然とした表現になっていると、Claudeはどんなタスクで使うべきか判断しづらく、期待した場面で読み込まれないという事態が起きやすくなります。反対に、対象範囲を広く書きすぎると、本来は不要な場面でも一致度が高いと判断され、意図しないタイミングで発火してしまいます。どちらの場合も、原因は同じで「タスクと使用条件の対応関係が具体的に書かれていないこと」にあります。
起動はしたのに期待通り動かないケースの原因パターン
descriptionによる判定を通過してスキルが起動しても、結果が期待と違うケースがあります。多くの場合、原因は本文の書き方にあります。先ほど触れた2段階読み込みの性質上、本文中で参照している追加ファイルやスクリプトへの案内が明確でないと、必要な情報がその場で読み込まれないまま処理が進んでしまいます。手順の分割方法や参照の書き方については、次の章で具体的に扱います。
最初のスキルはどう書けばいいのか？ ― SKILL.mdの記法とルール
SKILL.mdは、YAML形式のfrontmatter（nameとdescription）と、本文のMarkdownという最小限の構成でできています。まずはこの2項目を過不足なく書くところから始めます。
以下は、PDFの月次レポートを要約するスキルの最小構成の例です。実際に手元で試す際のテンプレートとして参考にしてください。
---
name: pdf-report-summary
description: PDFの月次レポートを要約し、数値と結論を分けて箇条書きにまとめる。「月次レポートを要約して」のような依頼で使う。
---
# PDF月次レポート要約スキル
## 手順
1. 対象PDFのテキストを抽出する
2. 数値と結論を分けて箇条書きにする
3. 出力は日本語、敬体で統一するfrontmatter（name/description）の必須項目と書き方の注意点
nameはスキルを識別するための名前で、descriptionはモデルが起動判断に使う唯一の手がかりです。descriptionには「何をするか」と「どんな依頼の時に使うか」の両方を具体的な言葉で書くことが、前章で触れた誤発火・不発火を避ける第一歩になります。
段階的開示（progressive disclosure）という設計思想
段階的開示（progressive disclosure）とは、前章で見た2段階読み込みの仕組みを支える設計思想の名前です。必要になるまで詳細情報を読み込ませないことで、スキルの数が増えても普段のやり取りで消費する情報量を小さく保てるという考え方を指します。本文をあえて簡潔にし、詳細な手順や大きな参考資料は別ファイルに分けて本文から参照する形にするのは、この思想に沿った書き方です。
サポートファイル・スクリプトを添える場合の構造
スキルのフォルダには、SKILL.mdのほかにスクリプトや参考資料を置くこともできます。その場合は本文中でファイルへの相対パスを明示し、どんな場面でそのファイルを読む・実行するべきかを具体的に書いておくことで、必要な時にだけ追加情報が読み込まれる構造になります。
公式配布スキルの活用法 ― バンドルスキルの位置づけ
Claude Codeにはあらかじめ用意された公式のスキルがあり、自作を始める前にそれらで足りるかどうかを確認しておくと、同じ作業のスキルを重複して作らずに済みます。
最初から使える代表的なスキルの傾向（カテゴリ単位）
公式に配布されているスキルの一例として、Office文書やPDFなど定型フォーマットの文書生成・編集を扱うものがあります。具体的な種類や最新の提供状況は更新される可能性があるため、断定的な一覧を示すのではなく、利用時に公式ドキュメントで最新の内容を確認することをおすすめします。
自作に進む前に確認しておきたいこと
新しくスキルを書き始める前に、同じ目的の公式スキルがすでにないか、あるいは既存スキルのdescriptionを少し調整するだけで対応できないかを確認しておくと、無駄な重複を避けられます。日常的な使い方の全体像についてはClaude Codeの使い方ガイドもあわせて参考にしてください。
作ったスキルが「使えるか」はどう判断するのか？ ― 評価と改善のフロー
作ったスキルは、まず期待通りのタイミングで起動するかを確認し、次に処理結果が意図通りかを検証するという2段階でチェックします。
期待通り起動するかの検証方法
想定している依頼文言だけでなく、似ているが本来は対象外であるはずの依頼文言でも試し、起動する場面としない場面がそれぞれ意図通りかを確認します。Claude Codeはスキルを使用したことを応答の中で示すため、そこで実際に読み込まれたかどうかを目視で確認できます。
改善を回すときの記録・比較の考え方
同じ依頼文言のセットを使い回して、descriptionや本文を修正するたびに結果を比較すると、変更の効果を判断しやすくなります。テストに使った文言と結果を簡単なメモに残しておくだけでも、後から見直す際の手がかりになります。
自分の業務をスキル化する最初の一歩 ― 洗い出しから育て方まで
スキル化に適しているのは、手順として説明できる定型的な業務であり、毎回状況に応じて判断が変わるような業務には向きません。
スキル化に向く業務・向かない業務の見分け方
レポートの要約、コーディング規約への準拠チェック、コミットメッセージの書式統一のように、手順とアウトプットの形が決まっている業務はスキル化しやすい対象です。一方で、その場の状況や最新情報に応じて毎回異なる判断が必要な業務は、手順として固定しにくく、スキル化のメリットが小さくなります。
小さく作って育てる進め方
最初から完璧な手順書を書こうとせず、最小限のdescriptionと本文で作り、実際の依頼で試しながら少しずつ手順を足していく進め方が現実的です。参照ファイルやスクリプトは、本文だけでは対応しきれなくなった時点で追加すれば十分です。
陥りやすい失敗パターン（肥大化してコンテキストを圧迫する、権限を広げすぎる等）
よくある失敗の1つは、本文にあらゆる情報を詰め込みすぎて、段階的開示のメリットを損なってしまうことです。詳細な情報は参照ファイルに分けたほうが見通しがよくなります。もう1つの失敗は、スキルが実行するスクリプトやコマンドの権限範囲を確認しないまま運用してしまうことです。権限設計の考え方は運用ルールの整備ガイドで詳しく扱っています。
導入前後で何を確認しておけば安全に使えるのか？ ― チェックリスト
導入前後で確認しておきたい項目を整理すると、次のようになります。原理面の説明はここまでの章で済ませているため、ここでは確認作業だけをまとめます。
-
descriptionに「何をするか」と「いつ使うか」の両方が具体的に書かれているか - 想定する依頼文言と、似ているが対象外の文言の両方で起動テストをしたか
- 意図しない場面で誤発火しないか、近い言い回しで確認したか
- 本文と参照ファイルに必要な情報が過不足なく含まれているか
- スキルが実行するスクリプトやコマンドの権限範囲を確認したか
- チームで共有する前に内容をレビューしたか
権限設計やセキュリティ面の詳しい考え方は運用ルールの整備ガイド、法人利用時のセキュリティガイドを参照してください。
チームで使う場合に追加で考えるべきこと ― 組織展開時の論点
個人利用と違い、チームや企業でスキルを共有する場合は、内容の正確性を担保するレビュー体制と、実行権限の管理・共有範囲の設計が新たに必要になります。
誰がSKILL.mdを書き、誰がレビューし、どこまでの権限を持つスクリプトを許可するかといった運用ルールを、個人利用の延長で済ませてしまうと、後から見直す手間が大きくなりがちです。ガバナンス設計の考え方はMCPの導入ガイドとも共通する部分が多く、法人での導入プロセス全体は法人導入ガイド、体系的な学習方法は研修の選び方ガイドでそれぞれ詳しく扱っています。
まとめ
Claude Codeのスキルは、SKILL.mdという1つのファイルに手順を書くだけで始められる一方、descriptionの書き方次第で起動の精度が大きく変わる仕組みです。まずは自分の業務の中から手順を説明できるものを1つ選び、最小構成のスキルを書いて試してみることをおすすめします。
チームでの共有や権限管理が必要になってきたら、運用ルールの整備や体系的な学習が選択肢になります。一人で使う範囲でも、スキルの設計をまとめて学びたい場合は、月額1,980円から参加できる学習コミュニティAI駆動ラボに講座があります。