Claude Code Skills：モデルが実際に呼び出すSKILL.mdファイルの仕組みを解説

更新日: June 28, 2026

Claude Code Skillとは、エージェントがタスクに一致した場合のみコンテキストに取り込むSKILL.mdファイルを持つフォルダです。私は最初にこのスキルを作成し、同じ200語のデータベース移行チェックリストをセッションごとに貼り付ける手間を省きました。その単一のファイルのおかげで、週に約1時間節約できています。

ここでは概要を先に述べ、次に実用的な構造（スキルとは何か、SKILL.mdのフロントマターと本文の書き方、モデルがどのようにスキルを呼び出すかを判断するか、そして単純なプロンプトと比較してスキルが過剰かどうか）について解説します。すでにClaude Codeを使用している場合、5分以内に最初のスキルを実装できます。

クイックアンサー：Claude Code Skillとは？

スキルとは、SKILL.mdとして保存され（オプションでサポートスクリプトを含む）、モデルによって呼び出される再利用可能な機能です。常にロードされるシステムプロンプトとは異なり、スキルはモデルがあなたの要求に関連していると判断したときにオンデマンドでロードされます。あなたは名前、いつ使用するかという説明、そして本文の指示を記述します。この「説明」が最も重要なフィールドであり、なぜならモデルはこの説明を読み取り、スキルを起動するかどうかを決定するからです。スキルはローカルの.claude/skills/に存在するか、レジストリから提供されるため、チームは移行、コードレビュー、またはリリースといった作業のための標準的な方法を共有できます。

CLI自体に関するより広範なコンテキストについては、Claude Code ultimate guide for 2026を参照してください。スキルが常時稼働のサブエージェントとどのように異なるかについては、how I automated my workflow with Claude Code sub-agentsをお読みください。

スキルとは実際何で、何で構成されているのか？

スキルはディレクトリです。最低限必要なのはSKILL.mdファイルのみです。オプションとして、スキルと一緒に渡されるスクリプト、テンプレート、または参照ドキュメントをバンドルすることができます。Anthropicのagent-skillsドキュメントでは、スキルをモデルが関連性があるときにロードできるパッケージ化された一連の指示とリソースとして説明しています (docs.anthropic.com/en/docs/agents-and-tools/agent-skills)。

私はスキルを、モデルのための名前付きでバージョン管理されたサブルーチンだと考えています。これを長いプロンプトと区別する3つの点があります。

1. オプトインである：タスクが説明に一致するように見える場合にのみ、モデルがロードします。
2. スコープが限定されている：その機能にとって意味のあるファイルやスクリプトを添付できます。
3. 共有可能である：フォルダはプロジェクトやチームメンバー間でポータブルです。

CLI自体はオープンソースであり、スキルの規約はGitHub (github.com/anthropics/claude-code)で文書化されており、動作がリリース間で変更されるかどうかを確認する場所でもあります。

SKILL.mdファイルはどのように構造化するか？

このファイルには2つの部分があります：YAMLフロントマターとMarkdown本文です。フロントマターはモデルにいつ実行するかを伝え、本文は何を行うかを伝えます。私が使用する構造は以下の通りです。

---
name: safe-migration
description: Use when the user asks to create, modify, or roll back a database migration. Covers schema changes, down migrations, and verifying against the staging dump.
---

本文はプレーンなMarkdownです。私は3つのセクションを維持しています：一行の目標、番号付きの手順、そして明示的な「停止して確認」ゲート。nameはフォルダ名と一致する必要があります。descriptionは人間向けではなくモデル向けに書かれるべきであり、トリガー条件のように読ませる必要があります。

これは実際に試してみました。「データベースに関するものに役立つ」といった曖昧な説明の場合、スキルが関連性のないSQLの質問でも発動してしまいました。これを「Use when the user asks to create, modify, or roll back a database migration」（ユーザーがデータベース移行の作成、変更、またはロールバックを要求する場合に使用する）に書き直した後、呼び出し精度は概ね60パーセントから信頼できるレベルに向上しました。説明文がルーティングを行っているので、編集時間をそこに費やしてください。

何をスキルにするべきか？

これが最もよく聞かれる質問です。私のルールはこうです：もし過去2週間で同じ指示ブロックを3回貼り付けたことがあり、それが段落以上長い場合、それはスキルになります。以下に私が実際に使用する意思決定マトリックスを示します。

もう一つの軸はコストです。ロードされたスキルはすべてコンテキストにトークンを追加するため、大きく常に関連性の高い指示ブロックは、スキルとしてよりもプロジェクトレベルのメモリやカスタムコマンドの方が適しています。スキルは条件的に関連する専門知識において輝きます。

私がスキルを記述した具体的なケース：私たちのリリースプロセスでは、変更履歴の更新、3つのバージョンファイルのインクリメント、タグ付け、そしてSlackへのサマリー投稿が必要です。私はこれを一度スキルとして書き、今では「cut a release」と言うだけで、モデルがチェックリスト全体を順序通りに実行します。私がそうしなかった具体的なケース：設定ファイルの一回限りのリファクタリング。これはプロンプトのまま残しました。

モデル呼び出しスキルのパターンはどのように機能するのか？

スキルを魔法のように感じさせるパターンとは、あなたがそれらを呼び出さないということです。あなたは仕事の内容を説明し、モデルが利用可能なスキルの説明を読み取り、一致するものを取り込みます。これは公式のClaude Codeドキュメント (docs.anthropic.com/en/docs/claude-code)に文書化されています。

フローは以下のようになります：

1. あなたが自然言語でリクエストを入力します。
2. モデルは、インストールされている各スキルのnameとdescriptionを確認します。
3. リクエストに対して関連性をスコアリングします。
4. 最も適したスキルの本文（およびバンドルされたファイル）がコンテキストに入ります。
5. モデルが指示を実行します。

実用的な結果として、あなたはdescriptionをモデル向けの検索エンジンエントリーを書くかのように書かなければなりません。動詞とトリガーのスコープから始めるようにしてください。これら2つの説明を比較してください：

• 弱い：「git関連の処理のためのスキル。」
• 強い：「Use when the user asks to squash, rebase, or split commits on the current branch. Produces an interactive plan before running any rewrite.」（ユーザーが現在のブランチでコミットをsquash、rebase、または分割するように要求する場合に使用する。書き直しを実行する前にインタラクティブな計画を出力する。）

後者はトリガーとなる動詞とガードレールを指定しています。これが呼び出しを信頼できるものにしているのです。もしツールを使ってスキル同士を配線している場合、Claude Code MCP integration guideは、外部のツールサーバーがスキルのバンドルとどのように共存するかをカバーしています。それらを接続する基盤となるプロトコルについては、MCP and the model contextを参照してください。

スキルをトリガーし、デバッグする方法は？

トリガー自体はほとんど自動的ですが、制御とデバッグのために3つの意図的なテクニックを持っています。

• 明示的にする。「use the safe-migration skill」と言うことで強制できます。説明が曖昧な場合に特に有用です。
• インストール済みスキルをリストアップする：モデルに利用可能なスキルとその説明のリストを要求します。これにより、新しいスキルが登録されたことを確認できます。
• トレースを検査する：スキルが誤って発動した場合、どの説明が一致したかを確認し、トリガーの文言を厳密にします。

スキルが発動しない場合、原因はほぼ常に説明文にあり、ファイルの位置ではありません。最初の文章を「Use when...」で始めるように書き直し、具体的な動詞を追加します。これで10回中9回は直ります。

以下が私が順に実行するデバッグチェックリストです：

スキル vs サブエージェント vs スラッシュコマンド

これら3つは重なり合っており、人々は常に混同しています。私は単純な分類で区別しています。

• スキル: モデル呼び出しの指示とオプションのファイル。条件付きの専門知識に最適です。
• サブエージェント: 孤立した作業を行う別のClaude Codeインスタンス。並行して実行される長時間タスクに最適です。私のsub-agent automation write-upでは深く掘り下げています。
• スラッシュコマンド: 意図的に入力するショートカット。常にオンデマンドで使いたいものに最適です。

スキルは、モデルがあなたのために選択してくれる唯一のものです。それが彼らの超能力であり、同時にリスクでもあります。誤って説明されたスキルは、コンテキストを静かに浪費してしまうからです。

スキルの共有とレジストリの使用方法

スキルは単なるフォルダなので、原理的には共有は簡単です。そのフォルダをリポジトリの.claude/skills/に配置し、コミットします。チームメンバーはクローン時に取得できます。チームを越えた共有の場合、コミュニティがレジストリを維持し、公式ツールが共通の場所を指します。

私の実用的なセットアップ：

1. プロジェクト固有のスキルは、バージョン管理された状態でリポジトリに保持する。
2. 個人的なスキルは、dotfiles repoに保存し、.claude/skills/にシンボリックリンクさせる。
3. 説明文の変更が動作を静かに変更する可能性があるため、外部で共有する際はスキルのバージョンを固定する（ピン留め）のが賢明です。

共有に関する正直な注意点：スキルはあなたのスタックに関する仮定をエンコードします。Drizzle向けに書かれた移行スキルは、説明文がスコープをガードしない場合、Prismaプロジェクトでは自信を持って間違った出力を生成します。常にフレームワークとガードレールを説明文に明記し、破壊的なアクションの前には「停止して確認」ステップを追加してください。共有されたスキルが誤ったブランチで破壊的な書き直しを実行したとき、私はこの教訓を痛い目に遭って学びました。したがって、すべての共有スキルは、その説明文が別であることを証明するまで信頼できないものとして扱ってください。

画像クレジット

• 開発者ワークステーション上のコードテキストオーバーレイの黒い画面 — Pixabayによる写真、Pexelsより
• 開発中のモニター上のプログラミングコードのクローズアップ — Christina Morilloによる写真、Pexelsより
• ソフトウェア開発中のコードエディタを示すラップトップ — luis gomesによる写真、Pexelsより