Agent Skills が Agentic AI Foundation へ: インストールする SKILL.md で何が変わるか、バージョン管理が始まるまでにすべきこと

Anthropic は Agent Skills を Agentic AI Foundation に移管しました。この財団は、Anthropic が昨年 12 月に Block、OpenAI と共同で立ち上げた Linux Foundation のプロジェクトです。発表は 10 月 22 日に出されました。移管の対象は名称とロゴ、GitHub の組織、agentskills.io ドメインです。財団にはすでに MCP、Block のエージェント goose、OpenAI の AGENTS.md 規約が入っています。リードメンテナーは David Soria Parra と Mahesh Murag で、Anthropic、Google、OpenAI などのエンジニアが個人の立場で標準をメンテナンスします。発表によれば、スキルを読み込めるプラットフォームは 70 以上あります。

2 週間前のサプライチェーンの記事は、レジストリがないこと、バージョンがないことで締めくくりました。今回の寄贈は、今のところそのどちらにもほとんど効きません。以下では、寄贈で実際に何が変わるのか、そしてインストールする側がそれまでの間に何をできるのかを整理します。確認作業と出力はすべて手元のマシンのものです。Claude Code 2.1.309、codex-cli 0.163.0、Python 3.12.3 を使いました。

Agent Skills の寄贈で SKILL.md の何が変わるか

ファイルについては何も変わりません。スキルは今も、SKILL.md を含むフォルダーです。先頭に YAML フロントマター、その下に指示が書かれ、必要に応じて scripts/、references/、assets/ が隣に置かれます。追加・削除されたフィールドはなく、インストール済みのものに手を入れる必要もありません。

変わったのは、次のバージョンを誰が決めるかです。今週まで、仕様は Anthropic が運営し、外部のコントリビューターが参加するリポジトリでした。これからは複数企業のメンテナーグループを持つ財団のプロジェクトです。70 のクライアントが読み込む形式が、1 社のスケジュールで変わることはなくなります。ただし、今日あなたのディスク上では、それに何の価値もありません。

Agent Skills の仕様にピン留めできるバージョンはあるか

まだありません。発表によると、Anthropic はまずロードマップから始めることを提案しています。バージョン付きのリリース、正式な提案プロセス、そしてスキルを書く人とインストールする人のためのセキュリティガイダンスです。肝心なのは「提案」という言葉です。

リポジトリもそれを裏付けています。agentskills/agentskills にはタグもリリースもなく、執筆時点の最新コミットは 8 月 9 日です。自分のスキルが準拠していると言える「仕様 1.0」は存在しません。個々のスキルのバージョンも定義されていません。仕様に version フィールドはなく、あるのは metadata だけです。これは文字列キーと文字列値の自由なマップで、例として version: "1.0" が示されています。確認したクライアントのうち、これを使うものはありませんでした。スキル作者が自分のツールで使うことはできますが、それは作者がラベルを整えているだけで、頼れるピン留めではありません。

参照用のバリデーター自身も、本番向けではないと README で断っています。

This library is intended for demonstration purposes only. It is not meant to be used in production.

つまり、ここでは 3 つの別々のものが「バージョン」と呼ばれています。仕様にはバージョンがありません。スキルは metadata にラベルを持つことがあります。そして実際に実行する中身を特定するのは git のコミットです。そもそも git から来たものであれば、の話ですが。

コピーした SKILL.md は元からどこまでずれるか

かなり遠くまで、しかも静かにずれます。手元の ~/.claude/skills にある他者製のスキルの 1 つは、4 月に作ったただの git clone で、作者の 3 月 31 日のコミットのままでした。今日 fetch してみました。

SK=~/.claude/skills/<the-skill>
git -C "$SK" fetch -q origin
git -C "$SK" log --oneline HEAD..origin/main | wc -l
# 76
git -C "$SK" diff --stat HEAD origin/main | tail -1
# 14 files changed, 828 insertions(+), 558 deletions(-)

上流の最新コミットは 10 月 16 日です。この差分には、どのスキルを pull する前にも知っておきたい点が 4 つあります。

description が書き直されていました。Claude Code でも Codex でも、モデルはスキルを使う場面かどうかを description で判断します。つまり更新によって、スキルが発動した後の動作だけでなく、いつ発動するかも変わり得ます。

バージョンのラベルの場所が変わっていました。手元のコピーはフロントマターの最上位に version: 2.5.1 を宣言していますが、仕様にそのフィールドはありません。上流は現在、仕様の提案どおり metadata の下に version: "3.1.0" と書いています。同じスキルの 2 つのコピーが、ラベルを別々の場所に持っているわけです。

フォルダーが大きくなっていました。上流は今、.claude-plugin/plugin.json と marketplace.json、.cursor-plugin/plugin.json、Codex 用の agents/openai.yaml、AGENTS.md、それにパッケージを検査する Python スクリプトを同梱しています。Markdown ファイル 1 つだったスキルが、3 つのクライアント向けのパッケージングとコードを抱えるようになりました。

そして、そのうちの 1 ファイルが Claude Code によるフォルダーの扱いを変えます。ドキュメントによると、個人またはプロジェクトのスキルフォルダー内に .claude-plugin/plugin.json があると、Claude Code はそのフォルダーを <name>@skills-dir という名前のプラグインとして読み込みます。ドキュメントの言葉では「with its own agents, hooks, and MCP servers」、つまり独自のエージェント、フック、MCP サーバーを持てるプラグインです。つまり ~/.claude/skills で git pull するだけで、文章だけのスキルが、フックを登録できるプラグインに変わり得ます。この上流のマニフェストに載っているのはスキルだけで、リポジトリにフックや MCP の設定はありません。これは確認済みです。ただ、次の更新でもそうだとは限りません。

まず変更されたファイルの一覧をすべて読み、その後、実行されるもの、動作を左右するものの差分を読みます。

git -C "$SK" diff --name-status HEAD origin/main
git -C "$SK" diff HEAD origin/main -- SKILL.md scripts/ agents/ .claude-plugin/ AGENTS.md

他者の Agent Skill を今 Claude Code でピン留めする方法

コミットで固定します。有効な方法が 2 つと、そう見えるだけの方法が 1 つあります。

素朴な方法は、既知のコミットをチェックアウトした git clone です。エージェントがスキャンするフォルダーの外にクローンし、コミットをチェックアウトして中身を読み、それから初めてリンクします。Claude Code はスキルフォルダーを監視していて、セッションの途中でも新しいスキルを拾うからです。

git clone https://github.com/<owner>/<skill> ~/src/skills/<skill>
git -C ~/src/skills/<skill> checkout --detach <40-character-commit>
# read it, then:
ln -s ~/src/skills/<skill> ~/.claude/skills/<skill>

これがピン留めになるのは、コミットを記録し、意図して更新する場合だけです。

Claude Code でより強い方法は、スキルのリポジトリを sha で指す自前のプラグインマーケットプレイスです。マーケットプレイスのリファレンスは 40 文字の完全なコミットを受け付け、ref と sha の両方が指定されていれば Claude Code は sha をチェックアウトします。プレースホルダーを実在のリポジトリとコミットに置き換えると、このファイルは手元で claude plugin validate を通りました (マーケットプレイスの説明がないという警告が 1 件出ました)。

{
  "name": "pinned-skills",
  "owner": { "name": "me" },
  "plugins": [
    {
      "name": "<skill>",
      "source": {
        "source": "github",
        "repo": "<owner>/<skill>",
        "sha": "<40-character-commit>"
      }
    }
  ]
}

自分が管理するフォルダーかリポジトリに .claude-plugin/marketplace.json として置き、claude plugin marketplace add ./my-skills、続けて claude plugin install <skill>@pinned-skills を実行します。ファイルの検証はしましたが、インストールは実行していません。ソースには git-subdir (大きなリポジトリの 1 フォルダー。ref と sha のフィールドは同じ) や archive も使えます。archive は sha256 付きの zip で、リファレンスによれば、Claude Code はダウンロードしたファイルをこの sha256 と照合します。

3 つ目の方法が metadata.version です。ピン留めに見えますが、ただのラベルです。中身と照合するものは何もありません。

SKILL.md を Agent Skills の仕様に照らして検査する方法

仕様リポジトリにある参照ライブラリ skills-ref を使います。PyPI にもありますが、ルールを仕様の本文と一致させるため、読んでいたコミットのクローンからインストールしました。Python 3.11 以降が必要です。

git clone https://github.com/agentskills/agentskills
git -C agentskills checkout --detach 69ef37e9424c0a7ea9dd2293b559e43ec8176379
python3 -m venv .venv && .venv/bin/pip install ./agentskills/skills-ref
for d in ~/.claude/skills/*/; do .venv/bin/skills-ref validate "$d"; done

このループは一覧を出すためのもので、ゲートではありません。終了コードではなく出力を読んでください。手元のフォルダーでは、およそ 4 つに 1 つのスキルが不合格で、その大半は自分で書いたスキルでした。失敗は 3 種類です。

引用符なしのコロンを含む description。description: ... sibling: same CLI ... のような行は正しい YAML ではありません。パーサーは 2 つ目のコロンを新しいキーと解釈し、mapping values are not allowed here で止まります。description を引用符で囲むか、| ブロックを使います。

フロントマター最上位の version。バリデーターが許可するのは name、description、license、compatibility、metadata、allowed-tools だけで、それ以外はすべて拒否されます。

仕様の上限である 1,024 文字を超える description。

もう 1 つ、スキルではないのに不合格になった項目がありました。synced フォルダーです。claude.ai アカウントで有効にしたスキルを Claude Code が置く場所で、中にスキルはあっても、フォルダー自体はスキルではありません。ドキュメントは、ここでのローカル編集は次の同期で上書きされ得ると警告しています。つまり、あなたに加えて 2 人目の書き手がいるフォルダーです。

不合格になったスキルも、すべて Claude Code には表示され、セッション内で何も警告されません。Claude Code は、認識しないフロントマターのフィールドをエラーを報告せずに無視します (ドキュメントの表現では「without reporting an error」)。パースできない YAML については、スキルはメタデータが空のまま読み込まれる、とドキュメントにあります。「with empty metadata, so /skill-name still works but Claude can't match against your description」、つまり /skill-name は動くものの、Claude は description と照合できません。手で呼び出すスキルは動き続け、自動の発動だけが黙って死にます。厳格な経路は別のところにあります。claude.ai へのアップロード、Skills API、Anthropic の package_skill.py は、6 つ以外のフィールドがあるとハードエラーで止まります。「Claude Code で動く」は、スキルが通り得る最も弱いテストです。スキルを誰かに渡す前には、別のツールで使う自分自身に渡す場合も含めて、バリデーターを実行してください。

Claude Code と Codex は Agent Skills をどこで探すか

別々のフォルダーです。Claude Code は個人のスキルを ~/.claude/skills から、プロジェクトのスキルを起動ディレクトリとリポジトリルートまでの各親ディレクトリの .claude/skills から読みます。ほかにプラグイン、マネージド設定、--add-dir のディレクトリも対象です。スキルのページに .agents への言及はありません。Codex はユーザー用に ~/.agents/skills を、作業ディレクトリからリポジトリルートまでの .agents/skills を読み、さらに /etc/codex/skills と同梱のスキルを読みます。仕様のクライアントガイドは .agents/skills を「a widely-adopted convention for cross-client skill sharing」と呼び、クライアント独自のフォルダーと並べてスキャンすることを勧めています。Claude Code は、ドキュメントを見る限りそうしていません。

どちらのローダーもシンボリックリンクに対応すると明記しているので、スキルは 1 か所に置き、もう一方にリンクします。

mkdir -p ~/.agents/skills
ln -s ~/src/skills/<skill> ~/.agents/skills/<skill>

シンボリックリンクが解決するのは発見だけです。一方のクライアントしか理解しないフィールドは、もう一方には意味を持ちません。Codex は UI と呼び出しの設定を agents/openai.yaml から読み、Claude Code は追加の設定をフロントマターから読みます。先ほどのスキルは、このすき間を埋めるためにクライアントごとのマニフェストを同梱するに至りました。「1 つの形式」はその程度のものです。

Agent Skills のセキュリティガイダンスが最初に扱うべきこと

信頼の境界です。この点で、クライアントの考え方がすでに食い違っているからです。

仕様のクライアントガイドには、この件について段落が 1 つあります。プロジェクトレベルのスキルは信頼できないリポジトリから来る可能性があるので、クライアントはユーザーがフォルダーを信頼済みとしてから読み込むべきで、そうしないと新しいクローンがエージェントに黙って指示を注入できてしまう (「silently inject instructions」)、という内容です。一方、Claude Code のドキュメントは allowed-tools について次のように書いています。

Workspace trust doesn't gate this field. Claude Code applies a project skill's
allowed-tools even in a -p run in a folder you've never trusted.

この許可はスキルを呼び出したターンの間だけ有効で、上限でもありません。リストにないツールも、通常の権限のもとで呼び出せます。ドキュメントは、リポジトリにチェックインされたスキルの allowed-tools を、そこで Claude Code を実行する前に確認するよう勧め、リポジトリのスキルからこのフィールドを取り上げるマネージド設定を案内しています。クローンしたリポジトリの設定ファイルが何を実行できるかと同じ構図です。ファイルはクローンと一緒にやって来て、ヘッドレス実行は誰にも尋ねません。その一方で、仕様は allowed-tools を実験的なものとし、サポートは「may vary」としています。Codex のスキルのページはこのフィールドに触れていません。

筆者の見方では、唯一の権限フィールドがクライアントごとに違う意味を持つ共通形式こそ、セキュリティガイダンスが最初に決着をつけるべき点です。署名やハッシュでのピン留めも重要ですが、それが答えるのは「これはインストールするつもりだったファイルか」という問いです。未解決なのは、インストールされたファイルが何をしてよいのかであり、今日その答えは、どのエージェントがフォルダーを開いたかで変わります。

そのガイダンスができるまで、自分で書いていないスキルとの最初の 5 分間はこうなります。

S=path/to/skill
sed -n '1,/^---$/{p}' "$S/SKILL.md" | sed -n '2,$p'   # the whole front matter, allowed-tools included
find -H "$S" ! -name '*.md' ! -path '*/.git/*' \( -type f -o -type l \)   # files and links that are not prose
find -H "$S" \( -name '__pycache__' -o -name '*.pyc' \)   # caches next to code
ls "$S/.claude-plugin" 2>/dev/null                       # does it load as a plugin?
git -C "$S" log -1 --format='%H %ad' && git -C "$S" status --short   # the commit, and anything not in it

1 行だけ実行するなら、最後の行です。status が何か出力したら、実行されるのは信頼しているつもりのコミットではありません。

Agent Skills の仕様の変更を追う方法

ブログではなくリポジトリを見てください。仕様の変更は agentskills/agentskills へのプルリクエストとして入り、発表によれば、変更案へのフィードバックはプロジェクトの Discord で受け付けます。最初のタグ付きリリースが出た時点で、ロードマップは提案ではなくなります。

財団が形式を受け入れるのは、これが初めてではありません。MCP は日付付きの仕様バージョンを持つプロトコルとして、AGENTS.md はバージョンをまったく持たないファイル規約として入りました。スキルはその中間にあります。スキルはコードを同梱できるので規約以上のものですが、クライアントがどのバージョンの形式を実装しているかを示すものがまだないので、プロトコルには届きません。