Agent SkillsとSKILL.md：プログレッシブディスクロージャーを測る

第14章では、この講座の後半におけるルール、つまり接続、リトライ、キャンセルはTypeScriptで扱う、という方針を置き、5つの例外を宣言しました。これはその1つです。理由は好みではありません。

skillはMarkdownファイルです。 プログラムを設定するファイルでも、プログラムがコンパイルするファイルでもありません。モデルが、あなたの入力したメッセージを読むのと同じように読むドキュメントです。この章にプログラミング言語を与えることは、そのフォーマットを理解していないことを意味します。そして、その誤解こそがskillについて最もよくある誤解です。以下に出てくるのはMarkdownとYAML、そしてskillの中でcodeがどこに属し、どこに属さないかを示すためだけに存在する小さなshell scriptです。

実際の手順を1つ挙げます。ある会社がリリースノートを書く方法です。これは好みではなく手順です。順序付きのステップ、分類体系、文体、テンプレート、そして素材を集めるscriptがあります。

多くのチームがそうしているように、そのすべてをsystem promptに入れると、第16章の算術が支配します。system promptはprefixであり、prefixはすべての呼び出しで支払われます。この章のために書いたフォルダをo200k_baseで測ると、こうなります。

whole thing pasted into the system prompt   1,716 x 40  =  68,640 input tokens   $0.1373
as a skill, activated once on turn 12          46 x 40
                                            + 324 (SKILL.md body)
                                            + 665 (two reference files read)
                                                        =   2,829 input tokens   $0.0057
as a skill, never activated at all             46 x 40  =   1,840 input tokens   $0.0037

使われるときは24倍安く、使われないときは37倍安い。料金は第16章のものです。入力100万tokenあたり$2.00です。

ここで正直な反論を入れます。これを飛ばす章は広告になってしまうからです。prompt cachingは金銭面の差をほぼ埋めます。 system promptは安定しており、先頭に置かれるため、存在しうる中で最高のcache候補です。cached inputが100万tokenあたり$0.20なら、同じ68,640 tokensのコストは$0.1373ではなく$0.0168です。それでもskillの3倍ですが、もはや桁違いではありません。

金銭は最初から最強の論点ではありません。最強なのはこちらです。

Caching makes a permanent prefix cheaper. It does not make it smaller.

40ターン目でも、system-prompt版ではリリースノート方針の1,716 tokensが、まったく別の話題についての会話中にwindowへ居座り、第24章がモデルのattention budgetと呼んだものを奪い合います。skill版では46です。間違ったものをcacheすれば、あなたが買ったのは気を散らすものへの割引です。

式で書くと、$n$をターン数、$L_1$をmetadata、$L_2$をbody、$L_3$をbundle全体、$R$を実際に読まれたbundled filesの集合として、こうなります。

この章全体は、第2項を$n$倍するか、1倍または0倍するかの違いです。

skillはdirectoryです。仕様は、完全に述べられるほど短いものです。

release-notes/
├── SKILL.md          # required: YAML frontmatter + Markdown instructions
├── scripts/          # optional: executable code
├── references/       # optional: documentation read on demand
├── assets/           # optional: templates, schemas, examples
└── ...               # anything else you like

SKILL.mdはYAML frontmatterで始まらなければならず、必須fieldはちょうど2つ、nameとdescriptionです。¹ さらに4つが任意で、定義されているfieldはそれ以上ありません。

こちらがrelease-notes skillの全体です。bodyは30行未満です。

---
name: release-notes
description: Write the release notes for a tagged version in this company's house style. Use when preparing a release, drafting a changelog entry, or when someone asks for the notes for a version number or a tag.
allowed-tools: Bash(git log:*) Bash(git tag:*) Read
---

# Release notes

## Procedure

1. Run `scripts/collect.sh <previous-tag> <new-tag>`. It prints one line per merged
   pull request: number, title, author and the labels.
2. Drop every line whose labels contain `internal`, `ci` or `chore`.
3. Put each surviving line into exactly one of the four categories in
   [references/categories.md](references/categories.md). A change that seems to fit two
   belongs in the higher one; the order in that file is the order of precedence.
4. Rewrite each line as a sentence in the voice defined in
   [references/voice.md](references/voice.md). The pull request title is a note to
   the team; the release note is a note to a stranger.
5. Check the result against [references/examples.md](references/examples.md).

## The one rule that is not negotiable

Every note says what a person can now do, or what stopped happening to them. If a
sentence can only be understood by someone who has read the diff, it is not finished.

そのbodyが何であるかを読んでください。これは方針そのものではありません。作業順を持った目次です。方針は、そこで名指しされている3つのfileにあり、bodyには含まれていません。そして第1ステップでは作業をscriptに渡しています。scriptのcodeはcontext windowに一切入らないからです。入るのはその出力だけです。²

loading modelには名前と3つの段階があります。仕様はtoken budgetとともにそれらを示しています。¹

1. Metadata、約100 tokens：nameとdescription。インストール済みのすべてのskillについて起動時に読み込まれる。
2. Instructions、推奨は5,000 tokens未満：SKILL.mdのbody。skillがactivateされたときに読み込まれる。
3. Resources、必要に応じて：bundled files。何かがそれを必要としたときだけ読み込まれる。

reference documentationは同じ表に4つ目の列、つまりwhen loaded、token cost、contentを置いています。重要なのは3行目です。アクセスされるまでゼロ。³ この章全体を要約する文もそこにあります。

Files don't consume context until accessed, so Skills can include comprehensive API documentation, large datasets, or extensive examples. There's no context penalty for bundled content that isn't used.³

この章の冒頭に置いた測定表は、その主張を、この記事のために誰かが書いたわけではない5つのskillで確かめたものです。2つの行は、並べて読む価値があります。

next-best-practicesには966-tokenのbodyがあり、19,374 tokensを持つ19個のfileへlinkしています。hydration errorを直すよう依頼すると、agentが読むのはbodyとhydration-error.mdだけです。20,340のうち1,409 tokens、14分の1で、残り18個のfileは開かれません。

next-cache-componentsには2,334-tokenのbodyがあり、bundled filesはまったくありません。これは有効なskillであり、よく書かれたskillでもありますが、開示すべきlevel 3を持っていません。これがこの技法の正直な限界です。progressive disclosureが節約になるのは、先送りできるものがある場合だけです。知識が分解できないskillは、activation時にbody全体を支払います。残るleverは、それをactivateしないことだけです。

level 1は、1文から行われるrouting判断です。skillについて、それ以外の何も、そのskillが開かれるかどうかには影響しません。bodyの品質も、例も、scriptも関係ありません。つまりdescriptionはdocumentationではありません。query surfaceであり、そこは間違えられます。

仕様は、良い例と悪い例という形でそれを述べています。そして悪い例は4語です。description: Helps with PDFs.¹ これは受け入れるより測る価値があります。

6つのskill。それぞれに、何をし、いつ使うかを述べるもっともらしいdescriptionがあります。24個のrequest、各skillにつき4つ。人がそう言うであろう言い方で表現し、skill名は決して出しません。モデルはsystem prompt内で6行を見て、1つの名前、またはNONEで答えなければなりません。greedy decodingなので再現します。次に、同じ6つのskillと同じ24個のrequestで、descriptionを裸のsubjectまで削ります。

rich   - sql-review: Review a SQL migration for locks, missing indexes and unsafe
         defaults before it runs on the production database. Use when someone adds
         or changes a migration, an index, or a table column.
thin   - sql-review: Helps with SQL.

rich   295 tokens of level 1 for six skills   18/24 correct = 75.0 %  [55.1, 88.0]
thin    81 tokens of level 1 for six skills   10/24 correct = 41.7 %  [24.5, 61.2]

paired: rich only 9, thin only 1, two-sided sign test p = 0.0215
answered NONE: rich 1 of 24, thin 9 of 24

まずintervalを読んでください。第4章が求め、第29章が再び求めるようにです。intervalは重なっています。24件だけでは、aggregateだけで2つのsystemを順位付けできません。決着をつけるのはpaired comparisonです。それは第15章のinstrumentです。2つのarmが食い違った10件のうち、9件はrich description側に、1件はthin description側に行きました。これは通常のthresholdで成立しています。

次に最後の行を読んでください。これが実際の発見です。thin descriptionでは、モデルは24件中9件でNONEと答えました。間違ったskillではありません。skillなし、です。そのうち4つを、そのまま示します。

"Check this migration before I run it against production."     -> release-notes
"Will this CREATE INDEX lock writes?"                          -> NONE
"Is this ALTER TABLE safe to deploy at peak traffic?"          -> NONE
"Is 'seamless and powerful' allowed in the app store listing?" -> next-best-practices

完璧なsql-review skillがインストールされていて、bodyも例もchecklistもありました。それでも、そのskillのために書かれた3つの質問で、3回連続で一度も開かれませんでした。level 1に到達しないskillにとって、level 2と3は無関係です。

修正コストは214 tokensです。6つのskillにまたがる、295と81の差です。これは第18章の発見が反対側から到着したものです。そこでは、toolのdescriptionだけを変えることで、date formattingは24件中2件正解から24件中24件正解になりました。ここでは、skillのdescriptionだけを変えることで、activationは24件中10件から18件になります。どちらの場合も、system内で最も安い修正は1文です。そしてどちらの場合も、その文はsubjectだけでなくtriggerを名指ししなければなりません。そのものが何であるかではなく、それが適用される直前にuserが何と言っているはずか、です。

この章が自分自身の基準に対して負っている但し書きが1つあります。これは5億parameterのモデルであり、frontier modelは75%よりはるかにうまくroutingします。大きさではなく、仕組みを読んでください。routing signalは、どのモデルが読むとしても1文の長さです。そして、どんなモデルも、その文に入れなかった情報では選択できません。

2つ目の失敗は、1つ目の反対です。skillは見つかり、levelは正しく分割され、そしてagentは結局そのすべてを読みます。

vercel-react-best-practicesは本当にうまく作られたskillです。1,670-tokenのbodyは8カテゴリのpriority tableと、70個のrule fileを各1行で名指しするquick referenceです。ruleは同じdisk上にあります。70 files、最小132 tokens、中央値319、最大1,052。barrel importsについて1つ質問すると、正直なコストはbody plus 1 file、つまり53,670のbundleに対して2,400 tokens未満です。

ところがbodyの最後の行はこう言います。

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

AGENTS.mdは26,362 tokensです。これは70個のrule fileを連結したものです。合計は25,784で、差分はそれらの間のheadingです。つまりskillはagentに、中央値319 tokensのruleを1つ読むか、同じcontentをすべて、83倍の価格で読むかを選ばせています。しかも、その選択肢を、コストも、いつ取るべきかという条件も添えずに1文で提示しています。

これはbugではなく、fileが間違っているわけでもありません。compiled documentは人間にとって本当に有用ですし、codebase全体のauditを依頼されたagentにとっても有用です。これはlevel-2の招待を持つlevel-3 fileです。そして教訓はこの1つのskillを超えて一般化します。SKILL.mdから出るすべてのpathは、それがいくらかかり、いつ価値があるかを述べるべきです。モデルには、あるfilenameが1つ上のfilenameより83倍高いことを知る方法がないからです。

同じfolderには、stalenessについての小さな教訓もあります。bodyは「8カテゴリにわたる70 rules」と言い、70個を列挙しています。rules/ directoryには72 filesがあり、そのうち2つはscaffolding（_template.mdと_sections.md）です。そしてsidecarのmetadata.jsonは「40+ rules」と言います。同じ集合について3つのcountが1つのfolderにあり、1つは正しく、1つは算術で、1つは古いversionの名残です。skillはdocumentであり、documentは、隣のcodeからずれていったcode commentとまったく同じように腐ります。ただし違いは、こちらは眉をひそめないmachineに読まれることです。

open specificationは6つのfrontmatter fieldを定義しています。reference implementationであるClaude Codeは20個を受け入れます。² 5つのgroupは名前で知っておく価値があります。formatが単なるdocumentではなくなる場所だからです。

Arguments（arguments、argument-hint）は、人がbodyへsubstituteされる値を渡せるようにします。これによりskillはslash commandとして使えます。Scoping（paths）は、globに一致するfileにactivationを限定します。そしてdynamic context injectionはmental modelを変えるものです。!`git diff HEAD`という形の行は、bodyが送られる前に実行され、その出力がtextにsubstituteされます。documentはtemplateであり、その一部はread timeに計算されます。

ここで罠です。同じdocumentationに明記されています。Claude Codeの外、つまりweb product、Skills API、packagingでは、指定された6つのfieldだけが許可され、その他のfieldはupload時のhard errorになります。² つまり、あるproductで完璧に動くskillが、同じvendorの別productではinstallに失敗します。しかも失敗するのはfrontmatterであり、proseを読んでtestできるような部分ではありません。skillをportableにするつもりなら、6つのfieldがbudgetのすべてです。そうでないなら、まさにそのために存在するcompatibilityでそう言ってください。

4つのものが常に互いに混同されます。そしてこの混同は語彙の細かいこだわりではありません。間違って選ぶと、毎turnお金がかかるか、あると思っていた保証を失います。

boldの2行が区別のすべてです。skillは読まれ、toolはinvokeされます。 skillはcontext windowに到着するproseであり、そこにある他のすべてとattentionを奪い合います。モデルはそれに従うことも、読み違えることも、無視することもできます。そしてsystem内の何もそれに気づきません。toolは、モデルの手を完全に離れるcallです。あなたのcodeがargumentsを受け取り、validateし、permissionをcheckし、決定します。第18章は、モデルが提案し、あなたのcodeが処分すると表現しました。その分業こそ、skillにはないものです。

では、実例6つに決着をつけます。

歴史は短く、珍しいほど日付がはっきりしています。そして、ほとんど誰も語らない部分です。

Agent Skillsは、2025年10月16日に、あるvendorのfeatureとして公開されました。そのannouncementでは「agentsが特定taskでよりよく働くためにdiscoverし、dynamicallyにloadできる、instructions、scripts、resourcesのorganized folders」と定義され、3つのlevelは、残しておく価値のある比喩で説明されました。「まず目次、次に具体的な章、最後に詳細なappendixを持つ、よく整理されたmanualのようなもの」です。⁴

2025年12月18日、同じpageは、そのformatをopen standardとして発表するよう更新されました。独自のspecificationがagentskills.ioに置かれ、governanceはcontributionに開かれ、reference validatorもあります。³ 2026年9月7日に読むと、standardのclient showcaseには46個のproductが載っています。editor、terminal、cloud platform、mobile runtime、そしてAnthropic、OpenAI、Google、Mistralのfirst-party coding agentsを含み、それぞれが自分のsetup documentationへlinkしています。¹

MCPとの収束はopenに進められており、確認できる数字があります。

興味深いのはproposalではなくclosureです。SEP-2076は、tools、resources、promptsに並ぶ4つ目のprimitiveを求めました。そこから生まれたworking groupは、答えはnoだと決めました。skillは、すでに存在するresources primitiveに、opt-in extensionとして乗ります。⁵ 第26章では、protocol自身のchangelogに同じ本能を測りました。sampling、roots、loggingは残されるのではなくdeprecatedになりました。自分たちが書いたproposalを取り下げるstandards bodyは、うまく振る舞っています。この話を数字とともに語る理由は、他所で読むsummaryがいまだにskillをMCP primitiveとして説明しているからです。

これで、あなたはSKILL.mdを書き、それを3つのlevelに分けて元を取らせ、他人のskillのfrontmatterを読んでどのfieldが他所へのuploadで生き残らないかを知り、この章全体が中心に据えた問い、system prompt、skill、tool、serverのどれか、に習慣ではなく理由で答えられるようになりました。

まだできないのは、それが機能するかどうかを知ることです。

この章で重要だった主張はすべてmeasurementでした。そして最も重要だったmeasurementはaccuracyでした。24件中18件対24件中10件、それぞれにintervalがあり、その間にpaired testがある。重なる2つのaggregateは何も決めないからです。そのinstrumentは借り物でした。skillのdescriptionはrouting keyであり、bodyはモデルが従うかもしれないし従わないかもしれないprocedureです。そのどちらも、何度も実行して返ってきたものをscoreしなければわからないpropertyです。つまりgolden set、run前に書いたgrader、そして少なくとも1回ではなく毎回うまくいったかを問うmetricです。

第29章がそれです。そして、この章のmethodが依存している数字から始まります。10回中7回成功するagentは70%に見えますが、そのpass^10、つまり10回すべてで成功する確率はゼロです。また、同じ200 transcriptに対して3つのgraderを測り、1 tokenも再生成せずに0%、13%、26%を得ます。いまdescriptionに書いたばかりの文を信頼する前に、それが置き換えた文より悪いと教えてくれるinstrumentが必要です。

この章のすべてのtoken countは、2026年9月7日にlocalで、tiktoken 0.14.0とo200k_base encodingを使って生成しました。対象は、この章の冒頭に挙げた5つのthird-party skillと、この章のために書かれたrelease-notes skillです。その全文は一部上に再掲しています。level 1は、hostがsystem promptにrenderする単一行- name: descriptionとして測定しました。level 2はfrontmatter後のSKILL.md bodyです。level 3はfolder内のその他すべてのfileです。costは第16章で測定したgpt-5.6-terraのrate、入力100万tokenあたり$2.00、cached input 100万tokenあたり$0.20を、それらのcountに適用したものです。測定tokenに対する算術であり、live billの観測ではありません。この章を書くために有料APIは呼び出していません。

activation experimentは、consumer GPU 1枚でQwen/Qwen2.5-0.5B-Instructをhalf precisionで実行しました。greedy decoding、6つのskillに対する24個のrequestを2回です。1回目はskillが何をし、いつ適用されるかを述べるdescription、2回目は仕様自身の「poor example」のstyleで裸のsubjectまで削ったdescriptionです。intervalは95%のWilsonです。paired comparisonは、10個のdiscordant caseに対するtwo-sided exact sign testです。Wilson intervalは第4章のもの、exact paired sign testは第15章のもので、どちらも変更なしに再利用しています。magnitudeは非常に小さいモデルのpropertyとして読み、methodはtransferableなものとして読んでください。

ここで測定した5つのskillはthird-party packageであり、この章のために書かれたものではありません。vercel-labs/next-skills由来のnext-best-practicesとnext-cache-components、そしてvercel-labs/agent-skills由来のvercel-composition-patterns、vercel-react-best-practices、vercel-react-native-skillsです。それらの内部count、つまり70 rule files、26,362 tokensのAGENTS.md、2026年1月付けで「40+ rules」と主張するmetadata.jsonは、2026年9月7日にdisk上のfileから読み取ったものであり、その公開versionのpropertyです。著者への批判ではありません。どれも、countされるより頻繁に編集されるdocumentation treeならどこにでも現れるdriftです。