SKILL.md実践ガイド：フィールド仕様とToken設計

もしあなたが Agent 開発に取り組んでいるなら、この一年で最も時間をかけて理解する価値のある概念は、ある新しいモデルではなく、SKILL.md というごく普通の Markdown ファイルかもしれません。これは Anthropic が提唱し、2025 年 12 月 18 日に agentskills.io の名義でオープン標準として公開され、2026 年 3 月までに 32 のプラットフォーム（Microsoft、OpenAI、Google Gemini CLI、Cursor、GitHub を含む）に採用され、claude.ai、Claude Code、Claude 開発者プラットフォーム（API）などの入口をカバーしています。SDK も API 統合もデプロイ工程も不要で、フォルダ一つと Markdown ファイル一つがあれば、Agent に新しいスキルを習得させられます。この記事は二部構成です。第 1 部では Skill の定義、標準の進化、ディレクトリ構造、フィールドの厳格な制約、25+ プラットフォームのインストール経路を解説します。第 2 部では段階的読み込みの三層 Token 台帳、MCP との境界、FAQ、公式ベストプラクティスに入ります。読み終えれば、チームのプロジェクトにそのまま導入できる SKILL.md ハンドブックが手に入ります。

Skill とは結局何か：SKILL.md を入れたフォルダが、なぜ新人に入社ガイドを渡すようなものなのか

まず定義をはっきりさせましょう。Agent Skill とは一つのフォルダであり、そのフォルダには必ず SKILL.md が入っていなければなりません。このファイルは二つの部分から成ります。冒頭は三本のハイフンで囲まれた YAML frontmatter メタデータで、この Skill の名前と用途を宣言します。ハイフンの下は Markdown 本文で、実際の指示、フロー、例、制約を担います。SKILL.md 以外に、フォルダにはスクリプト、テンプレート、参考ドキュメントなどのリソースを置くこともでき、本文が必要に応じて参照します。

なぜ新人に入社ガイドを渡すようなものと言えるのか。能力は高いがあなたのチームについて何も知らない新人を雇ったと想像してください。彼は最初からあなたの社内ドキュメントをすべて暗記したりはしません。まず一ページの職務説明（この職務が何を担当し、いつ出番なのか）を受け取り、実際にタスクを受けたときに該当する操作マニュアルを開き、記入が必要なときにテンプレートを取りに行きます。Agent が Skill を読む仕組みもまったく同じです。タスクに関連するときだけ読み込んで実行します。関連しないとき、この Skill はそのコンテキストにほとんど負担をかけません。これこそが、SKILL.md が一つのファイルに大量のドメイン知識を詰め込みながら、なお拡張性を保てる根本的な理由です。

もう一つ見落とされがちな位置づけの問題があります。SKILL.md はプレーンテキストのオープン標準であり、同じファイルを 25 以上の互換プラットフォームでそのまま使え、プラットフォームごとに適応層を書く必要がありません。これは、チームが蓄積した知識資産が特定の一社のツールに縛られないことを意味します。

Anthropic が提唱し、agentskills.io がオープン標準に：2025 年 10 月から 2026 年 3 月までの採用タイムライン

Agent Skills の進化のペースは、一本のタイムラインでその重みがはっきり見えます。

• 2025 年 10 月 16 日：Agent Skills は PowerPoint、Excel、Word、PDF の公式 Skill とともに公開され、「Markdown で Agent に仕事を教える」ということを初めて表舞台に載せました。
• 2025 年 12 月 18 日：agentskills.io で正式にオープン標準として公開され、フォーマットはある一製品の内部規約から、あらゆるプラットフォームが実装できる事実上の仕様へと変わりました。
• 2026 年 3 月：すでに 32 のプラットフォームが同じ SKILL.md フォーマットを採用しており、その名簿には Microsoft、OpenAI、Google Gemini CLI、Cursor、GitHub が含まれます。同時に入口の形態も単一の IDE プラグインから claude.ai、Claude Code、Claude 開発者プラットフォーム（API）へと広がりました。

このタイムラインのエンジニアリング上の意味は、2025年に SKILL.md を書くのはまだ「試し」だったが、2026年9月の今日、それはチームの知識資産の事実上の標準的な担い手になったということだ。今日あなたが書いた description は、十数社の異なるベンダーの Agent で、同じ解析ロジックによって読み取られ、マッチングされるかもしれない。

なぜ Skill を書く価値があるのか：ドメイン知識のパッケージ化、能力の補完、監査可能なプロセス、クロスプラットフォーム相互運用、チーム知識の蓄積

公式が示す価値提案は5つあり、それぞれが実際のニーズに対応している：

1. ドメイン専門知識のパッケージ化。法務レビューのプロセス、データ分析パイプライン、財務モデリングの手法、ある人格特性——これらはもともと文書、口伝え、あるいは個人の経験に散在していたものが、Agent が読み取って実行できるパッケージとして固定化される。以前はプロンプトで何度も繰り返し述べる必要があったが、今は一度書けば再利用できる。
2. もともと持っていなかった能力を与える。Agent は自分ではプレゼンテーションを作成したり、PDF を処理したり、MCP サーバーを構築したり、カスタム schema に従ってデータセットを分析したりできない。Skill は「どうやるか」を手順とスクリプトとして書き出し、能力が補われる。
3. 多段階タスクを一貫した監査可能なプロセスにする。データベース移行を例に取ると、毎回同じ検証手順を踏み、その会話におけるモデルの気分や即興に依存しないため、結果は自然とより安定し、「どのステップで問題が起きたか」も追跡しやすくなる。
4. クロスプラットフォーム相互運用。一度書けば、25+ のプラットフォームで変更なしに使え、サンクコストは極めて低い。
5. チーム知識の共有。組織の知識をバージョン管理されたパッケージに入れる。人が去っても、知識は Skill に残る——これは多くのチームが本気で Skill を書こうと決断するきっかけである。

最小ディレクトリと完全ディレクトリ：SKILL.md は必須、scripts/、references/、assets/ はすべて任意

ディレクトリ構造は想像するほど複雑ではなく、2つの形態しかない：

3つの任意ディレクトリにはそれぞれ明確な役割分担がある：scripts/ は実行可能コードを置き、Agent が必要なときに実際に「実行する」もの；references/ はドキュメントを置き、Agent が必要なときに「読む」補足知識；assets/ はテンプレートと静的リソース、たとえばフォームテンプレートやスタイルファイルを置く。**ここに頻出の落とし穴がある：**本文で、あるリソースが「読む」べきものか「実行する」べきものかを明確に書かなければならない。そうでなければ、Agent が参考ドキュメントをスクリプトとして実行したり、スクリプトをドキュメントとして一通り読んだりして、大量の token を浪費する可能性がある。

4ステップの作成フロー：ディレクトリ作成、SKILL.md の記述、必要に応じたリソース追加、skills ディレクトリへのコピー

実装までの道筋はたったの4ステップです：

1. ディレクトリ作成：mkdir my-skill && cd my-skill。ディレクトリ名には小文字英字、数字、ハイフンのみ使用できます。これは後で frontmatter の name と一致しているかを検証するためです。
2. SKILL.md の記述：frontmatter には name と description が必須で、区切り文字の後に Markdown の指示本文を書きます。
3. 任意でリソース追加：必要に応じて scripts/、references/、assets/ の3種類のディレクトリを追加し、本文中で参照します。
4. 対象プラットフォームの skills ディレクトリへコピー：ここでは2つのスコープを区別する必要があります——プロジェクトレベルの Skill は git を通じてチーム全体で共有され、ユーザーレベルの Skill は自分のマシン上でのみ利用できます。

最小構成の実例を分解：code-review の frontmatter と When to use / Process 本文

以下の code-review は、すぐに使える最小の Skill です：

---
name: code-review
description: コード変更をレビューし、実行可能なフィードバックを提供する。ユーザーが PR を提出したとき、コードレビューを依頼したとき、または特定のコード品質の確認を求めたときに使用する。
---

## When to use

ユーザーが pull request を提出したとき、特定のファイルのレビューを依頼したとき、または「このコードに問題がないか見てほしい」と言ったときに使用する。

## Process

1. 対象コードを読み、まず全体的な意図を理解する。
2. 欠陥と境界条件を探す：null 値、範囲外、並行性、エラーハンドリングの漏れ。
3. セキュリティ脆弱性を確認する：インジェクション、権限昇格、機密情報の漏洩、安全でないデシリアライズ。
4. 実行可能なフィードバックを提供する：各問題に最小限の修正例を添え、深刻度を明記する。

ポイントは3つあります。第一に、description は「何をするか」と「いつトリガーするか」の両方を明確に述べる必要があります——「コード変更をレビューし、実行可能なフィードバックを提供する」が何をするかであり、「ユーザーが PR を提出したとき……使用する」がいつ使うかであり、どちらの部分も欠かせません。第二に、本文では ## When to use でトリガーシナリオをもう一度説明し、ロード後の本文でもモデルが逸脱しないように助けます。第三に、## Process は番号付きリストでフローを固定します：コードを読む → 欠陥と境界を確認 → セキュリティ脆弱性を探す → 実行可能なフィードバックと例を提供する。ステップが具体的であるほど、複数回実行したときの一貫性が高まります。

必須フィールドの厳格な制約：name の64文字とハイフンのルール、description の1024文字の2要素

検証ルールはプログラムでチェックできるため、記憶に頼らないでください：

• name：最大 64 文字。小文字英字、数字、ハイフンのみ許可。親ディレクトリ名と一致しなければならない。連続するハイフンは許可されない。ハイフンで始まるか終わることはできない。
• description：最大 1024 文字。「この Skill が何をするか」と「いつアクティブ化するか」の両方を説明する必要があり、両方の部分が信頼できる Skill の発見にとって極めて重要です。

description が必須の二要素である理由は、起動時にシステムプロンプトへ注入され、ルーティング判断に直接関与するからです。「Skill は確かに存在するのに、なぜかいつも発動しない」という問題の多くは、description に能力だけを書き、発動シナリオを書いていないことに根本原因があります。

任意フィールドの使い方：license、compatibility、metadata がそれぞれ担う情報

3 つの任意フィールドは、「コンプライアンス、環境、帰属」という 3 種類のエンジニアリング上の問題を解決します：

• license：ライセンス名を書きます。例えば MIT や Apache-2.0 です。パッケージに同梱されたライセンスファイルを指すパス参照として書くこともでき、配布時のコンプライアンス監査に便利です。
• compatibility：対象プラットフォーム、必要な依存パッケージ、ネットワークアクセスの要否など、環境要件を宣言します。これにより Agent や利用者は、読み込む前に実行可能かどうかを把握できます。
• metadata：任意のキーと値のマッピングで、作者、バージョン、ホームページなどの付加属性を保存します。チームが資産管理やバージョン追跡を行う際の拠り所となります。

完全な例 pdf-processing：license、compatibility、metadata と Quick start / Advanced features の構成方法

任意フィールドと階層化された本文をまとめたものが、本番品質の SKILL.md の姿です：

---
name: pdf-processing
description: PDF からテキストとフォームデータを抽出し、構造化された出力を生成します。ユーザーが PDF を解析したり、フィールドを一括抽出したり、PDF フォームに入力したりする必要がある場合に使用します。
license: Apache-2.0
compatibility: Python 3.10+ が必要で、pdfplumber と pypdf に依存し、ネットワークアクセスは不要
metadata:
  author: platform-team
  version: 1.4.0
---

## Quick start

```python
import pdfplumber

with pdfplumber.open("input.pdf") as pdf:
    for page in pdf.pages:
        print(page.extract_text())
```

## Advanced features

フォーム入力については [FORMS.md](FORMS.md) を参照してください。

この例の要点は階層化です。frontmatter では license でライセンスを明示し、compatibility で依存関係である pdfplumber と pypdf、および対応するホスト環境を明記し、metadata で author と version を記録します。本文では「最もよく通る経路」を ## Quick start に置き、そのままコピーできるコードを提示し、低頻度だが複雑な機能は ## Advanced features にまとめ、FORMS.md のフォーム入力ガイドへリンクします。これにより、デフォルトで読み込まれる本文は非常に短くなり、重いドキュメントは本当に必要なときだけ読まれます。

description こそがトリガー：Agent はこれに基づいてこの Skill を有効化するかどうかを決める

この一文は単独で強調しておかなければならない：description はあらゆる Skill の中で最も重要な部分である。Agent はまさにこれに基づいてその Skill を有効化するかどうかを決めており、name によってでも本文によってでもない。無数のエンジニアリング実践が同じ結論を繰り返し裏付けている：Skill がどれほどよく書かれていても、description がトリガーとなるシナリオを十分に捉えていなければ、それは存在しないのと同じである。

さらに厳しいことに、このことはすでに定量的に検証されている。2026 年 8 月の arXiv 論文「What Keeps Agent Skills from Being Reusable?」は 138,133 件の公開 SKILL.md を分析し、欠陥を二つの層に分類した：Tier 1「仕様適合性」は計 14 項目のチェック、Tier 2「ベストプラクティス適合性」は計 17 項目のチェックであり、結論として仕様適合性の欠陥が支配的で、ルーティング（トリガー）系の欠陥は Skill が発見される品質を直接低下させる。論文はさらに非常に具体的な実証も示している：description が「[動詞] [何をするか]. Use when [トリガーシナリオ]」という構文を採用している Skill は、平均検出欠陥数が 1.83 個であるのに対し、「仕様を意識しない」書き方では平均 3.00 個で、Cliff's δ = −0.40 は中程度の効果量に属する。つまり、テンプレートに従って description を書くことは、定量的に検証可能な品質上の利益であり、スタイルの好みではない。さらに、AI 生成とラベル付けされた Skill と未ラベルのものは品質分布にも差があり、ラベリングと人手によるレビューには依然として価値があることを示している。

以下の Python 検証スクリプトはそのまま CI に組み込むことができ、上記のすべてのハード制約と二段構文のパターンを一通りチェックできる：

import os
import re
import sys

NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
TRIGGER_HINT = ("use when", "when the user", "当用户", "当任务")

def parse_frontmatter(text):
    if not text.startswith("---"):
        raise ValueError("SKILL.md 必须以 YAML frontmatter 开头")
    parts = text.split("---", 2)
    if len(parts)  3:
        raise ValueError("frontmatter 未正确闭合")
    meta = {}
    for line in parts[1].strip().splitlines():
        if ":" in line:
            key, value = line.split(":", 1)
            meta[key.strip()] = value.strip()
    return meta, parts[2]

def validate(skill_path):
    errors = []
    skill_dir = os.path.dirname(os.path.abspath(skill_path))
    dir_name = os.path.basename(skill_dir)
    meta, body = parse_frontmatter(open(skill_path, encoding="utf-8").read())

    name = meta.get("name", "")
    desc = meta.get("description", "")

    if not name:
        errors.append("缺少必填字段 name")
    else:
        if len(name) > 64:
            errors.append("name 超过 64 字符")
        if not NAME_RE.match(name):
            errors.append("name 只允许小写字母/数字/连字符，且不能首尾为连字符")
        if name != dir_name:
            errors.append(f"name({name}) 与父目录名({dir_name}) 不一致")

    if not desc:
        errors.append("缺少必填字段 description")
    else:
        if len(desc) > 1024:
            errors.append("description 超过 1024 字符")
        full = (desc + body).lower()
        if not any(hint in full for hint in TRIGGER_HINT):
            errors.append("description 未体现触发场景，建议写成「[动词] [做什么]. Use when [触发场景]」")

    return errors

if __name__ == "__main__":
    issues = validate(sys.argv[1])
    if issues:
        print("校验未通过：")
        for item in issues:
            print(" - " + item)
        sys.exit(1)
    print("校验通过")

このスクリプトは、頻出する4つの失敗ポイントをカバーしています：name の長さと文字セット、name が親ディレクトリと同名、description の長さ、そして「何をするか + いつ使うか」の2段式の文型が欠けていないか、です。これを CI に組み込めば、後から人の目で review するよりはるかに信頼できます。

25+ プラットフォーム互換マトリクスとデフォルトのインストールディレクトリ：.claude/skills/、.cursor/skills/、.agents/skills/、.windsurf/skills/

互換プラットフォームの一覧をまずすべて挙げます：Claude Code、Claude.ai、Cursor、OpenAI Codex、VS Code / GitHub Copilot、Windsurf、Gemini CLI、Amp、Roo Code、Goose、Cline、OpenCode、TRAE、Kiro、JetBrains、OpenHands、Replit、Factory、Manus、Zed、Qodo、Letta、Mistral Vibe、Agentman、VT Code、Piebald。同じ SKILL.md をコピーするだけでそのまま使え、プラットフォームごとに内容を書き換える必要はありません。

プロジェクトレベルとユーザーレベルの違いに注意してください：プロジェクトレベルのディレクトリ（.claude/skills/ など）は git でコミットされるため、チームメンバーが pull すると自動的に同じ Skill 一式を取得できます。ユーザーレベルのディレクトリ（~/.claude/skills/ など）は現在のユーザーにのみ有効で、個人の好みに関する Skill を置くのに適しています。**よくある落とし穴：**プロジェクト内にプロジェクトレベルとユーザーレベルで同名の Skill を同時に置いた場合、対象プラットフォームの優先順位の取り決めを確認し、「Skill を更新したはずなのに反映されていないようだ」という事態を避けてください。Claude Code 側には検証用のエントリポイントも用意されています：claude plugin validate で構造の正当性をチェックできるので、コミット前に一度実行することをおすすめします。

また特筆すべきは Claude Code の最新の変更です：Skill とスラッシュコマンドはすでに同一のシステムに統合されています——.claude/commands/review.md と .claude/skills/review/SKILL.md はどちらも /review を生成し、同名の場合は Skill が優先され、Skill は付随ファイルとより多くの frontmatter フィールドをサポートします。オープン標準のフィールド（name / description / license / compatibility / metadata / allowed-tools）に加えて、Claude Code はさらに一連の拡張フィールドを提供しています：allowed-tools（ツールのホワイトリスト）、model（モデルの指定）、context: fork（独立したコンテキストの派生）、agent（サブエージェントの指定）、user-invocable、disable-model-invocation、argument-hint、そして hooks ライフサイクルフック（PreToolUse / PostToolUse / Stop）。これらの拡張フィールドは SKILL.md のポータビリティを変えません。なぜなら他のプラットフォームは認識しないオプションフィールドを無視するからですが、Claude Code の中ではよりきめ細かな制御を可能にします。

ここまでで、あなたは Skill の定義、標準の進化、ディレクトリ構造、フィールド制約、記述例、インストールパスをすでに習得しました。しかし、ある Skill ライブラリが長期的に保守できるかどうかを本当に決めるのは、フォーマットではなく Token 予算です——次のセクションでは、プログレッシブローディングの三層の台帳に入り、各層がどれだけの token を使うべきかを明確に計算し、さらに Skill と MCP の境界を比較し、六つの頻出 FAQ に答え、公式の四つのベストプラクティスとコミュニティの第二波の実践テーマ——Skill ライブラリの監査、剪定、再構築——を確定します。

前のセクションでは、SKILL.md のディレクトリ構造、frontmatter フィールドの仕様、クロスプラットフォームのインストールパスを一つずつ分解し、最初の Skill の四段階の作成プロセスも実際に走らせました。この部分では、視点を実行時の「台帳」に切り替えます：Agent は一体どの時点でどれだけの token を読むのか、なぜ 25+ のプラットフォームが同じファイルをこれほど軽く使えるのか、そして 2026 年のエコシステムに最新で現れたエンジニアリング規律と検証手段とは何か。

プログレッシブローディングの三層と Token 台帳：メタデータは約 100 tokens、本文は 5000 tokens 以下を推奨、リソースはほぼ上限なし

Skill がコンテキストを圧迫することなくどんどん増やせるのは、圧縮ではなくプログレッシブ・ディスクロージャー（progressive disclosure）というローディング機構によるものです。これは一つの Skill を、異なるタイミングと異なるコストを持つ三つの層に分割します：起動時には「カタログ」だけを読み、トリガーされたときに「本文」を読み、本文で名指しされたものだけが「リソース」を読むのです。

重要なエンジニアリング上の含意は三つある。第一に、起動コストは Skill の数に対してほぼ線形だが極めて低い——40 個の Skill を入れても消費するのは約 4000 tokens のメタデータ予算だけで、モデルの context に対する知覚はほとんど影響を受けない。第二に、本文こそが真のコストセンターである。それは Skill がトリガーされた瞬間にコンテキストへどれだけ余分な文字を詰め込む必要があるかを決めるため、5000 tokens は能動的に守るべきレッドラインである。第三に、第三層の「上限なし」は無料の昼食ではない。上限がない前提はプリロードしないことにある——スクリプトと参照ドキュメントは参照されて初めてコンテキストに入る。これはつまり、SKILL.md の本文に「X のシナリオに遭遇したら references/Y.md を読む」と明確に書かなければ、モデルはそれらのファイルが存在することすら知らないということでもある。

よくある落とし穴はこれだ。PDF 解析の完全な API ドキュメントや、会社の数十ページにわたるコーディング規約の全文を SKILL.md の本文に貼り付けてしまう。その結果、この Skill がトリガーされるたびに、ごく少数のタスクでしか使わない知識のために 8000 tokens の固定税を払うことになる。正しいやり方は、それらを references/ に落とし、本文では一行のリンクで指し示すことだ。

Skill と MCP の五次元対照表：指示と知識 vs 外部ツール接続、そして両者の組み合わせ方

Skill が登場してから最もよく聞かれる質問は「それは MCP を置き換えるのか」である。答えは否だ——両者はまったく異なる二種類のエンジニアリング問題を解決する。

両者は補完関係にあり、多くの実際のワークフローは両方を同時に使う。MCP は BigQuery への接続を担当し、Skill は Agent に「データを照会するときはまず時間パーティションを確認し、次に業務定義でフィルタし、最後にどのテンプレートでレポートを出力するか」を伝える役割を担う。さらに Skill は完全修飾名で MCP ツールを参照できる。たとえば本文に「データ照合段階で BigQuery:query を呼び出して基礎テーブルを取得する」と書けば、同じ Agent が一度のタスクで知識層とツール層をつなぐことができる。

これこそが Skill の移植性がこれほど重要な理由である。「財務モデリングのやり方」を記述した Skill は、claude.ai、Claude Code、API の三つの入口で一貫した挙動を示すべきであり、その前提は実行環境が宣言した依存関係を満たしていることだけである。ツール側で MCP 実装を変えても、通常は Skill 本文のロジックには影響しない。

13.8 万件の SKILL.md の欠陥研究：Tier 1 仕様適合性と Tier 2 ベストプラクティス適合性

Skill が少数の人が書くものから数十万人が書くものになると、品質問題はもはや個人のスタイルの問題ではなく、測定可能なコーパス問題となる。2026 年 8 月の arXiv 論文「What Keeps Agent Skills from Being Reusable?」は 138,133 件の公開 SKILL.md を分析し、欠陥を二種類に分類した：

• Tier 1「仕様準拠性」：全14項目のチェックで、open standard が明確に規定するハード制約に対応します。たとえば name の長さと文字セット、親ディレクトリと一致するか、description が長すぎないかなどです。
• Tier 2「ベストプラクティス準拠性」：全17項目のチェックで、公式およびコミュニティがまとめた記述上の推奨に対応します。たとえばトリガーとなるシナリオが含まれているか、本文が長すぎないか、リソース参照が明確かなどです。

論文の中心的な発見の一つは、仕様準拠性の欠陥が公開コーパスで支配的であるという点です。つまり、多くの Skill が「安定的に発見される」という関門すら通過していません。さらにエンジニアリングチームが警戒すべきなのはルーティング（トリガー）系の欠陥です。description が曖昧に書かれ、何をするのかも、いつ使うのかも説明されていないと、Agent のマッチングは不正確になります。Skill 自体は非常に詳細に書かれていても、ほとんど起動されず、最終的に「発見される品質」が直接引き下げられます。これは、前段で強調した「description はあらゆる Skill の中で最も重要な部分である」という点と実証的に呼応しています。

description の文型による定量化された効果：[動詞] [何をする]. Use when [トリガーシナリオ] は平均欠陥 1.83 対 3.00

論文で最も広く共有されたデータは文型の比較から来ています。研究者は description の書き方を二つに分類しました。一つは「[動詞] [何をする]. Use when [トリガーシナリオ]」という構造化テンプレートを採用するもの、もう一つは「仕様を意識しない」自由な書き方です。統計結果は次のとおりです：

• テンプレート文型を採用した Skill は、平均検出欠陥 1.83 個；
• 仕様を意識しない書き方は、平均検出欠陥 3.00 個；
• 効果量 Cliff’s δ = −0.40、中程度の効果量。

言い換えれば、テンプレートに従って description を書くことは、定量的に検証可能な品質上の利益であり、美的嗜好ではありません。チームにとって、これは文型をコードレビューのチェックリストに入れることが割に合うことを意味します。それは「description がうまく書けているか」を主観的判断から自動チェック可能なルールへと変えるからです。論文はまた、AI 生成とラベル付けされた Skill と未ラベルのものでは品質分布に差があることにも言及しています。これは、Skill を自動生成するチームこそ、モデルが一発で仕上げることに頼るのではなく、明示的な検証ツールをより必要としていることを示唆しています。

以下は CI でそのまま実行できる検証スクリプトで、Tier 1 の中で最も見落とされやすい三種類をチェックします。name の長さと文字セット、name が親ディレクトリと同名か、description の長さと「何をする + いつ使う」の二段構成です。

#!/usr/bin/env python3
"""validate_skill.py — CI で SKILL.md の Tier 1 仕様準拠性を検証する"""
import re
import sys
from pathlib import Path

import yaml  # pip install pyyaml

NAME_MAX = 64
DESC_MAX = 1024
WHEN_RE = re.compile(r"(use when|when to use|何时使用|适用于)", re.IGNORECASE)


def fail(msg: str) -> None:
    print(f"[FAIL] {msg}")
    sys.exit(1)


def load_frontmatter(skill_md: Path) -> dict:
    text = skill_md.read_text(encoding="utf-8")
    if not text.startswith("---"):
        fail("SKILL.md は YAML frontmatter の区切り文字 '---' で始まる必要があります")
    _, fm, _ = text.split("---", 2)
    return yaml.safe_load(fm) or {}


def check(skill_md: Path) -> None:
    fm = load_frontmatter(skill_md)
    name = fm.get("name", "")
    desc = fm.get("description", "")

    # 1) name の長さと文字セット
    if not isinstance(name, str) or not name:
        fail("name は必須で、文字列でなければなりません")
    if len(name) > NAME_MAX:
        fail(f"name が長すぎます：{len(name)} > {NAME_MAX}")
    if not re.fullmatch(r"[a-z0-9-]+", name):
        fail("name には小文字、数字、ハイフンのみ使用できます")
    if name.startswith("-") or name.endswith("-") or "--" in name:
        fail("name はハイフンで始めたり終えたりできず、連続ハイフンも許可されません")

    # 2) name は親ディレクトリと同名でなければならない
    parent = skill_md.parent.name
    if name != parent:
        fail(f"name({name}) は親ディレクトリ名({parent}) と一致する必要があります")

    # 3) description の長さ + 二段構成
    if not isinstance(desc, str) or not desc.strip():
        fail("description は必須です")
    if len(desc) > DESC_MAX:
        fail(f"description が長すぎます：{len(desc)} > {DESC_MAX}")
    if not WHEN_RE.search(desc):
        fail("description にトリガーシナリオの説明がありません。'[動詞][何をする]. Use when [シナリオ]' の文型を推奨します")
    if len(desc.strip()) < 20:
        fail("description が短すぎて、信頼できるルーティング判断をほぼ支えられません")

    print(f"[OK] {name}: name={len(name)} chars, description={len(desc)} chars")


if __name__ == "__main__":
    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path(".")
    md = target / "SKILL.md" if target.is_dir() else target
    check(md)

このスクリプトを pre-commit や PR チェックに組み込めば、マージ前に最も安価で最も致命的ないくつかの種類のエラーを食い止められる。ただし、意図的に機械的に判定可能なチェックのみを行っている点に注意してほしい。意味論的な「この作業をそもそも Skill に任せるべきか」は依然として人間の判断に委ねられる。

token 予算の規律とよくある誤解：コンテキストを公共資源として扱い、コミュニティの閾値は公式より保守的

公式が示す 5000 tokens は上限であり、目標ではない。真に成熟したチームはコンテキストウィンドウを公共資源として管理する。各 Skill はこの共通予算から一部を分け取り、どんな内容を書き込んでも、それは他の Skill と現在のタスク自体に対して課金していることになる。だからこそ、書くたびに次の三つを自問する価値がある：

1. モデルはタスクを完了するために本当にこの情報を必要とするか？
2. 訓練で既に学んでいると合理的に仮定できるか？
3. この内容の token コストは元が取れるか？

コミュニティのツールはこれを踏まえ、公式より保守的な参考閾値を示しており、内部規範のデフォルト値として採用する価値がある：

• 第一層 name + description：目標 < 200 文字 / < 30 tokens；
• 第二層の本文：目標 < 50 行 / < 1,000 語 / < 680 tokens。

典型的な誤解はいくつかある：「出力例」を丸ごと本文に貼り付ける（references/ に落とすべき）；互いに排他的なシナリオを同じ Skill に詰め込む（例えばコードレビューとコード生成を同時に教えると、description が正確にルーティングできなくなる）；スクリプトが「読む」ものか「実行する」ものかを明記しない（モデルが、読むべき参考実装を実行可能なコマンドとみなす可能性がある）；そして「モデルなら分かるはず」という暗黙知に過度に依存し、結果としてトリガー後もなお重要なコンテキストが欠ける、などである。

Claude Code の最新実践：Skill とスラッシュコマンドの統一、拡張フィールド、hooks、claude plugin validate

2026 年の Claude Code は Skill とスラッシュコマンドを同一のシステムに統合した：.claude/commands/review.md と .claude/skills/review/SKILL.md はどちらも /review を生成する；両者が同名の場合、Skill が優先される。Skill は付随ファイルとより豊富な frontmatter フィールドをサポートするからだ。オープン標準のフィールド（name / description / license / compatibility / metadata / allowed-tools）に加えて、Claude Code はいくつかの拡張フィールドとライフサイクルフックを提供している：

• allowed-tools：ツールのホワイトリストで、この Skill が呼び出せるツールの範囲を限定する；
• model：この Skill にモデルを指定する；
• context: fork：独立したコンテキストを派生させ、メインの会話を汚染しない；
• agent：タスクを引き受けるサブエージェントを指定する；
• user-invocable と disable-model-invocation：ユーザーが明示的に呼び出すか、それともモデルによる自動起動を禁止するかを制御する；
• argument-hint：スラッシュコマンドの引数のヒント；
• hooks：PreToolUse / PostToolUse / Stop の三つのライフサイクルフックで、ツール呼び出しの前後と終了点に検証やログを挿入するために用いる。

構造レベルでは claude plugin validate で検証でき、フィールドのスペルミスやディレクトリ構成などの初歩的なミスを提出前に防げます。以下は、すべての frontmatter フィールドを含む SKILL.md の例で、そのままテンプレートとして使えます。

---
name: pdf-processing
description: Extract structured data from PDF documents and fill in forms. Use when the user provides a PDF and asks for text extraction, table parsing, or form completion.
license: Apache-2.0
compatibility: Requires Python 3.10+, pdfplumber and pypdf installed, host agent supporting the agentskills.io standard.
metadata:
  author: data-platform-team
  version: 1.3.0
  homepage: https://example.internal/skills/pdf-processing
allowed-tools:
  - Read
  - Bash
  - Write
---

# PDF Processing

## Quick start

Use pdfplumber to extract text page by page, then normalize whitespace.

```python
import pdfplumber

with pdfplumber.open("input.pdf") as pdf:
    for page in pdf.pages:
        print(page.extract_text() or "")
```

## Advanced features

- Form filling and AcroForm handling: see [FORMS.md](references/FORMS.md)
- Table extraction edge cases: see [TABLES.md](references/TABLES.md)
- When the user asks to *run* a batch job, execute exactly one script:
  `scripts/batch_extract.py` — do not treat the snippets above as runnable files.

## When to use

- The user uploads a PDF and asks for its contents.
- The user needs specific fields pulled from a filled form.

## Process

1. Confirm the PDF path and whether forms or plain text are needed.
2. Extract text with pdfplumber; fall back to pypdf for encrypted files.
3. Validate extracted fields against the requested schema.
4. Return results plus any pages that failed, with the reason.

Microsoft Agent Framework の四段階開示：Advertise、Load、read_skill_resource、run_skill_script

Microsoft Agent Framework は、より細粒度な「四段階」の漸進的開示という表現を採用しており、学界でよく言われる三層を、よりランタイムの動作に近い形に分解しています：

1. Advertise：約 100 tokens/Skill で、名前と説明をシステムプロンプトに注入し、Agent に能力一覧を認識させます；
2. Load：タスクがマッチした際に load_skill ツールを通じて完全な SKILL.md を取得し、公式の推奨は < 5,000 tokens です；
3. read_skill_resource：リソースファイルを読み取る独立した動作；
4. run_skill_script：スクリプトを実行する独立した動作。

「リソースの読み取り」と「スクリプトの実行」を二つの独立した動作としてモデル化することは、安全性と可観測性にとって非常に重要な設計です——参考ドキュメントを読むこととコードを走らせることではリスクレベルが全く異なり、監査時にも別々に記録すべきです。このフレームワークは同時に四種類の Skill ソースをサポートします：ファイル型（ディレクトリ内の SKILL.md）、コード定義型、クラス定義型、そしてMCP ベース型です。前三者は静的な配布に傾き、最後のものは Skill をサーバーが動的に提供できるオブジェクトに変え、企業内での集中ホスティングやカナリアリリースに適しています。

公式のベストプラクティスと設計原則：評価から始める、規模のために構造化する、モデルの視点に立つ、モデルとともに反復する

公式に示された四つのベストプラクティスは、本質的には一連の反復方法論です：

1. 評価から始める：まず実際のタスクで走らせ、Agent がどこで詰まり、どのようなコンテキストを欠いているかを観察してから、漸進的に Skill を作るのであり、最初に完璧な知識体系を設計するのではありません；
2. 規模のために構造化する：SKILL.md が肥大化したら独立したファイルに分割して参照し、本文は約 5k 語以内に抑え、相互排他的なシナリオを分け、スクリプトが「読む」ためのものか「走らせる」ためのものかを明確に書き分けます；
3. モデルの視点に立つ：name と description がトリガーを決めるため、実際の使用トレースを観察すべきであり、呼び出されるかどうかを仮定で判断してはいけません；
4. モデルとともに反復する：成功したやり方とよくある落とし穴を Skill に還元し、実践とともに進化させます。

三つの設計原則がこれに伴います：漸進的開示（token 使用量の最小化）、組み合わせ可能性（複数の Skill が同時にロードされるため、自分が能力を独占していると仮定してはいけません）、ポータビリティ（同じ Skill が claude.ai / Claude Code / API で一貫して動作すること、ただしランタイム環境がその依存関係を満たすことが前提です）。組み合わせ可能性は特に見落とされがちです：ある Skill が本文で「本 Agent は X のみを担当する」と断言すると、他の Skill と共存する際に衝突を生みます；より良い書き方は、境界を前提条件とチェック手順として書くことです。

キッチンのアナロジーとエコシステムのシグナル：MCP がキッチン、Skill がレシピ、そして到来しつつある監査と剪定の第二波

公式ドキュメントは非常に的確な比喩を用いている：MCP が提供するのは「プロの厨房」——ツール、食材、設備であり、Skill が提供するのは「レシピ」——それらの食材をどのように価値あるものに仕上げるかである。MCP があっても Skill がなければ、ユーザーはコネクタに接続した後も次に何をすべきか分からず、毎回のセッションがゼロから始まり、結果は一貫せず、最終的にはコネクタのせいにされてしまう。この帰属の誤りは実務では非常に一般的である：チームはツールが使いにくいと思い込んでいるが、実際にはツールをフローに組み込む知識層が欠けているのだ。

エコシステムの面では、Simon Willison のような初期の評論家が Agent Skills を「MCP よりも大きい」と評した——MCP を置き換えるからではなく、別の問題を解決するからである：Agent にただツールを与えるのではなく、仕事をうまくこなす方法を教えることだ。2026年後半には、以前インストールした Skill ライブラリの監査、剪定、再構築をテーマとする明確な第二波の実践が現れている：チームはどの Skill が一度も発火していないか（description ルーティングの失敗）、どの本文が長すぎるか（token 予算の暴走）、どのフィールドが新しいプラットフォームの仕様と互換性がなくなったかを棚卸しし始めている。これは先の13.8万件のコーパス研究の結論と一致する——規模が大きくなると、ガバナンスは創作よりも希少になる。

六つの質問で早わかり FAQ：プログラミングは必要か、Claude/Cursor/Codex をまたいで使えるか、システムプロンプトとの違い、いくつインストールするか、どんなものを作れるか、どこで見つけるか

• Skill の作成にプログラミングは必要ですか？不要です。それはただの Markdown ファイルで、文章が書ければ作成できます——SDK もビルド手順もデプロイ工程もありません。本文がスクリプトを参照する場合にのみ、そのスクリプトを誰かが書く必要があります。
• 同じ Skill は Claude、Cursor、OpenAI Codex で使えますか？使えます。SKILL.md は Anthropic が提唱し agentskills.io で公開されたオープン標準で、2026年には32のプラットフォームが同じフォーマットを採用しています。同じフォルダを各ツールの skills ディレクトリにコピーするだけです。
• Skill とシステムプロンプトの違いは何ですか？システムプロンプトは常に読み込まれる静的な指示ブロックです。Skill はオンデマンドで読み込まれる構造化パッケージで、タスクに関連するときだけ本文が読み込まれ、複数の Skill が共存でき、context の消費もごくわずかです。
• Skill はいくつインストールできますか？いくつでもインストールできます——起動時には各 Skill が約100トークンのメタデータのみを読み込むため、数十個インストールしても影響はごくわずかです。
• どんな種類の Skill を作成できますか？技術系（コードレビュー、PDF 処理、テスト）、プロセス系（データベース移行、デプロイ）、ペルソナ系（同僚、著名人、歴史上の人物）のいずれも可能です。
• インストール可能な Skill はどこで見つけられますか？Skill ライブラリ、GitHub、あるいはゼロから自分で作成することもできます。

まとめとベストプラクティス

これら二つの部分の内容を実行可能なチェックリストに圧縮する：

1. まず評価し、その後で Skill を作る。実際のタスクで Agent がどこで詰まるかを観察し、この Skill がどのコンテキストを補うべきかを決める。
2. description をインターフェースとして書く。「[動詞] [何をするか]. Use when [発火シナリオ]」という構文を使うと、平均欠陥を3.00から1.83に減らせることが実証されている。これは同時に、Agent があなたを起動するかどうかも決める。
3. Tier 1 のハード制約を守る。name ≤ 64文字、小文字英字/数字/ハイフンのみ、親ディレクトリと同名、連続ハイフンなし、ハイフンで始まらない・終わらない；description ≤ 1024文字で「何をするか」と「いつ使うか」の両方に答える。検証スクリプトを CI に組み込む。
4. 三層読み込みで token 予算を管理する。メタデータは約100トークン/Skill で常駐；本文は < 5000トークンを推奨、コミュニティのより保守的な目標は < 50行 / < 1000語 / < 680トークン；リソースはオンデマンドで読み込まれ、ほぼ上限がない。
5. 本文のスリム化は下方への移設で行う。長い文書、テンプレート、schema は references/ と assets/ に置き、本文には一行の参照だけを残す；そしてスクリプトが「読む」ものか「実行する」ものかを明確に書く。
6. 規模に応じて分割する。SKILL.md が肥大化したらファイルを分割し、相互排他的なシナリオは別々の Skill に分け、一つの Skill に矛盾する発火条件を負わせない。
7. 組み合わせ可能で移植可能に保つ。独占的な能力を前提とせず、特定のホスト固有の挙動を本文にハードコードしない；同じ Skill は claude.ai / Claude Code / API で一貫して動作すべきである。
8. プラットフォームの拡張機能を活用する。Claude Code では allowed-tools、model、context: fork、agent、user-invocable、argument-hint、および PreToolUse/PostToolUse/Stop フックを利用でき、claude plugin validate で構造を検証できる。
9. 新旧の役割分担を認識する。MCP は厨房を、Skill はレシピを与える；Skill は BigQuery:query のような完全修飾名で MCP ツールを参照し、同じ Agent 内で協調できる。
10. 定期的に Skill ライブラリを監査する。どれが一度も発火していないか、どれの本文が予算超過か、どのフィールドが古くなっているかを確認する；成功したやり方と落とし穴を Skill に書き戻し、反復のループを形成する。