Agent Skillsの公式リポジトリで2026年8月4日、仕様書を更新する2件のプルリクエスト（PR）がマージされた。スキルディレクトリには必須のSKILL.md以外の任意のファイルやディレクトリを含められることと、SKILL.mdのmetadataが文字列のキーと値からなるマッピングであることが明記された。いずれも新しい要件を追加したものではなく、既存の扱いを仕様書上で明確にした。

任意のファイルやディレクトリを同梱できると明記

従来の仕様書では、scripts/、references/、assets/を任意ディレクトリとして挙げていた。一方、それ以外のファイルやディレクトリも含められることは本文で明示しておらず、列挙された3つ以外もスキルディレクトリに置けるかどうかが分かりにくかった。PR #268は、公式仕様の「Optional directories」節の冒頭に次の一文を加えた。

A skill directory may contain any files and directories beyond the required SKILL.md. The conventions below are recommendations for organizing common types of content.

（意訳：スキルディレクトリには、必須のSKILL.md以外にも任意のファイルやディレクトリを含められる。以下の構成は、一般的な種類のコンテンツを整理するための推奨事項である。）

引用中の「以下の構成」とは、この3つのディレクトリを指す。scripts/はエージェントが実行できるコード、references/は必要に応じて読む追加文書、assets/はテンプレートや画像、データファイルなどの静的リソースを整理するためのディレクトリとして紹介されている。

PR #268によると、これら3つのディレクトリは要件ではなく推奨で、変更は許可されたディレクトリがこの3つに限られるとの誤読を防ぐことを目的としている。仕様書への追記により、スキルには用途に応じてほかのファイルやディレクトリも含められることが明確になった。

スキル作者は、用途に応じた別のディレクトリや補助ファイルも同梱できる。たとえば、公式のスキル評価ガイドでは、8月4日の変更以前から、評価ケースをevals/evals.jsonへ置く構成を例示していた。

なお、PR #268はスキルに含められるファイルの範囲を明らかにしたが、自動検出や読み込み、実行など、クライアント側の挙動までは規定していない。

metadataのキーと値は文字列と明記

PR #479は、SKILL.mdのYAMLフロントマターで使える任意フィールドmetadataについて、仕様書の概要表の説明を「文字列のキーから文字列の値へのマップ」に改めた。

仕様書には、metadataのキーと値を文字列に限定する詳細説明が以前からあった。しかし、同じページの概要表では値の型を明示せず、「⁠任意のキーと値のマッピング」とだけ説明していた。そのため、ネストしたオブジェクト、配列、真偽値、数値なども値に使えるように読めた。

Issue #474は、この不一致がクライアント間の互換性に影響すると指摘し、ネストしたメタデータを含むスキルを厳格なパーサーで読み込めない事例を挙げた。今回の変更により、概要表と詳細説明の内容がそろった。

たとえば、次のように値を文字列として記述する形式は仕様に沿う。

metadata:
  author: example-org
  version: "1.0"

一方、次のようなネストしたマッピングや配列は、YAMLとしては有効でも、Agent Skills仕様のmetadataには適合しない。

metadata:
  example-client:
    tags:
      - analysis
      - reporting

クライアント固有の情報をmetadataへ追加する場合も、キーと値には文字列を使う。仕様書は、意図しない衝突を避けるため、他と重複しにくいキー名を推奨している。