Agent Skills: Ajanınıza Meslek Öğretmenin Altı Kuralı

Bir klasör, içinde bir markdown dosyası. Bir AI ajanını (agent) belirli bir işte iyi hale getirmenin bilinen en basit yolu bu. Tam da bu kadar basit olduğu için yanlış yapması da çok kolay. Gelin skill yazmanın altı altın kuralını, standardın kendi rakamlarıyla ve sahadan güvenlik verileriyle birlikte öğrenelim.

Bu yazıya "skill kavramını duydum ama tam oturmadı" diyerek geldiyseniz doğru yerdesiniz. Sonuna vardığınızda şunları yapabileceksiniz: bir skill'in ne zaman tetikleneceğini tasarlayabileceksiniz, SKILL.md dosyasının context bütçesini hesaplayabileceksiniz, hangi adımın talimatla hangi adımın script ile yazılması gerektiğine karar verebileceksiniz, internetten indirdiğiniz bir skill'i çalıştırmadan önce nelere bakacağınızı bileceksiniz — ve altıncı kuralda, kimsenin pek konuşmadığı bir şeyi konuşacağız: yazdığınız skill zamanla nasıl çürüyor, bunu nasıl yakalarsınız. Yol boyunca acıyla öğrenilen tuzakları da tek tek işaretleyeceğiz.

1. Skill Tam Olarak Nedir? (Ve Ne Değildir?)

En yalın tanımıyla bir skill, ajana verilen prosedürel bilgidir (procedural knowledge). Model zaten bir sürü olguyu biliyor; bilmediği şey, sizin o işi sizin yönteminizle nasıl yaptığınız. Anthropic'in kendi benzetmesi bu işi çok iyi anlatıyor: skill yazmak, işe yeni başlayan birine oryantasyon dokümanı hazırlamaya benziyor^[1]. Genel amaçlı bir ajanı, sizin ihtiyacınıza göre uzmanlaşmış bir ajana çeviren şey bu doküman.

Format ise neredeyse komik derecede sade: bir klasör, içinde SKILL.md adında bir markdown dosyası. Zorunlu olan tek şey bu. İsteğe bağlı olarak yanına scripts/, references/ ve assets/ klasörleri koyabilirsiniz^[2].

compliance-report/
├── SKILL.md          # Zorunlu: metadata + talimatlar
├── scripts/          # İsteğe bağlı: çalıştırılabilir kod
├── references/       # İsteğe bağlı: derin dokümantasyon
└── assets/           # İsteğe bağlı: şablonlar, kaynaklar

Skill'i komşu kavramlardan ayıran şey de önemli. Prompt değildir: prompt tek konuşmalıktır ve baştan context'e girer; skill dosya sisteminde durur, tekrar kullanılır ve yalnızca gerektiğinde yüklenir^[3]. MCP değildir: MCP (Model Context Protocol) ajana tool verir, yani dış sistemlere erişim; skill ise ajana talimat ve kaynak verir. İkisi rakip değil, tamamlayıcıdır — MCP eli, skill ise el kitabıdır^[3][17].

Standart ve ekosistem: kısa bir zaman çizelgesi

Anthropic skill'leri Ekim 2025'te duyurdu; 18 Aralık 2025'te format agentskills.io adresinde açık standart olarak yayımlandı^[8]. Simon Willison standardı "nefis derecede küçük" (deliciously tiny) diye tanımlıyor — birkaç dakikada okunuyor — ama aynı zamanda "epeyce eksik tanımlı" (quite heavily under-specified) olduğunu da not düşüyor^[5]. Buna rağmen benimsenmesi çok hızlı oldu: Claude Code, OpenAI Codex, Cursor, GitHub Copilot, VS Code, Gemini CLI, Goose, OpenCode, Amp ve Microsoft Agent Framework ile Google ADK dahil 40'tan fazla platform aynı formatı okuyor^{[8][12][13][14][18]}. Yani bir kez yazdığınız skill, birden fazla ajanla çalışıyor.

Formatın doğru olup olmadığını tahmin etmeniz de gerekmiyor: standardın referans kütüphanesi skills-ref validate ./my-skill komutuyla frontmatter'ı ve adlandırma kurallarını denetliyor^[10].

Bir uyarıyı da baştan yapalım, çünkü yazının sonunda buna geri döneceğiz: bir skill kod içerebilir ve o kodu çalıştırabilir. İnternetten skill indirmek, tanımadığınız birinin yazılımını makinenizde koşturmak demek. Bu, skill'leri hem çok güçlü hem de dikkat gerektiren bir araç yapıyor.

2. Motoru Anlayalım: Progressive Disclosure

Beş kuralın hepsi tek bir mekanizmanın etrafında dönüyor, o yüzden önce onu oturtalım. Diyelim ki kurulu 100 skill'iniz var. Ajan bunların tamamını aynı anda okusa context window'u anında dolar. Çözüm, bilgiyi kademeli açmak: progressive disclosure (kademeli açılım)^[1].

Üç seviye var ve her birinin fiyat etiketi farklı^[2][3]:

Bu şemayı aklınızda tutun: bundan sonraki beş kuralın dördü doğrudan bu üç katmanın nasıl kullanılacağıyla ilgili.

3. Kural #1 — Tetiklenen Bir Description Yazın

Bir skill'in çalışıp çalışmayacağına karar veren şey içeriği değil, description alanıdır. Ajan başlangıçta yalnızca isim ve description'ı görür; "bu iş için bu skill'i açayım mı" kararını yalnızca bu iki satıra bakarak verir. Yani dünyanın en iyi skill'ini yazsanız bile, description zayıfsa skill hiç açılmaz.

Standart bu alanlara net sınırlar koyuyor^[2]:

Alan	Zorunlu?	Kural
name	Evet	En fazla 64 karakter; yalnızca küçük harf, rakam ve tire; tire ile başlayamaz/bitemez, çift tire olamaz; klasör adıyla birebir aynı olmalı
description	Evet	En fazla 1.024 karakter; boş olamaz; hem ne yaptığını hem ne zaman kullanılacağını anlatmalı
license	Hayır	Lisans adı ya da pakete dahil lisans dosyasına referans
compatibility	Hayır	En fazla 500 karakter; ortam gereksinimleri (gerekli paketler, ağ erişimi, hedef ürün)
metadata	Hayır	Serbest anahtar-değer eşlemesi (author, version gibi)
allowed-tools	Hayır	Boşlukla ayrılmış, önceden onaylanmış tool listesi (deneysel; her ajanda çalışmayabilir)

Şimdi işin püf noktasına gelelim. Kötü bir description şuna benzer:

description: Rapor üretir.

Ajanın bakış açısından bu cümle hiçbir şey söylemiyor. Hangi rapor? Ne zaman? Doğru versiyon iki soruyu birden yanıtlar^[4]:

---
name: compliance-report
description: Dahili veriden aylık uyum raporunu üretir; satır ve
  kolon toplamlarını doğrulayıp Markdown çıktısı verir. Kullanıcı
  uyum raporu, aylık bildirim, regülasyon raporu ya da denetim
  özeti istediğinde kullanılır.
---

Anthropic'in doküman ekibinin altını çizdiği üç incelik daha var^[4]. Birincisi, description sistem prompt'una enjekte edildiği için üçüncü tekil şahısla yazılır: "Excel dosyalarını işler" doğru, "Excel dosyalarını işlemene yardım edebilirim" yanlış. İkincisi, anahtar kelimeleri açıkça geçirin — kullanıcının kuracağı cümlede hangi kelimeler geçecekse ("bildirim", "denetim", ".xlsx", "PDF") onlar description'da bulunsun. Üçüncüsü, name alanında "claude" ya da "anthropic" gibi ayrılmış kelimeler kullanılamaz.

Sahadan gelen kural: Modeller skill'leri az tetikleme eğiliminde — kullanması gereken skill'i atlarlar. Bu yüzden description'ı biraz fazla iddialı yazmak, az iddialı yazmaktan daha güvenlidir. Kapsamı gerçekten aşan bir tetikleme, hiç tetiklenmemekten daha kolay fark edilir ve düzeltilir.

4. Kural #2 — Gerçek Uzmanlıktan İnşa Edin

Description tetiklenmeyi sağladı; peki içine ne yazacağız? İşte çoğu skill'in raydan çıktığı yer burası, çünkü akla gelen ilk yol şu: "Hey ajan, bana X yapan bir skill yaz."

Bu yolun sonucu genellikle jenerik bir bulamaç oluyor: "hataları uygun şekilde ele al", "girdileri doğrula", "en iyi pratikleri uygula". Yani modelin zaten bildiği şeyler. Skill'in tüm amacı, sizin belirli bir işi yapma biçiminizi aktarmaktı; içerik modelin kendi başına ulaşamayacağı bir yerden gelmek zorunda.

İki sağlam kaynak var. Birincisi: işi bir kez elinizle baştan sona yapın ve ne işe yaradığını, yol boyunca yaptığınız düzeltmelerle birlikte not edin. İkincisi: elinizde zaten duran artefaktlardan damıtın — eski raporlar, runbook'lar, code review yorumları, pull request geri bildirimleri. Anthropic'in önerdiği pratik yöntem de bunun sistemli hali: önce ajanı skill olmadan temsili görevlerde koşturun, nerede takıldığını yazın, skill'i o boşluğu kapatmak için yazın^[1].

Bu bakışın en değerli çıktısı, gövdeye koyacağınız gotcha bölümüdür: makul varsayımları bozan, ortama özgü olgular. Ajanı elle her düzeltişinizde ortaya bir gotcha çıkar. Yazın. Yoksa aynı düzeltmeyi haftaya, ondan sonraki hafta yine yaparsınız.

## Gotcha'lar

- `finance_export.csv` dosyasında tarih kolonu DD/MM/YYYY;
  sistemin geri kalanı ISO kullanıyor. Her zaman dönüştür.
- 3. ve 7. bölgenin verisi ayın 5'inden önce gelmez.
  Daha erken çalıştırılırsa raporu üretme, uyar ve dur.
- "Diğer" kategorisi 2024'te ikiye ayrıldı; eski raporlarla
  karşılaştırırken ikisini toplaman gerekir.

Bu üç madde, modelin hiçbir eğitim verisinden çıkaramayacağı türden bilgi. Skill'in gerçek değeri de burada yatıyor.

Bir uyarı: ekosistem kalite bakımından epey dengesiz. SkillsBench ölçümlerine göre ortalama bir kamuya açık skill 12 üzerinden 6,2 puan alıyor; buna karşılık özenle seçilmiş skill'ler ajanın başarı oranını 16,2 puan yükseltiyor. Yani yalnızca en üst çeyrekteki skill'ler anlamlı fark yaratıyor^[8]. "Bir skill kurdum ama işe yaramadı" hikâyelerinin çoğunun arkasında bu var.

5. Kural #3 — Context'i Akıllı Harcayın

İkinci kural "detaylı yaz" diyor, üçüncü kural "kısa yaz" diyor. Çelişki gibi duruyor ama değil — mesele neyin yazılacağı.

Şekil 1'i hatırlayın: skill tetiklendiğinde SKILL.md gövdesinin tamamı context'e giriyor ve oradaki her satır, konuşma geçmişiyle, sistem prompt'uyla ve diğer skill'lerle aynı bütçeyi paylaşıyor. Anthropic'in dokümanı bunu şöyle özetliyor: context ortak bir kaynaktır, tek başınıza kullanmıyorsunuz^[4]. Dolayısıyla her cümleye şu soruyu sorun: "Modelin bunu benden öğrenmesi gerekiyor mu, yoksa zaten biliyor mu?"

Model PDF'in ne olduğunu biliyor. Bir database migration'ın ne yaptığını biliyor. Python'da dosya okumayı biliyor. Bunları anlatan paragraflar saf israf. Anthropic'in dokümanındaki karşılaştırma çarpıcı: bir PDF kütüphanesinin ne işe yaradığını ve nasıl kurulacağını anlatan 150 token'lık açıklama yerine, 50 token'lık üç satır kod aynı işi daha iyi yapıyor^[4].

Somut sınırlar şöyle: gövdeyi 500 satırın altında tutun, ki bu kabaca 5.000 token'a denk geliyor^[2][4]. Bunu aşıyorsanız içerik bölünmelidir — silinmesi değil, references/ altına taşınması gerekir. Ajan oradaki dosyaları yalnızca gerçekten ihtiyaç duyduğunda açar.

---
name: pdf-processing
description: PDF'ten metin ve tablo çıkarır, form doldurur...
---

# PDF İşleme

## Hızlı başlangıç
[temel talimat + kod örneği]

## İleri seviye
**Form doldurma**: references/FORMS.md
**API referansı**: references/REFERENCE.md
**Örnekler**: references/EXAMPLES.md

Burada iki tuzağa dikkat. Birincisi, referanslar tek seviye derinlikte kalmalı: SKILL.md → advanced.md → details.md → asıl bilgi zinciri kötü bir kalıp, çünkü ajan iç içe referansları çoğu zaman yarım okuyor^[2][4]. İkincisi, 100 satırı geçen bir referans dosyasının başına içindekiler listesi koyun.

Bir de klasik anti-pattern listesi var, hepsi aynı kökten geliyor^[4]:

Anti-pattern	Neden kötü	Doğrusu
"pypdf, pdfplumber, PyMuPDF ya da pdf2image kullanabilirsin"	Seçenek bolluğu ajanı tereddüde sokar, her koşuda başka kütüphane seçer	Tek yolu söyleyin: "pdfplumber kullan. Taranmış PDF'lerde pdf2image + pytesseract."
"Ağustos 2025'ten önceyse eski API'yi kullan"	Zamana bağlı bilgi eskir ve yanlış yönlendirir	Güncel yolu yazın; eski bilgi gerekiyorsa <details> içine alın
scripts\helper.py	Ters bölü yalnızca Windows'ta çalışır	Her zaman düz bölü: scripts/helper.py
Soyut örnekler ("uygun bir format kullan")	Model neyi kastettiğinizi bilemez	Girdi-çıktı çiftiyle somut örnek verin

6. Kural #4 — Tahmin Tehlikeliyse Deterministik Script Yazın

Şimdi belki de en çok işe yarayan kurala geldik. Ajan skill'inizi her çalıştırdığında talimatları okur ve içinden doğaçlayarak geçer. Gevşek adımlarda bu tamamen sorunsuzdur; doğru sonuca giden birçok yol vardır. Ama bazı adımlar her seferinde tam olarak doğru olmak zorundadır. Orada modelin mantığı uçuşta yeniden üretmesini istemezsiniz.

Kural tek cümle: ne kadar buyurgan olacağınızı, adımın ne kadar kırılgan olduğuna göre ayarlayın. Gevşek adım → talimat yazın. Kırılgan adım → kod yazın.

Klasik örnek şu: uyum raporu üreten bir skill'in ilk koşusunda satır toplamları kolon toplamlarını tutmuyor. Matematik yanlış — hem de bir uyum raporunda. Bu, modelin sayıları kendi kafasında toplamasından kaynaklanır. Çözüm test yazmak değildir; test yalnızca kontrol etmeyi akıl ettiğiniz şeyi yakalar. Çözüm, o adımda modele hiç tahmin yaptırmamaktır:

# SKILL.md içinde

## 3. Adım — Toplamları doğrula

Toplamları kendin hesaplama. Şu script'i ÇALIŞTIR:

    python scripts/reconcile.py data/rows.csv

Script satır ve kolon toplamlarını karşılaştırır; fark
varsa hangi satırda olduğunu yazar. Fark sıfır olmadan
4. adıma geçme.

Artık model sayıları toplamıyor; sayıları toplayan bir script'i çağırıyor. Bu hata sınıfı tamamen ortadan kalkıyor, çünkü script tahmin yürütmüyor. Aynı mantık ajanın olasılıksal (probabilistic) doğasıyla ilgili genel bir gerçeğe dayanıyor: model her koşuda aynı kararı vermeyebilir. Sabitlenebilecek her mantığı sabitleyin, esneklik gereken yerde model esnesin.

Script yazarken üç kural daha var^[4]:

Çöz, devretme. Script'iniz sorunu ajana havale etmesin, kendisi halletsin. Dosya yoksa çökmek yerine anlamlı bir mesaj versin ya da varsayılanı üretsin.

# ✗ Devrediyor
def process(path):
    return open(path).read()

# ✓ Çözüyor
def process(path):
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        print(f"{path} yok; boş şablon oluşturuluyor")
        ...

Sihirli sayı bırakmayın. TIMEOUT = 47 gören ajan (ve altı ay sonra siz) bunun neden 47 olduğunu bilemez. Değeri gerekçesiyle yazın: TIMEOUT = 30 # HTTP istekleri tipik olarak 30 sn içinde biter.

Geri bildirim döngüsü kurun. Kalitesi kritik işlerde "üret → doğrula → düzelt → tekrar doğrula" akışını skill'e açıkça yazın; doğrulama geçmeden sonraki adıma geçilmesin. Uzun akışlarda ajanın kopyalayıp işaretleyeceği bir checklist vermek de ciddi fark yaratıyor^[4].

Bu yaklaşım Anthropic'e özgü değil: Codex CLI, Cursor, Goose ve diğerlerinde de scripts/ klasörü aynı şekilde çalışıyor^[12].

7. Kural #5 — Çalıştırmadan Önce Denetleyin

Kendi yazdığınız, satır satır okuduğunuz, kırılgan adımlarını script'e bağladığınız bir skill'e güvenebilirsiniz. Peki çalıştıracağınız her skill'i siz mi yazacaksınız? Ekosistem büyüdükçe cevap "hayır" oluyor — ve burada işler ciddileşiyor.

Hatırlayın: bir skill klasörü çalıştırılabilir script'ler içerebilir. O script'ler yerel dosya sisteminize, ortam değişkenlerinize, ortalıkta duran API anahtarlarınıza erişebilir. Skill'leri güçlü yapan şey tam olarak budur; riskli yapan şey de.

Rakamlar konuşsun. Snyk'in Şubat 2026'da yayımladığı ToxicSkills çalışması, ClawHub ve skills.sh üzerinden toplanan 3.984 kamuya açık skill'i taradı^[6][7]:

 534 skill (%13,4) en az bir kritik seviye bulgu içeriyor — turuncunun alt kümesidir

Araştırmacıların kullandığı risk taksonomisi de yol gösterici — indirdiğiniz bir skill'i incelerken tam olarak bunlara bakacaksınız^[7]:

Kategori	Seviye	Neye bakacaksınız?
Prompt injection	Kritik	Gizlenmiş, kodlanmış ya da yorum içine saklanmış talimatlar
Kötücül kod	Kritik	Backdoor, veri sızdırma, tedarik zinciri saldırısı kalıpları
Şüpheli indirme	Kritik	curl … | sh, bilinmeyen adreslerden ikili dosya çekme
Hatalı kimlik bilgisi kullanımı	Yüksek	Token'ları düz metne yazma, ortam değişkenlerini dışarı taşıma
Sır sızıntısı	Yüksek	Depoya gömülü API anahtarları
Üçüncü taraf içerik	Orta	Güvenilmeyen dış veriyi doğrudan context'e alma
Doğrulanamayan bağımlılık	Orta	Uzaktan çekilen ve sürümü sabitlenmemiş kod/prompt
Doğrudan para erişimi	Orta	Ödeme ya da finans sistemi entegrasyonu
Sistem servislerini değiştirme	Orta	Servis/başlangıç yapılandırmasına dokunma

Pratik reçete kısa. Bir skill'i tıpkı bir npm ya da pip paketi gibi bir bağımlılık olarak görün: SKILL.md'yi ve bütün script'leri okuyun, hangi adreslere çıktığına bakın, sürümü sabitleyin, otomatik güncellenen skill'lerden kaçının. Kaynağı belirsiz bir skill'i ilk kez çalıştıracaksanız izole bir ortamda deneyin. Kurumsal tarafta Anthropic, claude.ai ve Cowork için skill içerik taraması sunuyor; marketplace işletenlere de gönderim hattına otomatik tarama koyup kritik bulguları bloklamaları öneriliyor^[3][7]. SkillSpector gibi açık denetim araçları da bu iş için çıkmış durumda^[9].

Şunu net söyleyelim: skill'lerin açık bir standart olması, herhangi bir skill'in güvenli olduğu anlamına gelmez. Standart formatı tanımlar, niyeti değil. Nitekim prompt injection, üretimdeki ajan güvenliği olaylarının hâlâ en büyük kalemi^[16], ve kötücül skill dağıtımı başlı başına bir saldırı yüzeyi hâline geldi^[15].

8. Kural #6 — Skill'ler Çürür: Ona Canlı Bir Ürün Gibi Davranın

Buraya kadarki beş kural, bir skill'i doğru yazmakla ilgiliydi. Videolarda, dokümanlarda, blog yazılarında hep orada duruluyor. Şimdi kimsenin pek konuşmadığı kısma gelelim: yazdıktan sonrası.

Şöyle düşünün. Kural #2'de skill'in en değerli parçasının gotcha'lar olduğunu söylemiştik: "bu CSV'de tarih formatı farklı", "3. bölgenin verisi ayın 5'inden önce gelmez". Şimdi kötü haber: bunlar aynı zamanda skill'in en kırılgan parçasıdır, çünkü hepsi ortama bağlıdır — ve ortam durmadan değişir. Google'ın kendi skill ekibinin ifadesiyle skill'ler "tek seferlik parçacıklar değil, canlı ürünlerdir"^[20].

Bir skill dört farklı yoldan çürür

Çürüme tipi	Ne olur?	Örnek
Yapısal	Dosya yolları ve komutlar geçersizleşir	Skill tests/Feature diyor, depo çoktan packages/billing/tests'e taşınmış
Standart	Terk edilmiş konvansiyon skill'de yaşamaya devam eder	Ekip o kalıptan vazgeçti, skill hâlâ onu dayatıyor
Ürün bağlamı	Eski aşamanın varsayımı yeni aşamada tehlikeli olur	"Hıza öncelik ver" tavsiyesi, müşteriye açılmış bir sistemde risk üretir
Tooling	Komut ya da iş akışı deprecate olur	Skill artık desteklenmeyen bir eklentiyi çağırıyor

Ve işin sinsi tarafı şurada: bayat bir skill genellikle tek ve bariz bir yerde kırılmaz; kararları yavaş yavaş bozar^[22]. Bu, onu klasik bir bağımlılıktan ayıran şey. Bozuk bir pip paketi size exception fırlatır, hemen anlarsınız. Bayat bir skill hata vermez — ajanı her koşuda biraz yanlış yöne iter, siz de çıktıya bakıp "model bugün kalitesiz" dersiniz.

Drift'in tanımı: her değişiklik değil, ihlal edilen varsayım

Bu konuya akademik taraftan bakan çok net bir tanım var. SkillGuard çalışması, skill çürümesini (skill drift) bir sözleşme ihlali olarak tanımlıyor: her skill, dayandığı servisler, paketler, API'ler ve yapılandırmalar hakkında örtük bir sözleşme taşır; drift, ortamda herhangi bir şey değiştiğinde değil, işleyişin dayandığı bir varsayım bozulduğunda gerçekleşir^[19]. Çalışmanın ayrımı akılda kalıcı: "Yorum satırındaki bir sürüm numarası gürültüdür; aynı numara sabitlenmiş bir bağımlılıkta bir yükümlülüktür."

Bu ayrımın pratik değeri rakamlarda görünüyor. Sözleşme kavramı olmadan kurulan CI kontrolleri %40 yanlış alarm veriyor — yani ekip kısa sürede uyarılara bakmayı bırakıyor. Sözleşmeleri çıkaran yaklaşım ise 599 drift'siz vakada hiç yanlış alarm üretmemiş, bilinen drift'lerde %100 precision ve %76 recall'a, 49 gerçek skill üzerinde yapılan taramada %86 precision'a ulaşmış. En çarpıcı sonuç ise onarım tarafında: hangi varsayımın bozulduğu tespit edilmeden yapılan düzeltme yalnızca %10 başarılı olurken, ihlal edilen sözleşme yerelleştirildiğinde tek turda %78'e çıkıyor^[19].

Panzehir 1: Eval'i baştan yazın

Anthropic'in dokümanındaki en çok atlanan tavsiye şu: kapsamlı dokümantasyon yazmadan önce eval yazın^[4]. Akış şöyle: ajanı skill olmadan gerçek görevlerde koşturun ve nerede battığını yazın. En az üç senaryo hazırlayın. Skill'siz temel performansı ölçün. Sonra bu senaryoları geçirecek asgari talimatı yazın. Ve iterasyonu gerçek gözlemle yapın, varsayımla değil.

{
  "skills": ["compliance-report"],
  "query": "Temmuz ayı uyum raporunu üret",
  "files": ["test-data/july_rows.csv"],
  "expected_behavior": [
    "reconcile.py'yi çalıştırır, kendi kafasından toplamaz",
    "3. ve 7. bölge verisi eksikse uyarıp durur",
    "tarihleri ISO formatına çevirir"
  ]
}

OpenAI'ın Codex ekibinin bu konudaki reçetesi de çok pratik: 10-20 promptluk küçük bir set yeterli, ama seti dört tür çağrıyı kapsayacak şekilde kurun — skill'i açıkça isteyen prompt, yalnızca description üzerinden tetiklenmesi gereken örtük prompt, gerçek hayattaki gibi dağınık ve gürültülü prompt, ve negatif kontrol: skill'in tetiklenmemesi gereken durumlar^[21][23]. Bu sonuncusu çoğu ekipte hiç yok, oysa Kural #1'de "iddialı description yazın" dedik — iddialı description'ın faturasını ancak negatif kontrol gösterir.

Kontrol edeceğiniz dört eksen de şöyle ayrılıyor^[21]: sonuç (iş bitti mi), akış (skill gerçekten çağrıldı mı, adımlar izlendi mi), stil (istenen konvansiyona uyuldu mu) ve verimlilik (gereksiz komut ve token harcandı mı). Ve bu cümleyi bir yere yazın: yaptığınız her elle düzeltme, gelecekteki bir eval adayıdır. Kural #2'de "her düzeltme bir gotcha'dır" demiştik — aynı düzeltme aynı zamanda bir eval satırıdır.

Bir de skill'i hedeflediğiniz bütün modellerle test edin: küçük model için yeterli yönlendirme var mı, büyük model için gereksiz açıklama var mı? Ve şu ikili düzeni deneyin: bir ajan skill'i rafine etsin, ikinci ve temiz bir ajan onu gerçek görevde kullansın, siz de ikincinin nerede takıldığını izleyip birinciye götürün^[4][11].

Panzehir 2: CI kapısı kurun

Eval seti elinizde olunca, onu insan iradesine bırakmayın. Google'ın skill deposunda hiçbir skill merge edilmeden önce şu kapılardan geçiyor^[20]: frontmatter metadata'sını, satır sayısını, dizin düzenini ve adlandırma kurallarını denetleyen linter; skill içindeki her URL'yi çağırıp 404'leri ve uydurulmuş linkleri eleyen link checker; ve yapının gerekli kalıplara uyduğunu denetleyen otomatik kontrol listeleri. Formatın kendisi için standardın referans kütüphanesi zaten hazır: skills-ref validate ./my-skill^[10].

Link checker'ı özellikle küçümsemeyin. Bir skill'in gövdesindeki ölü bağlantı, ajanı ya boşluğa gönderir ya da kendi uydurduğu bir kaynağa; ikisi de sessiz hatadır.

Panzehir 3: Tazeliği takvime bağlayın

Son katman, hiçbir şey değişmemiş gibi görünürken koşan kontrollerdir. Google haftalık zamanlanmış eval işleri koşturuyor ve bunları birden fazla ajan çatısında tekrarlayıp istatistiksel anlamlılık arıyor; ölçüt de iki eksenli: doğruluk ve verimlilik — bir skill her ikisinde de ölçülebilir katkı göstermek zorunda^[20].

Bu ağır geliyorsa küçük ekipler için hafif versiyonu var: skill'i volatilitesine göre etiketleyin ve gözden geçirme sıklığını ona bağlayın — yüksek volatiliteli skill'ler 2-4 haftada bir, orta 6-8 haftada bir, düşük olanlar üç ayda bir. Ve takvimden daha güçlü olan şeyi unutmayın: tetikleyici olaylar. Depo yeniden yapılandırıldıysa, framework yükseltildiyse ya da ürün aşama atladıysa, ilgili skill'leri o gün gözden geçirin^[22].

Bunun için standardın metadata alanı biçilmiş kaftan — serbest anahtar-değer eşlemesi olduğu için ne koyacağınıza siz karar veriyorsunuz, CI'ınız da onu okuyor^[2]:

---
name: compliance-report
description: Dahili veriden aylık uyum raporunu üretir...
metadata:
  owner: veri-platformu
  version: "2.3"
  last-reviewed: "2026-08-01"
  volatility: high
  review-triggers: "şema değişikliği, yeni bölge, rapor formatı revizyonu"
---

Sahip alanı en kritik olanı. Google'ın modelinde iki ayrı rol var: depo bakımcıları deponun sağlığından, skill sahibi ise o skill'in uzun vadeli bakımından sorumlu — API değiştiğinde güncellemek, kalite düştüğünde müdahale etmek onun işi^[20]. Sahibi olmayan skill, kimsenin bakmadığı skill'dir.

Altıncı kuralın özeti: Kural #2'de "ajanı her elle düzeltişinizde bir gotcha doğar, yazın" demiştik. Kural #6 bunun devamı: her gotcha'nın bir son kullanma tarihi vardır. Skill'i yazan kişi işin yarısını yapmıştır; diğer yarısı, o skill'in hâlâ doğru olduğunu düzenli olarak kanıtlamaktır.

9. Kapanış: Kontrol Listesi

Toparlayalım. İyi bir skill, altı cümleye sığıyor — ilk beşi onu doğru yazmakla, sonuncusu doğru kalmasıyla ilgili:

#	Kural	Tek cümlelik özet
1	Tetiklenen description	Ne yaptığını ve ne zaman kullanılacağını yazın; az tetiklenmektense biraz iddialı olun
2	Gerçek uzmanlık	İçerik modelin bilmediği yerden gelsin; her elle düzeltme bir gotcha'dır, yazın
3	Context ekonomisi	Gövde 500 satırın altında; gerisi references/ altına, tek seviye derinlikte
4	Deterministik script	Kırılgan adımda modele tahmin yaptırmayın; script yazın ve "çalıştır" deyin
5	Denetim	Her skill bir bağımlılıktır: okuyun, nereye çıktığına bakın, sürümü sabitleyin
6	Bakım	Skill'ler çürür: sahibi, sürümü ve tazelik tarihi olsun; eval'i CI'da koştursun

Bu altıncı kuralın neden listelerde pek görünmediğini de söyleyelim: skill yazmak keyifli, skill bakmak değil. Bir öğleden sonra oturup yazdığınız dosya hemen işe yarıyor; onun altı ay sonra hâlâ doğru olup olmadığını kimse merak etmiyor. Ama ekosistemin bugünkü hâli bunu artık lüks olmaktan çıkardı: ortalama bir kamuya açık skill 12 üzerinden 6,2 alıyorsa^[8], sorunun bir kısmı kötü yazılmış skill'ler değil, iyi yazılmış ama bayatlamış skill'lerdir.

Ve bu liste büyüyecek. Standart açık, ekosistem hızlı, her ay yeni bir platform aynı formatı okumaya başlıyor. Bugün "en iyi pratik" dediğimiz şeylerin bir kısmı altı ay sonra araç seviyesinde çözülmüş olacak, yerine yeni sorular gelecek.

Şimdi sıra sizde: bir işi alın, elinizle bir kez yapın, düzeltmelerinizi not edin ve o notları bir SKILL.md'ye dökün. İlk koşuda mutlaka bir şey ters gidecek — ve o ters giden şey, yazacağınız en değerli satır olacak. Sonra takviminize bir hatırlatma kurun: iki ay sonra o satır hâlâ doğru mu?

---

Kaynaklar