1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Agent SkillsがLinux Foundation傘下に——手持ちの27スキルを仕様で検査したら6本が不合格

1
Posted at

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」の節で、ロードの段階が整理されている。

  1. メタデータ(約100トークン): 全スキルの name と description が起動時に読み込まれる
  2. 手順(5000トークン未満を推奨): スキルが有効になったとき、SKILL.md の本文全体が読み込まれる
  3. リソース(必要に応じて): 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 にも同じ内容を投稿しています。

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?