3 行まとめ
- 2026年10月22日、Anthropic は Agent Skills の仕様を Linux Foundation 傘下の Agentic AI Foundation(AAIF)に寄贈した。MCP に続く2つ目の寄贈で、
SKILL.mdの形式は特定のベンダーのものではなく、中立な標準として管理されることになった - 標準になったのを機に、個人開発の4リポジトリにある 27個のスキルを仕様のルールで機械的に検査した。すると 6個に YAML フロントマターがなく、Claude Code では本文の見出し1行(
write-articleなど)が説明文として使われていた - Claude Code はフロントマターがなくても動くので、これまで気づかなかった。ただ、説明文はスキルを自動で呼ぶかどうかの判断材料で、claude.ai や Skills API ではフロントマターの扱いがずっと厳しい。仕様に寄せておく価値はある
何が発表されたか
Anthropic のニュース(10月22日付け)で、Agent Skills を AAIF に寄贈すると発表された。
寄贈の対象は次の4つだ。
- Agent Skills のオープン標準(仕様)
- Agent Skills の名称とロゴ
- GitHub の organization
-
agentskills.ioのドメイン
AAIF は、Anthropic が Block・OpenAI と共同で立ち上げた Linux Foundation 傘下の財団で、MCP もここに寄贈されている。発表では、Agent Skills は「open, community-driven, and vendor-neutral」であり続けるとしている。メンテナは、Anthropic・Google・OpenAI などのエンジニアが個人の立場で務める。
最初のロードマップとして挙がっているのは3つだ。
- バージョン付きのリリース
- 正式な提案プロセス
- スキルを書く人・入れる人向けのセキュリティガイダンス
仕様そのものの変更は、今回の発表には含まれていない。普及状況としては、2025年12月の標準公開から70以上のエージェントプラットフォームが取り込んでいる(ChatGPT、Cursor、GitHub Copilot、VS Code など)。公開されたスキルは100万、インストールは約2億8000万にのぼるという。
仕様の本体は、agentskills.io と GitHub で公開されている。
仕様のおさらい:SKILL.md に何が必須か
スキルは、SKILL.md を含むディレクトリだ。SKILL.md は YAML フロントマターと Markdown 本文でできている。
skill-name/
├── SKILL.md # 必須: メタデータ + 手順
├── scripts/ # 任意: 実行するコード
├── references/ # 任意: 必要なときに読むドキュメント
└── assets/ # 任意: テンプレートや画像
フロントマターで定義されているフィールドは6つだけだ。
| フィールド | 必須 | 制約 |
|---|---|---|
name |
○ | 64文字以内。小文字英数字とハイフンのみ。先頭・末尾のハイフン、連続ハイフン(--)は不可。親ディレクトリ名と一致すること
|
description |
○ | 1〜1024文字。何をするスキルか、いつ使うかを書く |
license |
ライセンス名か、同梱したライセンスファイルへの参照 | |
compatibility |
500文字以内。必要な環境(対象プロダクト、パッケージ、ネットワークなど) | |
metadata |
文字列から文字列への任意のマップ | |
allowed-tools |
事前に許可するツールのスペース区切り(実験的) |
本文には形式上の制限はない。ただ「Progressive disclosure」の節で、ロードの段階が整理されている。
-
メタデータ(約100トークン): 全スキルの
nameとdescriptionが起動時に読み込まれる -
手順(5000トークン未満を推奨): スキルが有効になったとき、
SKILL.mdの本文全体が読み込まれる -
リソース(必要に応じて):
scripts/やreferences/のファイルは必要なときだけ読む
そのうえで、SKILL.md は500行以内に収め、詳しい資料は別ファイルに分けるよう勧めている。
つまり、エージェントが「このスキルを使うべきか」を判断する材料は、起動時に読み込まれる name と description だけ ということになる。
手持ちの27スキルを検査する
公式のバリデータ skills-ref が GitHub で公開されている(README には「demonstration purposes only」とある)。今回はこれを実行するのではなく、validator.py を読んでルールを確認し、同じ判定をする小さなスクリプトを書いた。
validator.py を読むと、公式の判定には仕様の本文から読み取りにくい点が2つあった。
-
仕様の6つ以外のフィールドがあるとエラーになる(
ALLOWED_FIELDS以外はUnexpected fields in frontmatter) - 名前の文字種は、NFKC 正規化のあと
c.isalnum() or c == "-"で判定していて、Unicode の文字も通る(docstring にも「i18n characters」とある)。仕様本文は「unicode lowercase alphanumeric characters (a-z,0-9)」という曖昧な書き方で、validator はこれを Unicode 許容として実装している
手元のスクリプトは、例に挙がっている [a-z0-9-] だけを許可した。また、500行は仕様では推奨値で validator も見ていないが、ここでは NG として数えている。
"""Agent Skills 仕様の frontmatter ルールを手元で検査する簡易チェッカー
(agentskills.io/specification と skills-ref/validator.py のルールを再現)"""
import re
import sys
from pathlib import Path
import yaml # PyYAML
ALLOWED_FIELDS = {"name", "description", "license", "allowed-tools", "metadata", "compatibility"}
NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
def split_frontmatter(text: str) -> tuple[dict | None, str]:
if not text.startswith("---\n"):
return None, text
_, fm, body = text.split("---\n", 2)
return (yaml.safe_load(fm) or {}), body
def effective_description(meta: dict | None, body: str) -> str:
"""Claude Code が一覧に出す説明文: description がなければ本文の最初の空でない行"""
if meta and meta.get("description"):
return str(meta["description"])
first = next((ln for ln in body.splitlines() if ln.strip()), "")
return first.lstrip("#").strip()
def check(skill_md: Path) -> tuple[list[str], str]:
text = skill_md.read_text(encoding="utf-8")
meta, body = split_frontmatter(text)
desc = effective_description(meta, body)
if meta is None:
return ["frontmatter がない"], desc
errors = []
extra = set(meta) - ALLOWED_FIELDS
if extra:
errors.append(f"仕様外のフィールド: {sorted(extra)}")
name = meta.get("name")
if not name:
errors.append("name がない")
else:
if len(name) > 64:
errors.append(f"name が64文字超 ({len(name)})")
if not NAME_RE.match(name):
errors.append(f"name の文字種/ハイフン規則違反: {name}")
if name != skill_md.parent.name:
errors.append(f"name とディレクトリ名が不一致: {name} != {skill_md.parent.name}")
if not meta.get("description"):
errors.append("description がない")
elif len(meta["description"]) > 1024:
errors.append(f"description が1024文字超 ({len(meta['description'])})")
lines = text.count("\n") + 1
if lines > 500:
errors.append(f"SKILL.md が500行超 ({lines})")
return errors, desc
effective_description() は、Claude Code が実際にどんな説明文を使うかを再現するための関数だ(理由は後述)。
対象は、個人開発の4リポジトリの .claude/skills/ にあるスキルだ。この記事のリポジトリ、ツールサイト(ぱんだツールズ)、投資分析ツール、防災系の Web サービスの4つになる。出力は、リポジトリごとの見出しを足し、OK の行をまとめて見やすく整形している。
## panda-zenn(このリポジトリ)
[NG] review-article frontmatter がない
→ Claude Code が使う説明文: 'review-article'
[NG] write-article frontmatter がない
→ Claude Code が使う説明文: 'write-article'
## rakuscan(投資分析ツール)
[NG] analyze frontmatter がない
→ Claude Code が使う説明文: 'analyze — 個別銘柄の統合分析レポートを生成する'
[OK] code-review
[OK] create-plugin
[OK] manage-pr
[OK] memo
[OK] plan
[NG] portfolio frontmatter がない
→ Claude Code が使う説明文: 'portfolio — ポートフォリオ管理'
[NG] report frontmatter がない
→ Claude Code が使う説明文: 'report — 週次・月次レポートを生成する'
[OK] research
[NG] scan frontmatter がない
→ Claude Code が使う説明文: 'scan — 日次スクリーニング結果を解釈する'
## (防災系Webサービス)
[OK] add-pref / code-review / deploy-dynamic / layout-check / manage-pr / plan
## sakutto-tools(ツールサイト)
[OK] add-guide / add-tool / code-review / layout-check / manage-pr / memo / plan /
plan-tool / review-guide / update-ai-cli-commands / update-arch /
update-cloud-service-map / update-plan
| リポジトリ | スキル数 | 不合格 |
|---|---|---|
| Zenn 記事(このリポジトリ) | 2 | 2 |
| 投資分析ツール | 10 | 4 |
| 防災系 Web サービス | 6 | 0 |
| ツールサイト | 13 | 0 |
| 合計 | 27 | 6 |
不合格の6個は、すべて「フロントマターがない」という同じ理由だった。逆に、フロントマターがある21個は全部合格した。名前とディレクトリ名は全部一致していて、仕様外のフィールドもなく、説明文の最長は170文字で上限の1024文字に余裕があった。500行を超える SKILL.md もなかった(最長は394行)。
フロントマターがないとどうなるか
Claude Code は、フロントマターがなくても動く。このリポジトリの記事執筆スキルも、フロントマターなしで何十本もの記事を書いてきた。だから気づかなかった。
Claude Code のドキュメントには、欠けたときの扱いが書かれている。
-
nameがなければ、ディレクトリ名 を使う -
descriptionがなければ、Markdown 本文の最初の空でない行 を使う。ドキュメントはdescriptionについて「Claude uses this to decide when to apply the skill」と書いている。つまり自動で呼ぶかどうかの判断材料が、その1行になる
記事執筆スキルの SKILL.md は、こう始まっている。
# write-article
Zenn記事を書くスキル。対象PJTのコードや設計ドキュメントを読み込み、実態に即した技術記事を作成する。
最初の空でない行は # write-article なので、説明文は「write-article」になる。実際、このリポジトリで Claude Code を起動すると、モデルに渡されるスキル一覧にはこう出ている。
- review-article: review-article
- write-article: write-article
名前と説明が同じ文字列だ。見出しの次の段落に「Zenn記事を書くスキル」という立派な説明があるのに、それは一覧に載らない。エージェントは「write-article」という名前だけから中身を推測するしかない。
このリポジトリでは /write-article と明示して呼ぶ運用なので、実害は出ていなかった。しかし「記事を書いて」と頼んだときにエージェントが自分でこのスキルを選ぶかどうかは、ほぼ名前頼みになっていた。
この2つは、記事を書いたあとにフロントマターを足して直した。直した直後から、スキル一覧の表示は「write-article: 個人開発PJTのコードや設計ドキュメントを読み込み、実態に即したZenn記事を書いて…」に変わった。
投資分析ツールの4個は事情が少し違う。見出しが # scan — 日次スクリーニング結果を解釈する のように説明を兼ねていたので、それなりの説明文になっていた。さらに本文には ## Description という節まである。仕様を知らずに、「説明はここに書くもの」と自己流で書いていた形跡だ。
仕様に寄せる価値
Claude Code はかなり寛容に作られている。ドキュメントによると、YAML が壊れていてもフィールドなしでロードされ、知らないフィールドは黙って無視される。Claude Code 独自のフィールド(disable-model-invocation、argument-hint、model、context など)も使える。
一方、同じドキュメントには、Claude Code の外では扱いが厳しいとも書かれている。claude.ai へのアップロード、Skills API、anthropics/skills の package_skill.py では、仕様にないフィールドがあるとハードエラーになる。
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name
今回の6個はフロントマター自体がないので、仕様上は name と description という必須項目の欠落で不合格になる。同じスキルを Claude Code 以外のエージェントや API で使い回すつもりなら、次の2点を守っておくのが無難だ。
-
nameとdescriptionは必ずフロントマターに書く。descriptionには、何をするかと、いつ使うかの両方を書く - Claude Code 専用のフィールドを使うと、Claude Code の外では読み込めなくなる ことを意識する。持ち出す予定があるなら、仕様の6フィールドに収める
直すのは簡単で、先頭に数行足すだけだ。
---
name: write-article
description: 個人開発PJTのコードや設計ドキュメントを読み込み、実態に即したZenn記事を書く。「記事を書いて」「〜について記事にして」と頼まれたときに使う。
---
# write-article
...
1つだけ注意がいるケースがあった。投資分析ツールの scan スキルは、Claude Code から呼ぶだけでなく、日次バッチが SKILL.md をまるごと読んで Anthropic API の system プロンプトに渡している。
# src/notify/claude_analyzer.py(抜粋)
_SKILL_PATH = Path(__file__).parent.parent.parent / ".claude" / "skills" / "scan" / "SKILL.md"
...
skill_content = skill_path.read_text(encoding="utf-8")
...
system=[
{
"type": "text",
"text": skill_content,
"cache_control": {"type": "ephemeral"},
}
],
この構成は claude -p から API へ移行した記事で詳しく書いた。ここにフロントマターを足すと、YAML の数行もそのまま system プロンプトに入る。害はほとんどないが、プロンプトキャッシュは一度作り直しになる。気になるなら、読み込む側で --- から --- までを取り除けばいい。スキルを「エージェント向けの手順書」と「プログラムから読むプロンプト」の両方に使い回していると、こういうところで形式の変更が波及する。
まとめ
- Agent Skills は2026年10月22日に AAIF(Linux Foundation 傘下)へ寄贈され、MCP と同じく中立な標準になった。仕様自体の変更はまだなく、今後バージョン付きリリースや提案プロセスが整備される
- 仕様の必須項目は、フロントマターの
name(ディレクトリ名と一致)とdescriptionの2つだけ。エージェントが起動時に読むのもこの2つなので、descriptionの質が自動呼び出しの精度を左右する - 手持ちの27スキルを検査したら、6個がフロントマターなしだった。Claude Code では本文の最初の行が説明文に使われるので、
# write-articleのような見出しだけのスキルは、名前と説明が同じ文字列になっていた - Claude Code は寛容なので動いてしまうが、claude.ai や Skills API では仕様にないフィールドがハードエラーになる。標準になったこの機会に、
nameとdescriptionだけでも仕様どおりに書いておきたい
この記事は Zenn にも同じ内容を投稿しています。