Claude Skillsとは？SKILL.mdの書き方とclaude.ai・Claude Code・APIでの使い方【2026年最新】

Claude Skills（Agent Skills）は、手順書・スクリプト・参照資料をひとつのフォルダにまとめ、Claudeが必要になった瞬間だけ読み込む拡張の仕組みです。中身はSKILL.mdというMarkdownファイル1枚から始められます。ただし、claude.ai（Web版）・Claude Code・Claude APIでは対応するスキルの種類も制限も違い、しかもアップロードしたスキルは3者間で共有されません。ここを取り違えると「作ったのに動かない」で止まります。公式ドキュメントの記述に沿って、仕組み・書き方・3つの環境それぞれの使い方・公式スキルの入手先・MCPとの使い分けを整理します。

まとめ: Claude Skillsの要点

• スキルの実体はSKILL.mdを含むフォルダ。YAMLフロントマターの必須項目はnameとdescriptionの2つだけ。
• 読み込みは3段階（段階的開示）。起動時はname/descriptionのみ（1スキルあたり約100トークン）、該当したときにSKILL.md本体、参照ファイルやスクリプトはさらに必要になったときだけ。
• claude.aiは設定画面からzipでアップロード（Pro・Max・Team・Enterpriseでコード実行が有効な場合）。Claude Codeはファイルシステム上の.claude/skills/。Claude APIは/v1/skillsへアップロードし、コード実行ツールとベータヘッダーが必須。
• カスタムスキルはサーフェス間で同期しない。claude.ai・API・Claude Codeでそれぞれ別管理になる。
• 公式のプリビルドスキルはpptx・xlsx・docx・pdfの4種。オープンソースのスキルはanthropics/skillsリポジトリで公開されている。
• SKILL.mdの形式はAgent Skillsオープン標準（agentskills.io）として公開され、Codex・Cursor・Gemini CLI・GitHub Copilotなど他社エージェントでも同じフォルダが動く。
• スキルは実行権限を伴う。信頼できない配布元のスキルは、インストール前にスクリプトまで監査する。

Claude Skillsの仕組み: SKILL.mdと3段階の段階的開示

スキルが「プロンプトを長くするだけの機能」と違うのは、コンテキストを常時消費しない点にあります。Claudeは仮想マシン上のファイルシステムを持ち、スキルはそこに置かれたディレクトリとして存在します。Claudeはbashでファイルを読みに行くため、読まれなかったファイルはトークンを1つも消費しません。

読み込みの3レベルとトークンコスト

公式ドキュメントはこの挙動を「progressive disclosure（段階的開示）」と呼び、次の3レベルに分けています。

レベル1が軽いので、スキルを何十個インストールしてもコンテキストは圧迫されません。レベル3のスクリプトは実行結果だけがコンテキストに入り、コード本体は入りません。「Claudeにその場でコードを書かせる」よりスクリプトを同梱したほうが安く、結果も安定するのはこのためです。

SKILL.mdのフロントマター: 必須項目と制約

最小構成はフォルダ1つとSKILL.md 1枚です。必須項目はnameとdescriptionで、公式は次の制約を課しています。

---
name: pdf-processing
description: PDFからテキストと表を抽出し、フォーム入力やページ結合を行う。PDFファイルを扱うとき、またはユーザーがPDF・帳票・文書抽出に言及したときに使う。
---

# PDF Processing

## 使い方
pdfplumber でテキストを抽出する。フォーム入力の手順は FORMS.md を参照。

実務で効くのはdescriptionです。起動時に読まれるのはここだけで、Claudeはこの一文だけを見てスキルを呼ぶかどうかを決めます。「何をするか」に加えて「いつ使うか（どんな語がユーザー入力に出たら発火するか）」まで書くのが公式の推奨です。スキルが自動で呼ばれないときは、本文ではなくdescriptionを疑ってください。

使える環境と条件: claude.ai・Claude Code・Claude APIの違い

「Claude Skills」と一括りにされますが、対応するスキルの種類・共有範囲・実行環境は3つのサーフェスで異なります。

claude.ai（Web版）へのカスタムスキル追加手順

claude.aiではSettings（設定）＞ Featuresからzipファイルとしてスキルをアップロードします。対象はPro・Max・Team・Enterpriseの各プランで、コード実行が有効になっていることが条件です。pptxやxlsxなどのプリビルドスキルは、ユーザーがファイル作成を依頼した時点で裏側ですでに動いており、設定は要りません。

注意点が2つあります。claude.aiのカスタムスキルはユーザー個人に紐づき、組織で一元管理・全社配布する仕組みはありません（チームで配るなら各メンバーが自分でアップロードします）。またWeb版のスキルのネットワークアクセスは、ユーザーや管理者の設定によって全面・部分・不可のいずれかに変わります。外部APIを叩くスキルは、環境によって動いたり動かなかったりします。

サーフェス間で同期しないという制限

公式が制限事項として明記しているのがこれです。claude.aiにアップロードしたスキルはAPIからは見えず、API経由でアップロードしたスキルはclaude.aiに現れず、Claude Codeのスキルはファイルシステム上にあって両者と独立しています。同じスキルを3面で使うなら、3回登録する必要があります。逆に言えば、SKILL.mdをGitで管理し、そこから各面へ配る運用にしておくのが現実的な落としどころです。

Claude Codeでのスキルの作り方と配置場所

Claude Codeのスキルはアップロード不要で、指定ディレクトリに置くだけで認識されます。ディレクトリ名がそのままスラッシュコマンド名になります。

置き場所と呼び出し方

呼び出しは2通りです。Claudeがdescriptionを見て自動で読み込むか、ユーザーが/skill-nameと直接打つか。名前が衝突した場合はenterprise・個人・プロジェクトの順で上書きされ、同名のスキルはバンドル済みスキルより優先されます。プラグイン由来のスキルはplugin-name:skill-nameという名前空間を持つため衝突しません。

ここで1つハマりどころがあります。スラッシュコマンド名を決めるのはディレクトリ名であって、フロントマターのnameではありません（nameは一覧に出る表示ラベル）。プラグインのルートに置いたSKILL.mdだけが例外で、そこではnameがコマンド名になります。「nameを変えたのに/の名前が変わらない」ときはディレクトリ名を見てください。

Claude Code同梱のバンドル済みスキル

Claude Codeには最初から使えるバンドル済みスキルがあります。/doctor、/code-review、/batch、/debug、/loop、/claude-apiなどで、設定のdisableBundledSkillsで無効化できます（v2.1.205以降、/doctorだけはこの設定でも残ります）。これらは固定ロジックを実行する組み込みコマンドと違い、Claudeに詳細な指示を与えて手順をオーケストレーションさせるプロンプトベースの実装です。アプリの起動・検証を担う/run・/verify・/run-skill-generator（いずれもv2.1.145以降）もバンドル済みスキルで、/run-skill-generatorは起動手順を.claude/skills/run-<name>/としてリポジトリに記録します。

Claude Code独自のフロントマター（呼び出し制御・サブエージェント実行）

Claude Codeはオープン標準に独自フィールドを追加しています。とくに使うのは次の4つです（コード例では3つを指定）。

---
name: deploy
description: 本番環境へデプロイする
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
context: fork
---

disable-model-invocation: trueは、デプロイ・コミット・外部送信のように副作用のある操作に必ず付けてください。Claudeが「コードが良さそうだから」と自発的にデプロイを始める余地を消せます。allowed-toolsはプロジェクトの.claude/skills/に置いた場合、ワークスペースの信頼ダイアログを承認して初めて効きます。裏を返せば、他人のリポジトリを開くとき、同梱スキルが自分に広いツール権限を与えている可能性があるということです。信頼する前にスキルを読んでください。

カスタムコマンドのスキルへの統合

公開当初は別物だった.claude/commands/のカスタムコマンドは、現在スキルに統合されています。.claude/commands/deploy.mdと.claude/skills/deploy/SKILL.mdはどちらも/deployを作り、同じように動きます。既存のcommandsファイルはそのまま動作しますが、補助ファイルを同梱できる・呼び出し元を制御できるという理由で、新規に作るならスキル形式が推奨です。同名なら、スキルがコマンドに優先します。

Claude APIでスキルを使う: ベータヘッダーとcontainerパラメータ

APIでスキルを使うには、コード実行ツールが必須です。スキルはそのコンテナの中で動くためで、単にメッセージにスキルIDを添えるだけでは動きません。

リクエストの最小構成

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "予算データのExcelファイルを作成して"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

ベータヘッダーはcode-execution-2025-08-25とskills-2025-10-02の2つ。上の例のように生成物をダウンロードするところまでやるなら、files-api-2025-04-14もbetasに足す必要があります（生成ファイルはfile_idとして返り、Files API経由で取得します）。ここを忘れると、xlsxは生成されたのに手元に落とせません。

カスタムスキルはPOST /v1/skillsへ、SKILL.mdをトップレベルに置いたディレクトリごとアップロードします（PythonのSDKならfiles_from_dir()）。返ってきたskill_idはskill_01AbCdEfGhIjKlMnOpQrStUvのような形式で、これを{"type": "custom", "skill_id": "skill_01...", "version": "latest"}として同じcontainerに指定します。プリビルド側のバージョンは20251013のような日付形式、カスタム側はエポック値です。

API利用時の制限（ここでハマる）

「Web上のデータを取ってきて集計するスキル」はAPIでは動きません。ネットワークが遮断されているためで、外部データが要るなら呼び出し側で取得してファイルとしてコンテナに渡す設計にします。同じスキルがClaude Code（ネットワーク全面許可）では動くので、環境の違いを踏まえずに移植すると必ず詰まります。ZDR契約下の案件でスキルを使う判断は、契約条件を先に確認してください。

公式スキルと入手先: プリビルド4種とリポジトリ

プリビルドのAgent Skills

この4種はClaude API・claude.ai・Claude Platform on AWS・Microsoft Foundryで使えます（Microsoft FoundryではHosted on Anthropicのデプロイが条件）。Claude Codeはこのプリビルド文書スキルには対応せず、カスタムスキルと同梱スキルを使います。

オープンソースのスキルとプラグイン導入

Anthropicはanthropics/skillsリポジトリでスキルを公開しています。Claude Codeからはマーケットプレイスとして登録して導入します。

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

同リポジトリにはドキュメント操作系（docx・pdf・pptx・xlsxの参照実装）に加え、MCPサーバー生成やWebアプリのテストといった開発系、ブランド適用などの業務系が含まれます。Claude Codeには8言語ぶんのAPIリファレンスとSDKの使い方を持つclaude-apiスキルが同梱されています。プラグインとしてスキルを配る実例は、pr-review-toolkitのようなClaude Codeプラグインを見ると構成がつかめます。CLIでスキルを検索・追加したいなら、Vercel製のskills.shのような配布ツールもあります。

skill-creatorによるスキルの作成と評価

スキルを手書きする代わりに、公式マーケットプレイスのskill-creatorプラグインを使う手もあります。

/plugin install skill-creator@claude-plugins-official
/reload-plugins

導入後に「summarize-changesスキルを評価して」のように頼むと、テストケースを書かせ、スキルあり／なしの出力を比較する評価ループを回してくれます。descriptionを直すべきか本文を直すべきかを勘で決めずに済むので、社内配布するスキルほど効きます。評価ファイルの形式はagentskills.ioのドキュメントに掲載されています。

他社エージェントでも動くSKILL.md（Agent Skillsオープン標準）

SKILL.mdの形式はAnthropicが開発し、その後オープン標準としてagentskills.ioで公開されました。Claude Code自身も「Claude Codeのスキルはこのオープン標準に従う」と明記しています。標準に対応するクライアントにはOpenAI Codex・Cursor・Gemini CLI・GitHub Copilot・VS Code・OpenCode・Goose・Kiro・Snowflake Cortex Codeなどが並び、Codex SkillsはそのままSKILL.md互換の実装です。スキル資産はClaude専用ではなく、エージェントを乗り換えても持ち運べると考えて設計して差し支えありません。

名前が似ていても別物のものがあります。Chrome Skills（Gemini in Chrome）は、保存したプロンプトをサイドパネルの/から呼び出す再利用機能で、SKILL.mdフォルダ形式ではなくagentskills.ioのクライアント一覧にも入っていません。「スキル」という語だけで互換性を推測しないでください。

MCP・CLAUDE.md・プロンプトとの使い分け

スキルは「万能の置き換え先」ではありません。混同されやすい3つとの境界を引いておきます。

MCP（Model Context Protocol）との違い

MCPはModel Context Protocolの略で、外部システム（DB、SaaS、社内API）へClaudeを接続するためのプロトコルです。MCPは「接続」を担い、スキルは「手順」を担います。役割が違うので競合しません。実際、Excalidraw MCPのような接続系で図の作成手段をつなぎ、そのうえで「どの図をどう描くか」の作法をスキルに書く、という組み合わせが自然です。判断基準は単純で、外部システムへの接続や認証が要るならMCP、既存の道具の使い方や社内ルールを教えたいならスキルです。

CLAUDE.md・システムプロンプトとの違い

CLAUDE.mdやシステムプロンプトは、常にコンテキストに載る「事実」の置き場です。スキルは呼ばれたときだけ載る「手順」の置き場です。公式ドキュメントの言い方を借りれば、CLAUDE.mdの一節が事実ではなく手順に育ってきたら、それはスキルに切り出す合図です。長い参照資料をCLAUDE.mdに書くと毎回トークンを払いますが、スキルなら使うときまでコストはほぼゼロです。

スキルにすべきでない場面と、失敗するパターン

一度きりの依頼はスキルにしないでください。作成・保守コストのほうが高くつきます。スキル化の判断基準は「同じ指示・チェックリスト・多段手順をチャットに貼り直しているか」です。貼り直していないなら、まだプロンプトで十分です。

失敗の典型は3つあります。第一に、descriptionに用途しか書かず発火条件を書かないケース。自動で呼ばれず「スキルが効かない」と誤解します。第二に、context: forkをガイドライン型のスキル（「このAPI規約に従う」等）に付けるケース。サブエージェントは指示だけ受け取ってタスクを持たないため、何も返さず終わります。forkは実行手順が明示されたスキル専用です。第三に、出所不明のスキルをそのまま入れるケース。スキルはClaudeにツール呼び出しとコード実行を指示できるため、悪意あるスキルはデータ持ち出しや不正アクセスに直結します。公式も「ソフトウェアをインストールするのと同じ扱いにせよ」と警告しており、外部URLを取りに行くスキルはとくに危険です（取得先の内容が後から書き換わる）。導入前にSKILL.mdだけでなく同梱スクリプトまで読む、が最低ラインです。

よくある質問

Claude Skillsは無料プランでも使えますか？

claude.aiでカスタムスキルをアップロードできるのはPro・Max・Team・Enterpriseで、コード実行が有効になっている必要があります。pptx等のプリビルドスキルはファイル作成時に裏で動く形で提供されます。Claude Codeのスキルはファイルシステムベースなので、アップロード自体が不要です。

claude.aiにアップロードしたスキルは、Claude CodeやAPIでも使えますか？

使えません。カスタムスキルはサーフェス間で同期しないと公式に明記されています。claude.ai・API・Claude Codeで個別に登録・配置してください。

スキルが自動で呼び出されないときは何を直せばよいですか？

まずdescriptionを見直します。起動時にClaudeが読むのはname/descriptionだけで、そこに「いつ使うか」が書かれていないと発火しません。またClaude Codeでdisable-model-invocation: trueを付けていると、定義上そのスキルは/nameで人間が呼ぶまで動きません。

おすすめのClaude Skillsや一覧はどこで手に入りますか？

公式のオープンソーススキルはanthropics/skillsリポジトリにまとまっており、Claude Codeからは/plugin marketplace add anthropics/skillsで導入できます。文書生成のpptx・xlsx・docx・pdfはプリビルドとして最初から利用でき、Claude Codeには/code-review・/debug・/batch・/loop・/claude-apiなどのバンドル済みスキルが同梱されています。

スキルとMCPはどちらを導入すべきですか？

目的が違うため二者択一ではありません。社内DBやSaaSへの接続・認証が必要ならMCP、既存ツールの使い方や社内の作法をClaudeに覚えさせたいならスキルです。両方を組み合わせるのが一般的な構成です。関連する内容として、Claude Scienceもご覧ください。

関連記事

• Codex Skillsとは？できること・SKILL.mdの作り方と配置場所を解説【2026年最新】
• skills.shとは？Vercel製エージェントスキルCLIの使い方とnpxコマンド一覧【2026年最新】
• pr-review-toolkitとは｜Claude Codeプラグインの導入とreview-prの使い方
• Excalidraw MCPの導入と使い方｜Claude Code・Cursor・Codex設定と実装の選び方
• Chrome Skillsの基本機能とGemini統合による業務自動化の全体像