Agent Skills dan SKILL.md: Progressive Disclosure yang Terukur

Bab 14 menetapkan aturan untuk paruh kedua kursus ini — koneksi, retry, dan pembatalan adalah TypeScript — lalu menyatakan lima pengecualian. Ini salah satunya, dan alasannya bukan preferensi.

Skill adalah file Markdown. Bukan file yang mengonfigurasi program, bukan file yang dikompilasi program: dokumen yang dibaca model, dengan cara yang sama seperti ia membaca pesan yang kamu ketik. Memberi bab ini bahasa pemrograman berarti tidak memahami formatnya, dan kesalahpahaman itu adalah yang paling umum tentang skill. Semua di bawah ini adalah Markdown dan YAML, plus satu shell script kecil yang ada justru untuk menunjukkan di mana code seharusnya dan tidak seharusnya berada di dalam skill.

Ini instruksi nyata: bagaimana satu perusahaan menulis release notes. Ini prosedur, bukan preferensi — ia punya urutan langkah, taksonomi, voice, template, dan script yang mengumpulkan bahan mentahnya.

Masukkan semuanya ke system prompt, seperti yang dilakukan sebagian besar tim, dan aritmetika Bab 16 mengambil alih. System prompt adalah prefix, dan prefix dibayar pada setiap call. Diukur dengan o200k_base atas folder yang ditulis untuk bab ini:

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

Dua puluh empat kali lebih murah saat digunakan, tiga puluh tujuh kali lebih murah saat tidak digunakan. Tarifnya adalah tarif Bab 16: $2,00 per juta input token.

Sekarang keberatan yang jujur, karena bab yang melewatkannya akan menjadi iklan. Prompt caching hampir menutup celah biaya. System prompt stabil dan berada di awal, yang menjadikannya kandidat cache terbaik yang ada; pada $0,20 per juta untuk input yang di-cache, 68.640 token yang sama berbiaya $0,0168 alih-alih $0,1373. Masih tiga kali lipat skill, tetapi tidak lagi berbeda satu orde magnitudo.

Uang tidak pernah menjadi argumen terkuat. Ini argumennya:

Caching membuat prefix permanen lebih murah. Ia tidak membuatnya lebih kecil.

Pada turn 40, versi system-prompt masih memiliki 1.716 token kebijakan release-note yang duduk di window selama percakapan tentang hal lain sepenuhnya, bersaing memperebutkan apa yang Bab 24 sebut sebagai attention budget model. Versi skill memiliki 46. Cache hal yang salah, dan yang kamu beli adalah diskon untuk distraksi.

Ditulis sebagai formula, dengan $n$ turn, $L_1$ metadata, $L_2$ body, $L_3$ seluruh bundle, dan $R$ himpunan file bundle yang benar-benar dibaca:

Seluruh bab ini adalah perbedaan antara mengalikan term kedua dengan $n$ dan mengalikannya dengan satu atau dengan nol.

Skill adalah directory. Spesifikasinya cukup singkat untuk dinyatakan lengkap:

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 harus diawali dengan YAML frontmatter, dan tepat dua field wajib ada: name dan description.¹ Empat lainnya opsional dan tidak ada field lain yang didefinisikan:

Inilah skill release-notes, lengkap, dengan body di bawah tiga puluh baris:

---
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.

Baca apa isi body itu. Ia bukan kebijakan — ia adalah daftar isi dengan urutan operasi. Kebijakannya berada di tiga file yang ia sebutkan dan tidak ia sertakan. Dan langkah pertama menyerahkan pekerjaan ke script, karena code sebuah script tidak pernah masuk ke context window sama sekali: hanya output-nya yang masuk.²

Model loading ini punya nama dan tiga tahap. Spesifikasi menyatakannya dengan token budget yang terlampir:¹

1. Metadata, sekitar 100 token: name dan description, dimuat saat startup untuk setiap skill yang terpasang.
2. Instructions, direkomendasikan di bawah 5.000 token: body SKILL.md, dimuat saat skill diaktifkan.
3. Resources, sesuai kebutuhan: file yang dibundel, dimuat hanya saat sesuatu membutuhkannya.

Dokumentasi referensi menambahkan kolom keempat pada tabel yang sama — kapan dimuat, biaya token, konten — dan baris yang penting adalah yang ketiga: tidak ada sampai diakses.³ Kalimat yang merangkum seluruh bab juga ada di sana:

File tidak mengonsumsi context sampai diakses, sehingga Skills dapat menyertakan dokumentasi API yang komprehensif, dataset besar, atau contoh yang luas. Tidak ada penalti context untuk konten bundle yang tidak digunakan.³

Tabel terukur di awal bab ini adalah klaim itu yang dicek terhadap lima skill yang tidak ditulis siapa pun untuk artikel ini. Dua baris layak dibaca saling berhadapan.

next-best-practices memiliki body 966-token yang menautkan ke sembilan belas file berisi 19.374 token. Minta ia memperbaiki hydration error dan agent membaca body plus hydration-error.md: 1.409 token dari 20.340, faktor empat belas, dan delapan belas file lainnya tidak pernah dibuka.

next-cache-components memiliki body 2.334-token dan tidak ada file bundle sama sekali. Itu skill yang valid dan ditulis dengan baik, dan ia tidak punya level 3 untuk diungkap. Itulah batas jujur teknik ini: progressive disclosure hanya menghemat jika ada sesuatu yang bisa ditunda. Skill yang pengetahuannya tidak terurai membayar seluruh body saat aktivasi, dan satu-satunya tuas yang tersisa adalah tidak mengaktifkannya.

Level 1 adalah keputusan routing yang dibuat dari satu kalimat. Tidak ada hal lain tentang skill yang memengaruhi apakah ia pernah dibuka — bukan kualitas body, bukan contoh, bukan script. Jadi description bukan dokumentasi. Ia adalah query surface, dan ia bisa salah.

Spesifikasi mengatakannya lewat contoh yang baik dan contoh yang buruk, dan contoh buruk itu empat kata: description: Helps with PDFs.¹ Itu layak diukur, bukan sekadar diterima.

Enam skill, masing-masing dengan description yang masuk akal yang mengatakan apa yang dilakukannya dan kapan menggunakannya. Dua puluh empat request, empat per skill, dirumuskan seperti cara seseorang akan merumuskannya dan tidak pernah menyebut nama skill. Model melihat enam baris di system prompt-nya dan harus menjawab dengan satu nama atau dengan NONE. Greedy decoding, jadi ia mereproduksi. Lalu dua puluh empat request yang sama dengan enam skill yang sama, dan description dipangkas menjadi subjek polosnya.

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

Baca intervalnya dulu, seperti yang ditekankan Bab 4 dan akan ditekankan lagi oleh Bab 29: interval itu overlap, dan dua puluh empat kasus tidak dapat memberi peringkat dua sistem hanya dari agregatnya. Perbandingan berpasangan adalah yang menyelesaikannya, dan itu instrumen Bab 15: dari sepuluh kasus ketika kedua arm berbeda pendapat, sembilan berpihak pada description yang kaya dan satu pada yang tipis. Itu terbukti pada threshold yang biasa.

Sekarang baca baris terakhir, yang merupakan temuan sebenarnya. Dengan description tipis, model menjawab NONE pada sembilan dari dua puluh empat request. Bukan skill yang salah: tidak ada skill. Ini empat di antaranya, verbatim:

"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

Skill sql-review yang sempurna sudah terpasang, dengan body dan contoh serta checklist, dan ia tidak pernah dibuka, tiga kali berturut-turut, pada tiga pertanyaan yang memang ia tulis untuk jawab. Level 2 dan 3 tidak relevan bagi skill yang tidak pernah dicapai level 1.

Biaya untuk memperbaikinya: 214 token, selisih antara 295 dan 81, tersebar di enam skill. Ini adalah temuan Bab 18 yang datang dari sisi lain. Di sana, mengubah hanya description sebuah tool membawa pemformatan tanggal dari 2 benar dari 24 menjadi 24 dari 24. Di sini, mengubah hanya description sebuah skill membawa aktivasi dari 10 dari 24 menjadi 18. Dalam kedua kasus, perbaikan termurah dalam sistem adalah satu kalimat, dan dalam kedua kasus kalimat itu harus menyebut trigger dan bukan hanya subjek: bukan apa bendanya, melainkan apa yang baru saja dikatakan user saat ia berlaku.

Satu caveat yang harus dibayar bab ini kepada standarnya sendiri. Ini model setengah miliar parameter, dan frontier model melakukan routing jauh lebih baik daripada 75 %. Baca mekanismenya, bukan magnitudonya: sinyal routing hanya sepanjang satu kalimat model apa pun yang membacanya, dan tidak ada model yang bisa memilih berdasarkan informasi yang tidak kamu masukkan ke kalimat itu.

Kegagalan kedua adalah kebalikan dari yang pertama. Skill ditemukan, level-levelnya dipisahkan dengan benar, lalu agent tetap membaca semuanya.

vercel-react-best-practices adalah skill yang benar-benar dibangun dengan baik. Body 1.670-token miliknya adalah tabel prioritas delapan kategori dan quick reference yang menyebut 70 file aturan, satu baris masing-masing. Aturannya ada di disk di sebelahnya: 70 file, yang terkecil 132 token, median 319, terbesar 1.052. Ajukan satu pertanyaan tentang barrel imports dan biaya yang jujur adalah body plus satu file — di bawah 2.400 token dibanding bundle 53.670.

Lalu baris terakhir body mengatakan ini:

## Full Compiled Document

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

AGENTS.md adalah 26.362 token. Itu adalah 70 file aturan yang digabungkan: jumlahnya 25.784, dan selisihnya adalah heading di antaranya. Jadi skill menawarkan agent pilihan antara membaca satu aturan median seharga 319 token dan membaca konten yang sama, semuanya, dengan harga delapan puluh tiga kali lipat — dan ia menawarkan pilihan itu dalam kalimat tanpa biaya yang terlampir dan tanpa kondisi kapan sebaiknya mengambilnya.

Itu bukan bug dan filenya tidak salah; dokumen terkompilasi benar-benar berguna bagi manusia, dan bagi agent yang diminta mengaudit seluruh codebase. Itu adalah file level-3 dengan undangan level-2, dan pelajarannya berlaku lebih luas dari satu skill ini: setiap path keluar dari SKILL.md harus mengatakan berapa biayanya dan kapan ia layak, karena model tidak punya cara untuk tahu bahwa sebuah filename delapan puluh tiga kali lebih mahal daripada filename di atasnya.

Folder yang sama membawa pelajaran lebih kecil tentang kebasian. Body mengatakan “70 rules across 8 categories” dan mencantumkan 70; directory rules/ berisi 72 file, dua di antaranya scaffolding (_template.md dan _sections.md); dan sidecar metadata.json mengatakan “40+ rules”. Tiga hitungan atas himpunan yang sama dalam satu folder, satu benar, satu aritmetis, dan satu tertinggal dari versi sebelumnya. Skill adalah dokumen, dan dokumen membusuk persis seperti komentar kode yang sudah drift menjauh dari kode di sampingnya — bedanya, yang ini dibaca mesin yang tidak akan mengangkat alis.

Spesifikasi terbuka mendefinisikan enam field frontmatter. Reference implementation, Claude Code, menerima dua puluh.² Lima kelompok layak diketahui namanya, karena di sanalah format berhenti menjadi hanya dokumen:

Arguments (arguments, argument-hint) memungkinkan seseorang meneruskan value yang disubstitusikan ke body, yang membuat skill dapat digunakan sebagai slash command. Scoping (paths) membatasi aktivasi ke file yang cocok dengan glob. Dan dynamic context injection adalah yang mengubah model mental: baris berbentuk !`git diff HEAD` berjalan sebelum body dikirim, dan output-nya disubstitusikan ke teks. Dokumen adalah template, dan sebagian darinya dihitung saat dibaca.

Sekarang jebakannya, dan ia dinyatakan di dokumentasi yang sama: di luar Claude Code — pada produk web, melalui Skills API, dalam packaging — hanya enam field yang dispesifikasikan yang diizinkan, dan field lain apa pun adalah hard error saat upload.² Jadi skill yang bekerja sempurna di satu produk gagal dipasang di produk lain milik vendor yang sama, dan ia gagal di frontmatter, bukan pada sesuatu yang bisa kamu uji dengan membaca prosanya. Jika kamu ingin skill portabel, enam field adalah seluruh budget. Jika tidak, katakan itu di compatibility, yang memang ada persis untuk ini.

Empat hal terus-menerus tertukar satu sama lain, dan kekacauan ini bukan pedanteri kosakata: memilih salah akan membebanimu uang pada setiap turn, atau menghilangkan guarantee yang kamu kira kamu punya.

Dua baris yang dicetak tebal adalah seluruh pembedanya. Skill dibaca; tool di-invoke. Skill adalah prosa yang masuk ke context window dan bersaing memperebutkan attention dengan semua hal lain di sana; model bisa mengikutinya, salah membacanya, atau mengabaikannya, dan tidak ada bagian sistem yang menyadari. Tool adalah call yang keluar sepenuhnya dari tangan model: code kamu menerima argument, memvalidasinya, memeriksa permission, dan memutuskan. Bab 18 menyatakannya sebagai model yang mengusulkan dan code kamu yang menentukan, dan pembagian itu persis yang tidak dimiliki skill.

Jadi enam kasus nyata, diselesaikan:

Sejarahnya singkat, bertanggal luar biasa rapi, dan ini bagian yang hampir tidak diceritakan siapa pun.

Agent Skills dipublikasikan pada 16 Oktober 2025 sebagai fitur satu vendor, didefinisikan dalam pengumuman itu sebagai “folder terorganisasi berisi instruksi, script, dan resource yang dapat ditemukan dan dimuat agent secara dinamis agar bekerja lebih baik pada tugas spesifik”, dengan tiga level dijelaskan lewat analogi yang layak dipertahankan: “seperti manual yang tertata baik, dimulai dengan daftar isi, lalu bab-bab spesifik, dan akhirnya appendix yang mendetail”.⁴

Pada 18 Desember 2025 halaman yang sama diperbarui untuk mengumumkan format tersebut sebagai open standard, dengan spesifikasinya sendiri di agentskills.io, governance terbuka untuk kontribusi, dan reference validator.³ Dibaca pada 7 September 2026, showcase client standard itu mencantumkan empat puluh enam produk — editor, terminal, platform cloud, dan mobile runtime, termasuk coding agents first-party dari Anthropic, OpenAI, Google, dan Mistral — masing-masing menautkan ke dokumentasi setup-nya sendiri.¹

Konvergensi dengan MCP dilakukan secara terbuka, dengan angka yang bisa kamu cek:

Bagian menariknya adalah penutupan, bukan proposalnya. SEP-2076 meminta primitive keempat di samping tools, resources, dan prompts. Working group yang terbentuk darinya memutuskan jawabannya tidak: skill menumpang pada resources primitive yang sudah ada, sebagai extension opt-in.⁵ Bab 26 mengukur insting yang sama dalam changelog protocol itu sendiri, ketika sampling, roots, dan logging dideprecate alih-alih dipertahankan. Badan standard yang menghapus proposal yang ia tulis sendiri sedang berperilaku baik, dan alasan menceritakan kisah ini dengan angka di depan adalah karena ringkasan yang akan kamu baca di tempat lain masih mendeskripsikan skill sebagai MCP primitive.

Sekarang kamu bisa menulis SKILL.md, membaginya menjadi tiga level yang membayar dirinya sendiri, membaca frontmatter skill orang lain dan tahu field mana yang tidak akan bertahan saat di-upload ke tempat lain, serta menjawab pertanyaan yang menjadi fondasi seluruh bab — system prompt, skill, tool, atau server — dengan alasan, bukan kebiasaan.

Yang belum bisa kamu lakukan adalah tahu apakah milikmu bekerja.

Setiap klaim penting dalam bab ini adalah pengukuran, dan yang paling penting adalah akurasi: 18 dari 24 melawan 10 dari 24, dengan interval pada masing-masing dan paired test di antara keduanya, karena dua agregat yang overlap tidak memutuskan apa pun. Instrumen itu dipinjam. Description sebuah skill adalah routing key, body-nya adalah prosedur yang mungkin diikuti model dan mungkin tidak, dan kedua hal itu adalah properti yang hanya bisa kamu ketahui dengan menjalankan benda itu berkali-kali dan memberi skor pada hasilnya — yang berarti golden set, grader yang kamu tulis sebelum run, dan metric yang bertanya apakah ia berhasil setiap kali, bukan setidaknya sekali.

Bab 29 adalah itu, dan ia dibuka dengan angka yang menjadi sandaran metode bab ini: agent yang berhasil tujuh kali dari sepuluh terlihat seperti 70 %, dan pass^10-nya — peluang ia berhasil pada semua sepuluh — adalah nol. Bab itu juga mengukur tiga grader pada dua ratus transcript yang sama dan mendapatkan 0 %, 13 %, dan 26 % tanpa meregenerasi satu token pun. Sebelum kamu memercayai kalimat yang baru saja kamu tulis ke description, kamu membutuhkan instrumen yang bisa memberi tahu bahwa kalimat itu lebih buruk daripada yang kamu gantikan.

Setiap hitungan token dalam bab ini diproduksi secara lokal dengan tiktoken 0.14.0 dan encoding o200k_base, pada 7 September 2026: atas lima skill pihak ketiga yang tercantum di awal bab ini, dan atas skill release-notes yang ditulis untuk bab ini, yang teks lengkapnya direproduksi sebagian di atas. Level 1 diukur sebagai satu baris - name: description yang dirender host ke system prompt; level 2 adalah body SKILL.md setelah frontmatter; level 3 adalah setiap file lain di folder. Biaya menggunakan tarif terukur Bab 16 untuk gpt-5.6-terra, $2,00 per juta input token dan $0,20 per juta input token yang di-cache, diterapkan pada hitungan tersebut — ini aritmetika atas token yang diukur, bukan observasi atas tagihan live. Tidak ada API berbayar yang dipanggil untuk menulis bab ini.

Eksperimen aktivasi menjalankan Qwen/Qwen2.5-0.5B-Instruct dalam half precision pada satu GPU konsumen, greedy decoding, 24 request atas enam skill, dua kali — sekali dengan description yang menyatakan apa yang dilakukan skill dan kapan ia berlaku, sekali dengan description yang dipangkas menjadi subjek polos ala “poor example” milik spesifikasi sendiri. Interval adalah Wilson pada 95 %; perbandingan berpasangan adalah two-sided exact sign test atas sepuluh kasus discordant; interval Wilson adalah milik Bab 4 dan exact paired sign test adalah milik Bab 15, keduanya digunakan ulang tanpa perubahan. Baca magnitudonya sebagai properti model yang sangat kecil dan metodenya sebagai sesuatu yang dapat ditransfer.

Lima skill yang diukur di sini adalah package pihak ketiga, bukan ditulis untuk bab ini: next-best-practices dan next-cache-components dari vercel-labs/next-skills, serta vercel-composition-patterns, vercel-react-best-practices, dan vercel-react-native-skills dari vercel-labs/agent-skills. Hitungan internalnya — 70 file aturan, AGENTS.md pada 26.362 token, metadata.json bertanggal Januari 2026 dan mengklaim “40+ rules” — dibaca dari file di disk pada 7 September 2026 dan merupakan properti versi yang dipublikasikan itu, bukan kritik terhadap penulisnya: semuanya adalah jenis drift yang muncul di pohon dokumentasi mana pun yang diedit lebih sering daripada dihitung.