Claude Skillsの作り方を知りたい人が最初に知るべきなのは、Skillが「特別なプログラム」ではなくフォルダに置いた1枚のMarkdownファイル（SKILL.md）だという点です。毎回同じ前提をチャットに貼り付けている作業、たとえば「議事録はこの見出し構成で」「社内の略語はこう展開して」といった業務ルールを、一度書いておけばClaudeが必要なときだけ自動で読みに来てくれます。
本記事では、Anthropicの公式ドキュメントで確認できる仕様をもとに、SKILL.mdの必須項目、実際に動く1本の作成例、そして「作ったのに発動しない」ときの切り分け方までを手順で整理します。2026年8月11日時点の公式ドキュメントの記載にもとづいています。
Claude Skillsとは何か｜プロンプトやMCPとの違い
Skillsは、Claudeに専門性を持たせるための「読み物＋道具」をひとまとめにした仕組みです。会話ごとに指示を出し直すプロンプトとは、読み込まれるタイミングが根本的に違います。
Skillの実体は「フォルダ＋SKILL.md」
1つのSkillは1つのフォルダに対応し、その中にSKILL.mdを置きます。必要に応じて、追加の解説Markdown、参照用の資料、実行用スクリプトを同じフォルダに同梱できます。公式ドキュメントでは、この構成を「新しく入ったメンバーに渡すオンボーディング資料」にたとえています。特別なビルド作業やインストーラーは不要で、テキストエディタだけで作れます。
プロンプトやCLAUDE.mdとの使い分け
プロンプトは1回限りの指示、Skillsは「必要になったときだけ呼び出される再利用可能な指示」です。公式ドキュメントは、Skillsを使う利点として「同じガイダンスを会話のたびに繰り返さずに済む」ことを挙げています。常に効かせたい方針はプロジェクト共通の設定ファイルに、特定の作業のときだけ効かせたい手順はSkillに、と分けると管理しやすくなります。
3段階で読み込まれる仕組み（プログレッシブディスクロージャー）
Skillsの設計で最も重要なのが、内容が一度に全部読み込まれるわけではないという点です。公式ドキュメントは3つの階層を明示しています。
| 階層 | 読み込まれるタイミング | コンテキスト消費 | 中身 |
|---|---|---|---|
| レベル1：メタデータ | 起動時に常時 | 1スキルあたり約100トークン | YAMLフロントマターのnameとdescription |
| レベル2：本文 | スキルが発動したとき | 5,000トークン未満が目安 | SKILL.md本文の手順・ガイドライン |
| レベル3：同梱ファイル | 必要になったときだけ | 読むまでゼロ | 追加のMarkdown・資料・スクリプト |
つまり、スキルをたくさん入れても、発動していない分はnameとdescriptionしか場所を取りません。逆に言えば、発動するかどうかはdescriptionの書き方だけで決まるということでもあります。ここが後述する失敗の最大の原因になります。
SKILL.mdの書き方｜必須フィールドと文字数制限
SKILL.mdは、先頭にYAMLフロントマター、その下にMarkdownの本文、という構成です。公式仕様で決まっている部分は多くありません。
必須は name と description の2つだけ
公式ドキュメントが required fields として挙げているのはnameとdescriptionの2つです。それぞれに次の条件があります。
- name：最大64文字。使えるのは小文字の英字・数字・ハイフンのみ。XMLタグは不可。さらに予約語として「anthropic」「claude」を含められません。
- description：空にできず、最大1024文字。XMLタグは不可。「何をするか」と「いつ使うか」の両方を含める必要があります。
意外な落とし穴がnameの予約語です。「claude-minutes」のようにツール名を入れた名前を付けたくなりますが、これは仕様上はじかれます。meeting-minutes-formatのように、業務側の言葉で命名してください。
descriptionは説明文ではなく「発動条件」
ここが作り方の核心です。公式ドキュメントは、descriptionについて「Claudeがリクエストと照合して、そのスキルを発動させるかどうかを判断する対象」と説明しています。つまりdescriptionは読者向けの紹介文ではなく、ルーティングのための条件文です。
公式のPDF処理スキルの例では、descriptionが「Extract text and tables from PDF files, fill forms, merge documents.（何をするか）」に続けて「Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.（いつ使うか）」という形になっています。後半の「Use when〜」がないと、機能の説明としては正しくても発動しません。
本文に書くこと・書かないこと
本文はレベル2として発動時に読み込まれるため、5,000トークン未満に収めるのが目安です。ここには判断を伴う手順やガイドラインを書き、長い参照資料や大量の例は別ファイルに切り出して同梱します。同梱ファイルは読まれるまでコンテキストを消費しないため、分けておくほど軽くなります。
【実例】業務ルールを1つ覚えさせるSKILL.mdを作る
抽象論だけでは手が動かないので、実際に1本作ってみます。題材は多くの職場で共通する「議事録フォーマットの統一」です。
題材：議事録の見出しと禁止事項を固定する
「議事録を作って」と頼むたびに、見出しの順番が変わる、決定事項と検討中の話が混ざる、担当者名が抜ける——このあたりを毎回口頭で直しているなら、スキル化の効果が出やすい典型例です。逆に、毎回判断が変わるような業務はスキル化に向きません（後述）。
完成したSKILL.mdの全文
フォルダ名をmeeting-minutes-formatとし、その中にSKILL.mdを次の内容で作ります。
| SKILL.md の中身 |
|---|
---name: meeting-minutes-formatdescription: 社内会議の議事録を決まった見出し構成に整形する。会議メモ・録音の書き起こし・打ち合わせ内容から議事録を作るときや、ユーザーが議事録・打ち合わせメモ・MTGまとめに言及したときに使う。---
|
ポイントはdescriptionです。「議事録を整形する」だけで止めず、「会議メモから議事録を作るとき」「ユーザーが議事録・MTGまとめに言及したとき」という実際の依頼で使われる言葉を並べています。ここに実務で使う呼び方（MTG、打ち合わせメモなど）を入れておくと発動率が上がります。
置き場所：個人用とプロジェクト用
Claude Codeで使う場合、カスタムSkillはファイルシステムベースで、アップロード作業は不要です。公式ドキュメントが示す置き場所は次の2つです。
~/.claude/skills/：個人用。自分のどの作業でも効かせたいスキル。.claude/skills/：プロジェクト用。リポジトリに入れてチームで共有したいスキル。
先ほどの例なら~/.claude/skills/meeting-minutes-format/SKILL.mdという配置になります。Claude Codeの導入からつまずいている場合は、Claude Codeの使い方（始め方からつまずき対処まで）を先に確認してください。外部ツールとの接続まで広げたい場合はClaude CodeのMCPサーバー設定手順が参考になります。
【独自】スキルが発動しない・効かないときのチェックリスト
SKILL.md自体は数分で書けますが、実際には「作ったのに使われない」で止まる人が多い部分です。仕様から逆算した原因と対処を整理します。
症状と原因の対応表
| 症状 | 考えられる原因 | 対処 |
|---|---|---|
| まったく発動しない | descriptionに「いつ使うか」が無く、機能説明だけになっている | 「〜するときに使う」を追記し、実際の依頼で使う語（MTG、打ち合わせ等）を入れる |
| スキルが認識されない | nameに大文字・アンダースコア・日本語、または予約語「claude」「anthropic」が入っている |
小文字英数字とハイフンのみ・64文字以内に直す |
| 発動はするが指示が守られない | 本文が長すぎて要点が埋もれている | 本文は5,000トークン未満を目安に絞り、詳細は別ファイルへ切り出す |
| 別のスキルが誤って発動する | 複数スキルのdescriptionの守備範囲が重なっている | 各descriptionに「使わない場面」も1文添えて境界を作る |
| claude.aiでは動くがClaude Codeで無い | カスタムSkillはサーフェス間で同期されない仕様 | 使いたい環境ごとに個別に配置・アップロードする |
サーフェス別の落とし穴（claude.ai / Claude Code / API）
ここは日本語の解説で省かれがちですが、実務では最も引っかかる部分です。同じSKILL.mdでも、動く場所によって置き方・共有範囲・できることが変わります。
| 項目 | claude.ai | Claude Code | Claude API |
|---|---|---|---|
| 置き方 | 設定 > Features からzipでアップロード | ~/.claude/skills/ または .claude/skills/ |
Skills API（/v1/skills）にアップロード |
| 共有範囲 | ユーザー個人のみ。組織で一括管理はできない | 個人用／プロジェクト用。プラグインでも配布可 | ワークスペース全体で共有 |
| ネットワーク | 設定により全面・部分・不可と変わる | PC上の他プログラムと同等に利用可 | 外部通信不可・実行時のパッケージ追加も不可 |
| 利用条件 | Pro・Max・Team・Enterpriseでコード実行が有効なこと | ファイル配置のみ | コード実行ツールとベータヘッダーが必要 |
この表から言えること：外部APIを叩くような処理を含むスキルは、Claude Codeでは動いてもAPI経由では動きません。逆に、チーム全員に同じスキルを行き渡らせたいなら、claude.aiは個人単位でのアップロードになるため運用コストが高く、リポジトリに.claude/skills/を置くClaude Code方式のほうが配布は楽です。「まず個人で試す→リポジトリに入れてチーム展開」という順番が現実的です。なお、PowerPointやExcelなどの標準搭載スキルはClaude Codeでは提供されない点にも注意してください。
どこまで任せるかの線引きと安全面の注意
スキルは便利ですが、無条件に増やすほど良いものではありません。導入前に押さえておきたい判断軸があります。
他人が作ったSkillをそのまま入れない
公式ドキュメントは、Skillsについて「信頼できる提供元のものだけを使う」よう明記しています。Skillは指示とコードでClaudeに新しい振る舞いを与えるため、悪意のあるSkillは本来の目的と異なるツール実行やデータ持ち出しを指示できてしまいます。外部から入手する場合は、SKILL.mdだけでなく同梱スクリプトや参照先URLまで確認するのが前提です。ソフトウェアを1本インストールするのと同じ慎重さで扱ってください。
スキル化に向く業務・向かない業務
実際に運用してみると、向き不向きははっきり分かれます。
- 向く：出力形式が決まっている（議事録・報告書・コミットメッセージ）、社内固有のルールがある（略語・命名規則・禁止表現）、手順が毎回同じ。
- 向かない：毎回の判断が状況で変わる、ルール自体が月単位で改訂される、一度しか使わない作業。
迷ったときは「同じ指示を3回以上コピペしたか」を基準にすると判断しやすくなります。3回に満たないものは、まだプロンプトのままで十分です。また、スキルを増やしすぎるとdescriptionの守備範囲が重なって誤発動が起きるため、最初は3〜5本程度に絞り、使われなかったものは畳む運用が現実的です。ターミナル中心の環境を併用しているなら、Codex CLIの使い方と導入手順もあわせて見ておくと、同じ発想の指示書をどこまで共通化できるか判断しやすくなります。
まとめ｜Claude Skillsは「descriptionが8割」
Claude Skillsの作り方は、技術的にはSKILL.mdを1枚書くだけで完了します。難しいのは書式ではなく、どの依頼のときに発動してほしいかを言葉にすることです。必須項目はnameとdescriptionの2つ、nameは小文字英数字とハイフンのみで予約語不可、descriptionには「何をするか」と「いつ使うか」の両方を入れる——この3点を外さなければ、最初の1本は動きます。
まずは自分が3回以上コピペしている指示を1つ選び、~/.claude/skills/に置いて試してください。発動しなければdescriptionに実際の依頼で使う言葉を足す、という調整を繰り返すのが最短です。運用中にClaude Code側の利用上限で作業が止まった場合は、Claude Codeの利用上限に達したときの対処法で復旧手順を確認できます。
出典：Anthropic公式ドキュメント「Agent Skills」／anthropics/skills（公式スキルリポジトリ）（いずれも2026年8月11日確認）
