Agent Skills ve SKILL.md: Progressive disclosure, ölçülmüş

14. Bölüm, bu kursun ikinci yarısı için kuralı koydu — bağlantılar, yeniden denemeler ve iptal TypeScript’tir — ve beş istisna ilan etti. Bu onlardan biri, nedeni de tercih değil.

Bir skill bir Markdown dosyasıdır. Bir programı yapılandıran dosya değil, bir programın derlediği dosya değil: modelin, senin yazdığın mesajı okuduğu gibi okuduğu bir belge. Bu bölüme bir programlama dili vermek, formatı anlamamış olmak demek olurdu; skills hakkında en yaygın yanlış anlama da tam olarak bu. Aşağıdaki her şey Markdown ve YAML, artı kodun bir skill içinde nereye ait olup nereye ait olmadığını özellikle göstermek için var olan küçük bir shell script.

İşte gerçek bir yönerge: bir şirketin release notes’ları nasıl yazdığı. Bu bir tercih değil, bir prosedür — sıralı adımları, bir taksonomisi, bir sesi, bir şablonu ve ham malzemeyi toplayan bir script’i var.

Çoğu ekibin yaptığı gibi bunların tamamını system prompt’a koyarsan 16. Bölüm’ün aritmetiği devreye girer. Bir system prompt bir prefikstir ve prefiks için her call’da ödeme yapılır. Bu bölüm için yazılan klasör üzerinde o200k_base ile ölçüldüğünde:

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

Kullanıldığında yirmi dört kat, kullanılmadığında otuz yedi kat daha ucuz. Oranlar 16. Bölüm’den: milyon input token başına $2,00.

Şimdi dürüst itiraz, çünkü bunu atlayan bir bölüm reklam olurdu. Prompt caching para farkını büyük ölçüde kapatır. System prompt stabildir ve en başta durur; bu da onu mümkün olan en iyi cache adayı yapar. Cached input için milyon başına $0,20 ile aynı 68.640 token $0,1373 yerine $0,0168 tutar. Hâlâ skill’in üç katı, ama artık başka bir büyüklük mertebesi değil.

Para hiçbir zaman en güçlü argüman değildi. Şu argümandı:

Caching, kalıcı bir prefiksi ucuzlatır. Onu küçültmez.

40. turda system-prompt sürümünün context window içinde hâlâ 1.716 tokenlık release-note politikası durur; konuşma bambaşka bir şey hakkındayken bile, 24. Bölüm’ün modelin attention budget’ı dediği şey için yarışır. Skill sürümünde 46 vardır. Yanlış şeyi cache edersen bir dikkat dağıtıcısında indirim satın almış olursun.

Formül olarak yazarsak, $n$ tur, $L_1$ metadata, $L_2$ gövde, $L_3$ tüm paket ve $R$ de gerçekten okunan paketlenmiş dosyalar kümesi olsun:

Bu bölümün tamamı, ikinci terimi $n$ ile çarpmak ile onu birle ya da sıfırla çarpmak arasındaki farktır.

Bir skill bir dizindir. Spesifikasyon, tamamen ifade edilebilecek kadar kısadır:

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 ile başlamalıdır ve tam olarak iki alan zorunludur: name ve description.¹ Dört alan daha isteğe bağlıdır ve başka alan tanımlı değildir:

Release-notes skill’i, gövdesi otuz satırın altında olacak şekilde eksiksiz burada:

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

O gövdenin ne olduğunu oku. Politika değil — işlem sırası olan bir içindekiler tablosu. Politika, adını verdiği ama içine almadığı üç dosyada yaşar. Ve birinci adım işi bir script’e verir, çünkü bir script’in kodu context window’a hiç girmez: yalnızca çıktısı girer.²

Yükleme modelinin bir adı ve üç aşaması var. Spesifikasyon bunları bir token bütçesiyle birlikte belirtir:¹

1. Metadata, yaklaşık 100 token: name ve description, kurulu her skill için başlangıçta yüklenir.
2. Yönergeler, 5.000 tokenın altında önerilir: SKILL.md gövdesi, skill etkinleştirildiğinde yüklenir.
3. Kaynaklar, gerektiği kadar: paketlenmiş dosyalar, yalnızca bir şey gerektirdiğinde yüklenir.

Referans dokümantasyon aynı tabloya dördüncü bir sütun koyar — ne zaman yüklenir, token maliyeti, içerik — ve önemli satır üçüncüdür: erişilene kadar hiçbiri.³ Bütün bölümü özetleyen cümle de oradadır:

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

Bu bölümün başındaki ölçülen tablo, bu iddianın bu makale için yazılmamış beş skill’e karşı kontrol edilmiş hâlidir. İki satırın birlikte okunması gerekiyor.

next-best-practices, 19.374 token tutan on dokuz dosyaya link veren 966 tokenlık bir gövdeye sahip. Ondan bir hydration error düzeltmesini iste ve agent gövdeyi artı hydration-error.md dosyasını okur: 20.340 içinden 1.409 token, on dört katlık bir fark; diğer on sekiz dosya hiç açılmaz.

next-cache-components, 2.334 tokenlık bir gövdeye sahip ve hiç paketlenmiş dosyası yok. Geçerli bir skill ve iyi yazılmış bir skill; ayrıca açıklayacak seviye 3’ü yok. Tekniğin dürüst sınırı budur: progressive disclosure ancak ertelenecek bir şey varsa tasarruf sağlar. Bilgisi parçalanmayan bir skill, etkinleştirildiğinde tüm gövdesini öder ve geriye kalan tek kaldıraç onu etkinleştirmemektir.

Seviye 1, tek bir cümleden verilen routing kararıdır. Bir skill’in başka hiçbir şeyi onun açılıp açılmayacağını etkilemez — gövdenin kalitesi değil, örnekler değil, script’ler değil. Bu yüzden açıklama dokümantasyon değildir. Sorgu yüzeyidir ve yanlış olabilir.

Spesifikasyon bunu iyi bir örnek ve kötü bir örnek biçiminde söyler; kötü örnek dört kelimedir: description: Helps with PDFs.¹ Bunu kabul etmek yerine ölçmeye değer.

Altı skill, her biri ne yaptığını ve ne zaman kullanılacağını söyleyen makul bir açıklamaya sahip. Yirmi dört istek, skill başına dört, bir insanın ifade edeceği gibi phrased ve skill’in adı hiç geçmeden. Model system prompt içinde altı satırı görür ve bir adla ya da NONE ile yanıt vermelidir. Greedy decoding, yani yeniden üretir. Sonra aynı altı skill ile aynı yirmi dört istek, ama açıklamalar yalın konularına kadar kırpılmış hâlde.

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

Önce aralıkları oku; 4. Bölüm’ün ısrar ettiği ve 29. Bölüm’ün yeniden ısrar edeceği gibi: örtüşüyorlar ve yirmi dört vaka, iki sistemi yalnızca toplamlarına bakarak sıralayamaz. Bunu çözen eşleştirilmiş karşılaştırmadır ve bu 15. Bölüm’ün aracıdır: iki kolun ayrıştığı on vakadan dokuzu zengin açıklamalara, biri ince açıklamalara gitti. Bu, olağan eşikte kuruludur.

Şimdi asıl bulgu olan son satırı oku. İnce açıklamalarla model yirmi dört isteğin dokuzunda NONE yanıtını verdi. Yanlış skill değil: hiçbir skill. İşte bunlardan dördü, birebir:

"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

Mükemmel bir sql-review skill’i kuruluydu; gövdesi, örnekleri ve checklist’i vardı; ama yazıldığı üç soru için, üç kez üst üste, hiç açılmadı. Seviye 1’in hiç ulaşmadığı bir skill için seviye 2 ve 3 önemsizdir.

Bunu düzeltmenin maliyeti: 214 token, 295 ile 81 arasındaki fark, altı skill’e yayılmış hâlde. Bu da 18. Bölüm’ün bulgusunun diğer taraftan gelişidir. Orada yalnızca bir tool’un açıklamasını değiştirmek date formatting’i 24’te 2 doğrudan 24’te 24 doğruya taşıdı. Burada yalnızca bir skill’in açıklamasını değiştirmek activation’ı 24’te 10’dan 18’e çıkarır. Her iki durumda da sistemdeki en ucuz düzeltme bir cümledir ve her iki durumda da cümlenin yalnızca konuyu değil trigger’ı adlandırması gerekir: şeyin ne olduğunu değil, geçerli olduğunda kullanıcının az önce ne demiş olacağını.

Bu bölümün kendi standartlarına borçlu olduğu bir uyarı. Bu yarım milyar parametreli bir model ve bir frontier model %75’ten çok daha iyi routing yapar. Büyüklüğü değil mekanizmayı oku: routing sinyali, hangi model okursa okusun, bir cümle uzunluğundadır ve hiçbir model o cümleye koymadığın bilgiye göre seçim yapamaz.

İkinci hata ilkinin tersidir. Skill bulunur, seviyeler doğru ayrılmıştır ve agent yine de tamamını okur.

vercel-react-best-practices gerçekten iyi inşa edilmiş bir skill’dir. 1.670 tokenlık gövdesi, sekiz kategoriden oluşan bir öncelik tablosu ve her biri tek satırla adlandırılan 70 kural dosyası içeren hızlı bir referanstır. Kurallar yanında disktedir: 70 dosya, en küçüğü 132 token, median 319, en büyüğü 1.052. Ona barrel imports hakkında tek bir soru sor ve dürüst maliyet gövde artı bir dosyadır — 53.670’lik bir pakete karşı 2.400 tokenın altında.

Sonra gövdenin son satırı şunu söyler:

## Full Compiled Document

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

AGENTS.md 26.362 tokendır. 70 kural dosyasının birleştirilmiş hâlidir: toplamları 25.784’tür, fark aralarındaki başlıklardır. Yani skill, agent’a 319 tokenlık bir median kuralı okumak ile aynı içeriği, tamamını, seksen üç kat maliyetle okumak arasında bir seçim sunar — ve bu seçimi, maliyeti belirtilmeyen ve ne zaman alınacağına dair koşulu olmayan bir cümleyle sunar.

Bu bir bug değil ve dosya yanlış değil; derlenmiş bir belge bir insan için ve tüm bir codebase’i denetlemesi istenmiş bir agent için gerçekten faydalıdır. Bu, seviye-2 daveti olan bir seviye-3 dosyadır ve ders bu tek skill’in ötesine genellenir: bir SKILL.md içinden çıkan her yol, maliyetini ve ne zaman buna değdiğini söylemelidir; çünkü modelin bir dosya adının üstündeki dosya adından seksen üç kat daha pahalı olduğunu bilmesinin hiçbir yolu yoktur.

Aynı klasör staleness konusunda daha küçük bir ders taşır. Gövde "8 kategoride 70 kural" der ve 70 tane listeler; rules/ dizini 72 dosya içerir, bunların ikisi scaffolding’dir (_template.md ve _sections.md); sidecar metadata.json ise "40+ kural" der. Aynı kümenin bir klasörde üç sayımı: biri doğru, biri aritmetik, biri de eski bir sürümden kalma. Bir skill bir belgedir ve belgeler tam olarak yanındaki koddan uzaklaşıp drift etmiş bir kod yorumu gibi çürür — tek fark, bunu kaşını bile kaldırmayacak bir makinenin okumasıdır.

Açık spesifikasyon altı frontmatter alanı tanımlar. Referans implementasyon olan Claude Code yirmi alan kabul eder.² Beş grubu adıyla bilmeye değer, çünkü formatın yalnızca belge olmaktan çıktığı yerler bunlardır:

Argümanlar (arguments, argument-hint), bir kişinin gövdeye ikame edilen değerler geçmesine izin verir; skill’i slash command olarak kullanılabilir yapan budur. Kapsam belirleme (paths) activation’ı bir glob ile eşleşen dosyalarla sınırlar. Ve dinamik context injection, zihinsel modeli değiştiren alandır: !`git diff HEAD` biçimindeki bir satır gövde gönderilmeden önce çalışır ve çıktısı metne ikame edilir. Belge bir şablondur ve bir kısmı okuma zamanında hesaplanır.

Şimdi tuzak; aynı dokümantasyonda belirtilir: Claude Code dışında — web ürününde, Skills API üzerinden, paketlemede — yalnızca belirtilen altı alana izin verilir ve başka herhangi bir alan yüklemede sert hatadır.² Yani bir üründe kusursuz çalışan bir skill, aynı vendor’a ait başka bir ürüne kurulamaz; hata da metni okuyarak test edebileceğin herhangi bir yerde değil frontmatter’da oluşur. Bir skill’in portable olmasını istiyorsan altı alan tüm bütçedir. İstemiyorsan bunu compatibility içinde söyle; tam olarak bunun için vardır.

Dört şey sürekli birbirine karıştırılıyor ve bu karışıklık kelime bilgisi titizliği değil: yanlış seçmek ya her tur para yakar ya da sahip olduğunu sandığın bir garantiyi kaybettirir.

Kalın yazılan iki satır tüm ayrımdır. Bir skill okunur; bir tool invoked edilir. Skill, context window’a gelen ve oradaki her şeyle attention için yarışan prose’dur; model onu izleyebilir, yanlış okuyabilir veya görmezden gelebilir ve sistemde hiçbir şey bunu fark etmez. Tool ise modelin elinden tamamen çıkan bir call’dur: kodun arguments alır, validate eder, izinleri kontrol eder ve karar verir. 18. Bölüm bunu modelin önerdiği, kodunun hüküm verdiği bir ayrım olarak koydu; bu ayrım tam olarak skill’de yoktur.

Altı gerçek vaka, çözülmüş hâlde:

Tarihçe kısa, alışılmadık derecede iyi tarihlenmiş ve neredeyse kimsenin anlatmadığı kısım.

Agent Skills, 16 Ekim 2025’te bir vendor’ın özelliği olarak yayımlandı; o duyuruda "organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks" diye tanımlandı ve üç seviye, saklamaya değer bir analojiyle anlatıldı: "like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix".⁴

18 Aralık 2025’te aynı sayfa, formatı açık standart olarak duyurmak üzere güncellendi; agentskills.io adresinde kendi spesifikasyonu, katkılara açık governance ve referans validator ile.³ 7 Eylül 2026’da okunduğunda standardın client showcase’i kırk altı ürün listeliyordu — editörler, terminaller, cloud platformları ve mobile runtime’lar; Anthropic, OpenAI, Google ve Mistral’ın first-party coding agents’ları dahil — her biri kendi kurulum dokümantasyonuna link veriyordu.¹

MCP ile yakınsama açıkta ve kontrol edebileceğin rakamlarla yapılıyor:

İlginç olan teklifler değil, kapanıştır. SEP-2076 tools, resources ve prompts yanında dördüncü bir primitive istedi. Ondan doğan çalışma grubu yanıtın hayır olduğuna karar verdi: skills, opt-in extension olarak zaten var olan resources primitive’in üzerinde taşınır.⁵ 26. Bölüm protokolün kendi changelog’unda aynı içgüdüyü ölçmüştü; sampling, roots ve logging tutulmak yerine deprecated edilmişti. Kendi yazdığı bir teklifi kaldıran bir standards body iyi davranıyordur; bu hikâyeyi rakamlarla anlatmanın nedeni, başka yerlerde okuyacağın özetlerin hâlâ skills’i bir MCP primitive’i olarak tanımlamasıdır.

Artık bir SKILL.md yazabilir, onu kendi maliyetini ödeyen üç seviyeye bölebilir, başka birinin skill’inin frontmatter’ını okuyup hangi alanların başka bir yere yüklenirken ayakta kalmayacağını bilebilir ve tüm bölümün etrafında kurulduğu soruyu — system prompt, skill, tool veya server — alışkanlıkla değil gerekçeyle yanıtlayabilirsin.

Yapamayacağın şey, seninkinin çalışıp çalışmadığını söylemektir.

Bu bölümde önemli olan her iddia bir ölçümdü ve en önemlisi bir accuracy idi: 24’te 18’e karşı 24’te 10, her birinde bir aralık ve aralarında eşleştirilmiş test; çünkü örtüşen iki toplam hiçbir şeye karar vermez. O araç ödünç alınmıştı. Bir skill’in açıklaması bir routing key’dir, gövdesi modelin izleyebileceği ya da izlemeyebileceği bir prosedürdür; bunların ikisi de ancak şeyi birçok kez çalıştırıp döneni score ederek öğrenebileceğin özelliklerdir — yani bir golden set, run’dan önce yazdığın bir grader ve en az bir kez değil her seferinde çalışıp çalışmadığını soran metrik.

29. Bölüm budur ve bu bölümün yönteminin dayandığı rakamla açılır: on denemeden yedisinde başarılı olan bir agent %70 gibi görünür ve onun pass^10 — on denemenin hepsinde başarılı olma şansı — sıfırdır. Ayrıca aynı iki yüz transcript üzerinde üç grader ölçer ve tek bir token bile yeniden üretmeden %0, %13 ve %26 alır. Bir description içine az önce yazdığın cümleye güvenmeden önce, onun değiştirdiğin cümleden daha kötü olduğunu söyleyebilecek araca ihtiyacın var.

Bu bölümdeki her token sayımı, 7 Eylül 2026’da, bu bölümün başında listelenen beş third-party skill üzerinde ve bu bölüm için yazılan, tam metni yukarıda kısmen yeniden üretilen release-notes skill’i üzerinde, tiktoken 0.14.0 ve o200k_base encoding ile yerelde üretildi. Seviye 1, bir host’un system prompt’a render ettiği tek satır - name: description olarak ölçülür; seviye 2, frontmatter’dan sonraki SKILL.md gövdesidir; seviye 3, klasördeki diğer her dosyadır. Maliyetler, 16. Bölüm’ün gpt-5.6-terra için ölçtüğü oranları — milyon input token başına $2,00 ve milyon cached input token başına $0,20 — bu sayımlara uygular; bunlar ölçülmüş tokenlar üzerinde aritmetiktir, canlı bir faturanın gözlemleri değildir. Bu bölümü yazmak için ücretli API çağrılmadı.

Activation deneyi Qwen/Qwen2.5-0.5B-Instruct’yi yarım hassasiyette tek bir consumer GPU üzerinde, greedy decoding ile çalıştırdı: altı skill üzerinde 24 istek, iki kez — birinde skill’in ne yaptığını ve ne zaman geçerli olduğunu söyleyen açıklamalarla, diğerinde açıklamalar spesifikasyonun kendi "poor example" tarzında yalın konuya kırpılmış olarak. Aralıklar %95 Wilson’dır; eşleştirilmiş karşılaştırma, on discordant case üzerinde iki yönlü exact sign test’tir; Wilson aralığı 4. Bölüm’den ve exact paired sign test 15. Bölüm’den, ikisi de değiştirilmeden yeniden kullanıldı. Büyüklükleri çok küçük bir modelin özelliği, yöntemi ise taşınabilir olarak oku.

Burada ölçülen beş skill, bu bölüm için yazılmamış third-party paketlerdir: vercel-labs/next-skills kaynağından next-best-practices ve next-cache-components; vercel-labs/agent-skills kaynağından vercel-composition-patterns, vercel-react-best-practices ve vercel-react-native-skills. İç sayımları — 70 kural dosyası, 26.362 tokenlık AGENTS.md, Ocak 2026 tarihli ve "40+ rules" iddiasındaki metadata.json — 7 Eylül 2026’da diskteki dosyalardan okundu ve o yayımlanmış sürümün özellikleridir, yazarlarına yönelik eleştiriler değil: her biri, sayılmasından daha sık düzenlenen herhangi bir dokümantasyon ağacında görülen türden drift’tir.