Claude Skills 自作入門 — SKILL.md で動く最小型

Agent Skills とは — 組織化フォルダで Claude を専門エージェント化する拡張機能

Agent Skills は「組織化されたフォルダ内の指示・スクリプト・資料」で、Claude が動的に発見して読み込める拡張機能です。汎用的な Claude を、特定タスクに強い専門エージェントに変える仕組みであり、業務固有のドメイン知識・社内ルール・反復作業の手順を Claude に「身に付けさせる」標準的な方法として位置付けられています。プロンプトに毎回貼り付けていた長文ガイドラインを、フォルダに切り出して再利用可能にするイメージで捉えると分かりやすいでしょう。

既存の Claude 拡張機能との違い

似た概念に MCP(Model Context Protocol)サーバーやスラッシュコマンドがありますが、Agent Skills はこれらと役割が異なります。MCP は外部システムへの接続(API・データベース等)を担い、スラッシュコマンドはユーザーが明示的に呼び出す定型処理です。一方 Agent Skills は、Claude 自身が会話の文脈から「今このスキルが必要か」を判断して読み込む点が特徴で、ユーザーが毎回スキル名を覚えておく必要がありません。

どの製品で使えるか

Agent Skills は Claude.ai の Pro / Max / Team / Enterprise プラン、Claude Code、Claude Agent SDK、Developer Platform で共通サポートされています。同じ SKILL.md を複数の実行環境で使い回せる設計になっており、社内で整備したスキルを Claude.ai のチャットからも CI 上のヘッドレス実行からも参照できます。

SKILL.md 最小型 — YAML フロントマター + 本文だけで動く

SKILL.md は YAML フロントマター + Markdown 本文 という最小構成で動きます。フロントマターには name(スキル識別子)と description(発火条件の説明)の 2 項目を書き、本文に Claude へ守ってほしいルールや手順を Markdown で記述するだけです。最初の 1 本は数分で書けるため、まずは「自社の API 規約」「コミットメッセージ規約」など、繰り返し説明している社内ルールを 1 ファイルに切り出すのが取り掛かりやすい入口になります。

---
name: api-conventions
description: 当社 REST API の設計規約
---

# API 規約

- URL パスは kebab-case
- JSON フィールドは camelCase
- 一覧エンドポイントには必ず pagination を入れる
- API バージョンは URL に含める(例: /v1/users)

たったこれだけで、Claude は必要なタイミングで本スキルを読み込み、API 設計の質問に当社規約に沿って答えるようになります。重要なのは description の書き方 で、ここに「いつ・どんな場面で読むべきか」が具体的に書かれていないと、Claude はスキルの存在に気付けません。「当社 REST API の設計規約。新規エンドポイント追加・既存 API 修正・OpenAPI スキーマ生成のときに参照」といった粒度で、トリガー条件を動詞で書くのがコツです。

配置場所とスコープ

SKILL.md の置き場所はスコープによって変わります。Claude Code であれば、リポジトリ単位で共有したいスキルは .claude/skills/<skill-name>/SKILL.md、個人専用は ~/.claude/skills/<skill-name>/SKILL.md に配置します。プロジェクト配下に置けば Git で管理でき、チーム全員が同じスキルを共有できるため、社内ルールの教育コスト削減にも直結します。

Progressive Disclosure(段階的開示)— 3 段階ロードで 100 個入れても肥大化しない

出典によれば、Agent Skills はトークン効率のため、情報を 3 段階で開示します:

この設計により、多数のスキルを登録してもコンテキストが肥大化しない 構成になっています。仮に 100 個のスキルを登録しても、常時消費するのは各スキルの name と description(数十トークン)だけで、本文・参照ファイル・スクリプトはタスクに該当したときにしかロードされません。プロンプトに全ガイドラインを貼り付ける従来方式と比較すると、コンテキスト消費量は桁違いに小さく抑えられます。

なぜ Progressive Disclosure が重要なのか

Claude のコンテキストウィンドウは大容量化が進んでいるとはいえ、無限ではありません。プロジェクトが大きくなれば、ソースコード・テスト・設計ドキュメントを読み込むだけで容量を圧迫しがちです。Agent Skills の段階的開示は、「使うときだけ展開する」原則 を仕組み化することで、知識資産を増やしてもコストが線形に増えない設計を実現しています。社内 Wiki をすべて Claude に流し込む発想ではなく、必要な引き出しだけを開けさせる設計に切り替えるための基盤と言えます。

出典: Anthropic Engineering: Equipping agents for the real world with Agent Skills

実例: PDF Skill — SKILL.md + reference.md + scripts/ の典型構成

Anthropic が公開する PDF Skill は以下の構成:

pdf-skill/
├── SKILL.md             # PDF を扱うためのルール
├── reference.md         # フォームフィールド抽出の詳細
└── scripts/
    └── extract_form.py  # PDF フォーム抽出の Python スクリプト

Claude は PDF タスクが発生したとき、まず SKILL.md を読み、必要なら scripts/extract_form.py を実行します。SKILL.md 本体には「PDF を扱う基本的なルール・利用可能ファイルの一覧・推奨フロー」を簡潔に書き、込み入った詳細(フォームフィールド抽出の細かい仕様等)は reference.md に逃がす構成です。本文を薄く保ったまま、タスクが深掘りを要求したときだけリファレンスを読みに行く流れが、Progressive Disclosure を実践するうえで再現しやすいパターンになっています。

公式サンプルから学べるポイント

Anthropic は GitHub の anthropics/skills リポジトリで PDF・Excel・PowerPoint・Word 等の実用スキルを公開しています。これらに共通するのは、(1) description が動詞で発火条件を明示している、(2) SKILL.md 本体は手順の骨格だけ、(3) 詳細仕様や長いリストは別ファイルへ分離、(4) 自動化が必要な箇所のみスクリプトを置く の 4 点です。自作スキルの初期テンプレートとして、まず公式サンプルの構成を真似るところから始めると失敗が少なくなります。

自作スキルを作る 5 手順 — SKILL.md 配置からトリガー確認まで

ここからは、社内に最初の 1 本を導入する具体的な手順を整理します。所要時間は 5 〜 10 分程度。最初は完璧を目指さず、まず動かしてから description と本文を磨いていく進め方が現実的です。

1. .claude/skills/<skill-name>/SKILL.md を作成
2. YAML フロントマターに name と description を記載(どんなタスクで使うか明確に)
3. 本文に具体的な手順・ルール・禁則事項を書く
4. 必要なら関連ファイル(reference.md, templates/, scripts/)を配置
5. Claude Code で実行、スキルが適切にトリガーされるか確認

トリガー確認のコツ

スキルを配置したら、description に書いた発火条件をそのまま含む依頼を Claude に投げて発動を確認します。「新しい /v1/orders エンドポイントを設計して」のように具体的な業務指示を出し、Claude の応答が SKILL.md のルールに沿っているか(URL は kebab-case か、pagination が含まれるか等)を 1 点ずつチェックしましょう。発動しない場合は description の語彙が抽象的すぎる可能性が高いため、「いつ・何を・どう判断するか」をより具体的な動詞で書き直すのが有効です。

良いスキルの共通点 — description で発火条件明示・本文 100 行前後・Git 管理

社内で複数のスキルを運用していくと、自然と参照され続けるスキル と 書いたまま忘れられるスキル に分かれてきます。生き残るスキルには共通点があり、ここを押さえるだけで保守コストと実効性が大きく変わります。

• description が いつ使うべきか を明確に述べている
• SKILL.md 本文が 100 行前後に収まっている(長すぎると他スキルを食う)
• 実行可能なコマンドや具体例が含まれる
• バージョン管理されている(Git)

アンチパターン: 何でも詰め込んだ巨大スキル

避けたいのは、1 つの SKILL.md に複数のドメイン(API 規約・テスト規約・デプロイ規約)を詰め込む書き方です。本文が 500 行を超えると、第 2 段階ロード時の消費トークンが膨らみ、他スキルとのコンテキスト争いに負けて読み込まれづらくなります。役割ごとにスキルを分割し、それぞれの description を尖らせる方が、Claude にとっても判断しやすく、人間にとっても保守しやすい資産になります。

運用に組み込むには

スキルは書いて終わりではなく、業務フローの変更に合わせて更新し続ける資産です。社内で運用する場合は、Pull Request のレビュー観点に「このルールは SKILL.md に反映済みか?」を加える、月 1 回の棚卸しでスキル一覧を見直す、といった軽量な運用ルールを敷くだけでも、知識が陳腐化せず Claude の出力品質が安定します。Git で管理されているからこそ、変更履歴を辿れる点も活用しましょう。

出典(一次情報)

本記事の作成に直接参照した一次情報源は以下の通りです。最新の正確な情報は各リンク先で必ずご確認ください。

• Anthropic Engineering: Equipping agents for the real world with Agent Skills
• Agent Skills Overview(公式ドキュメント)
• GitHub: anthropics/skills — 公式サンプル集