Skill nedir ve SKILL.md nasıl yazılır?

Skill nedir, kural dosyasından farkı ne?

Açık standardın tanımıyla skill, içinde SKILL.md dosyası olan bir klasördür. Dosyanın başında en az bir ad (name) ve bir açıklama (description), altında ajanın bir işi nasıl yapacağını anlatan talimatlar bulunur. Klasörde betikler, başvuru belgeleri ve şablonlar da durabilir.

Biçimi Anthropic geliştirdi. Claude Code skill desteğini 16 Ekim 2025 tarihinde 2.0.20 sürümüyle getirdi; Anthropic biçimi 18 Aralık 2025 tarihinde açık standart olarak yayımladı. 18 Ekim 2026 itibarıyla Claude Code, Codex, Cursor, Gemini CLI ve Copilot’un skill sayfaları bu standarda dayandığını yazıyor. Standardın kendi listesinde 46 ürün var; standardın sitesi bu listenin desteği sunan ürünlerin yalnız bir kısmını gösterdiğini yazıyor. Google, 18 Haziran 2026’da ücretsiz kullanıcılar ile Google AI Pro ve Ultra aboneleri için Gemini CLI’ın yerine Antigravity CLI’ı getirdi; şirket lisansıyla ya da ücretli API anahtarıyla kullananlar için Gemini CLI sürüyor. Antigravity de skill okuyor ve projede .agents/skills klasörüne bakıyor.

Kural dosyasıyla (AGENTS.md, CLAUDE.md, GEMINI.md) arasındaki fark, ne zaman okunduğunda. Kural dosyası her oturumda baştan sona okunur. Skill’in talimatları ise ancak iş onlara uyduğunda yüklenir. Araçlar bunu kendi sözleriyle söylüyor:

• Claude Code: CLAUDE.md’nin aksine skill’in gövdesi yalnız kullanıldığında yüklenir. Uzun başvuru metinleri bu yüzden gerekene kadar neredeyse hiç yer tutmaz.
• Gemini CLI: GEMINI.md gibi bağlam dosyaları çalışma alanına sürekli bir arka plan verir; skill ise gerektiğinde açılan uzmanlıktır.
• Codex: AGENTS.md ajanın davranışını belirler, skill tekrar eden süreçleri paketler.
• Copilot: Neredeyse her işte geçerli basit talimatlar custom instructions’a, yalnız gerektiğinde okunacak ayrıntılı talimatlar skill’e yazılır.

Eski biçimler de skill’e taşınıyor. Claude Code’da .claude/commands/ altındaki komutlar skill’le birleşti. Codex custom prompt’ları kullanımdan kaldırdı ve yerine skill’i öneriyor. Cursor’da kuralları ve slash komutlarını skill’e çeviren bir /migrate-to-skills skill’i var.

Kural dosyalarını AGENTS.md ve CLAUDE.md yazımızda, her seferinde çalışan komutları hook yazımızda, işi ayrı bir bağlamda yapan yardımcıları subagent yazımızda anlattık. Bu yazı aradaki katmanı anlatıyor: ajanın yalnız gerektiğinde açtığı talimatları.

Ajan bir skill’i ne zaman okur?

Standart bunu kademeli yükleme (progressive disclosure) diye anlatıyor. Ajan bir skill’i tek seferde okumaz; iş gerektirdikçe parça parça okur:

İlk adımın bedeli her oturumda ödenir, skill hiç kullanılmasa bile. Kaç skill kurduğunuz bu yüzden önemli. Bu listeye ne kadar yer ayrıldığını iki araç yazıyor:

• Claude Code listeye modelin bağlam penceresinden %1 pay ayırır. Liste sığmazsa en az kullandığınız skill’lerin açıklamalarını çıkarır. Her açıklama da listede 1.536 karakterde kesilir.
• Codex listeye bağlam penceresinin en çok %2 kadarını ayırır; pencereyi bilmiyorsa 8.000 karakter. skills.max_context_tokens ile bu pay en çok 10.000 token’a çıkar. Çok skill kuruluysa Codex önce açıklamaları kısaltır.
• Cursor, Gemini CLI ve Copilot: belgede yazmıyor.

Skill açıldıktan sonra da yer kaplar. Claude Code’da çağrılan skill’in içeriği konuşmaya tek bir mesaj olarak girer ve sonraki turlarda orada kalır. Konuşma sıkıştırılınca her skill’in yalnız ilk 5.000 token’ı geri eklenir. En önemli talimatı bu yüzden dosyanın başına yazın.

Beş araçta skill hangi klasöre konur?

Standart, skill klasörünün içinde ne olacağını tanımlıyor ama klasörün nerede duracağını tanımlamıyor. Araç geliştirenlere yazdığı rehber bunu açıkça söylüyor ve .agents/skills’i araçlar arasında yaygınlaşan ortak klasör olarak anlatıyor. Beş aracın 18 Ekim 2026 günkü belgeleri şöyle:

Kaynak: her aracın skill belgesi, 18 Ekim 2026. Her skill bu klasörlerde kendi alt klasöründe durur: .agents/skills/<ad>/SKILL.md. Cursor, Claude Code’un ve Codex’in klasörlerini uyumluluk için okuyor. Copilot’un kişisel klasörleri CLI belgesinden; VS Code belgesi bunlara ~/.claude/skills’i de ekliyor. “Belgede yazmıyor”: o gün okuduğumuz sayfalarda bunu anlatan bir cümle bulamadık.

Beş aracın belgesinde birden geçen bir klasör yok. .agents/skills’i dört araç okuyor; Claude Code’un belgesi ise yalnız .claude/skills’i sayıyor, .agents/skills için bir şey söylemiyor. .claude/skills’i Claude Code’un yanında Cursor ve Copilot okuyor; Codex ile Gemini CLI’ın belgeleri bu klasörü saymıyor. Belgede yazmaması, aracın o klasörü okumadığı anlamına gelmez. Ama bir skill’in beş araçta da açılacağına belgelere bakarak güvenmek için tek bir klasör yetmiyor.

Aynı adlı iki skill olduğunda da araçlar farklı davranıyor. Standardın rehberi, proje skill’inin kişisel olanı geçmesini bütün araçların ortak geleneği olarak anlatıyor; Gemini CLI ile Copilot CLI’ın belgeleri buna uyuyor. Claude Code’un belgesinde sıra tersine: kişisel skill projedekini geçer. Codex ise ikisini birleştirmiyor, ikisini de listede gösteriyor.

Alt klasörler de farklı okunuyor. Claude Code ve Codex, oturumu başlattığınız klasörden deponun köküne kadar yukarıdaki her skills klasörünü okur. Cursor deponun içindeki her .cursor/skills ya da .agents/skills klasörünü bulur ve oradaki skill’i yalnız o klasörün dosyalarıyla çalışırken önerir. Gemini CLI ise skills klasöründe yalnız bir seviye derine bakar: .gemini/skills/<ad>/SKILL.md bulunur, daha derindeki bulunmaz.

Aynı skill’i beş araçta nasıl kullanırsınız?

Skill’leriniz .agents/skills’te duruyorsa Codex, Cursor, Gemini CLI ve Copilot onları okuyor; Claude Code için bir adım daha gerekiyor. Belgelere dayanan en kısa yol şu: skill’i .agents/skills/<ad>/ altına yazın, .claude/skills/<ad>’i de ona symlink olarak bağlayın.

mkdir -p .claude/skills
# skill .agents/skills/pr-ozeti/SKILL.md içinde duruyor
ln -s ../../.agents/skills/pr-ozeti .claude/skills/pr-ozeti
git add .claude/skills/pr-ozeti

Claude Code’un belgesi, bir skill klasörünün (.claude/skills/<ad>) başka bir yerdeki klasöre symlink olabileceğini yazıyor. Aynı hedefi gösteren birden çok yer olsa da skill’i bir kez yükler. Bütün .claude/skills klasörünü tek bir symlink yapmak ise belgede geçmiyor; belge skill başına bağlantıyı anlatıyor. Ters yönde bağlayacaksanız Codex’in belgesi de symlink’li skill klasörlerinin hedefini okuduğunu yazıyor.

Windows kullanan bir ekip arkadaşınız varsa bir şeye dikkat edin. Git’in belgesine göre core.symlinks kapalıyken symlink, içinde bağlantının yolu yazan küçük bir metin dosyası olarak çıkar. git clone da dosya sistemi desteklemiyorsa bu ayarı kendisi kapatır. Bağlantının onların makinesinde çalıştığını ayrıca deneyin.

Popüler depoların ne yaptığına da baktık. AGENTS.md yazısı için en çok yıldızlı 100 depoyu 13 Ekim 2026 tarihinde taramıştık; aynı ağaçlara bu kez SKILL.md için baktık. Ağacını tam okuyabildiğimiz 98 deponun 41 tanesinde en az bir SKILL.md var. Bunların 21 tanesi skill’lerini kökteki bir araç klasöründe tutuyor:

En kalabalık klasör, dört aracın birlikte okuduğu .agents/skills. İki klasörü symlink ile birbirine bağlayan 7 depo var. 5 depo .claude/skills’ten .agents/skills’e, 1 depo ters yönde .agents/skills’ten .claude/skills’e, 1 depo da .claude/skills’ten Copilot’un .github/skills klasörüne bağlantı vermiş. vercel/next.js ve flutter/flutter bütün .claude/skills klasörünü bağlıyor. langgenius/dify ise her skill’i ayrı bağlıyor, yani Claude Code belgesinin anlattığı biçimde.

SKILL.md’nin başına neler yazılır?

SKILL.md iki parçadan oluşur: en başta iki --- satırı arasında YAML (frontmatter), altında Markdown talimatlar. Standart frontmatter için altı alan tanımlıyor:

Kaynak: Agent Skills belirtimi, 18 Ekim 2026.

Araçlar bu kuralları aynı sıkılıkta uygulamıyor:

• Claude Code’da bütün alanlar isteğe bağlı, yalnız description öneriliyor. name yoksa klasörün adı kullanılır. Tanımadığı bir alanı hata vermeden yok sayar.
• Codex, Cursor, Gemini CLI ve Copilot name ve description ister.
• Gemini CLI, iki alandan biri eksikse ya da ilk --- satırından önce bir şey varsa (bir başlık, bir yorum, boş bir satır bile) dosyayı sessizce atlar. Skill’in adını da klasörden değil name alanından alır; standart ve Cursor ise adın klasörün adıyla aynı olmasını şart koşuyor.
• Copilot CLI adda büyük harfe, boşluğa, alt çizgiye, noktaya ve iki noktaya da izin veriyor. Standart yalnız küçük harf, rakam ve tire kabul ediyor.

XML etiketiyle ilgili kurallar standardın değil, Anthropic’in. claude.ai ve API için yazdığı kurallara göre name ve description XML etiketi içeremez, name de “anthropic” ve “claude” kelimelerini içeremez. Claude Code’a özgü alanlar (when_to_use, context, hooks gibi) Claude Code’da çalışır. Ama aynı skill’i claude.ai’a ya da Skills API’ye yüklerseniz standart dışı her alan yüklemeyi durdurur: Unexpected key(s) in SKILL.md frontmatter.

Skill’i birden çok araçta kullanacaksanız yalnız standardın alanlarıyla başlayın. Aşağıdaki örnek yalnız iki zorunlu alanı kullanıyor ve beş aracın belgesindeki alan kurallarına uyuyor:

Gövdeye ne yazacağınıza karar verirken standardın rehberindeki soruyu her satıra sorun: bu talimat olmasa ajan bu işi yanlış yapar mıydı? Cevap hayırsa satırı silin. Uzun başvuru metnini references/ altına taşıyın ve SKILL.md’den doğrudan bağlayın. Standart da Anthropic’in rehberi de başvuru dosyalarının SKILL.md’den yalnız bir seviye uzakta olmasını öneriyor.

Açıklamaya ne yazılır?

Ajan bir skill’i seçmeden önce yalnız açıklamasını görür. Standardın rehberi bunu açıkça söylüyor: “the description carries the entire burden of triggering.” Araçların belgeleri de aynı şeyi söylüyor: Claude Code, Codex, Cursor ve Copilot skill’i açıklamaya bakarak seçiyor. Gemini CLI’ın rehberine göre de açıklama, modelin skill’i açmadan önce gördüğü tek bilgi.

• Ne yaptığını ve ne zaman kullanılacağını yazın. Standart, Claude Code, Cursor ve Copilot ikisini birlikte istiyor. “Helps with PDFs.” gibi bir açıklama ajana hiçbir şey söylemez; bu, standardın kendi kötü örneği.
• Kullanıcının söyleyeceği kelimeleri kullanın. Claude Code’un sorun giderme listesi buradan başlıyor: açıklamada kullanıcıların doğal olarak söyleyeceği anahtar kelimeler var mı?
• Önemli kısmı başa yazın. Liste sığmayınca açıklamalar kısalır. Claude Code her açıklamayı listede 1.536 karakterde keser. Codex çok skill kuruluysa önce açıklamaları kısaltır; belgesi bu yüzden kullanım durumunu ve tetikleyen kelimeleri başa yazmanızı öneriyor.
• Benzer skill’lerden ayırın. Gemini CLI’ın rehberi açıklamaların hem birbirinden hem de modelin zaten yapabildiği işlerden ayrı olmasını istiyor.

Hangi kipte yazılacağında rehberler ayrışıyor. Anthropic’in rehberi üçüncü şahıs istiyor ve “I can help you…” ya da “You can use this…” diye başlayan açıklamaların keşfi bozabileceğini yazıyor. agentskills.io’nun rehberi ise açıklamayı ajana verilmiş bir talimat gibi, “Use this skill when…” kalıbıyla yazmayı öneriyor. İki rehberin kendi örnekleri aynı yolu izliyor: önce skill’in ne yaptığı, sonra “Use when…” ile ne zaman kullanılacağı. Yukarıdaki örnek de böyle yazıldı.

İyi bir açıklama da skill’in her seferinde açılacağını garanti etmez. Standardın rehberine göre ajanlar skill’e çoğunlukla kendi başına yapamadıkları işlerde başvurur. “Bu PDF’i oku” gibi tek adımlık bir istek, açıklama tam uysa bile PDF skill’ini açmayabilir. Copilot için VS Code belgesi de keşfin, uygun her istemde skill’in çağrılacağını garanti etmediğini yazıyor.

Skill’i siz mi çağırırsınız, ajan mı seçer?

İkisi de olur. Beş araçta da ajan, işe uygun bulduğu skill’i kendisi açabilir. Elle çağırmak ve ajanın kendi seçmesini kapatmak ise araca göre değişiyor:

Kaynak: her aracın skill belgesi, 18 Ekim 2026. Claude Code ve Copilot’ta user-invocable: false tersini yapar: skill’i yalnız ajan açabilir.

Ajanın kendi seçmesini, yan etkisi olan işlerde kapatın. Claude Code’un belgesi bunu şöyle anlatıyor: “You don't want Claude deciding to deploy because your code looks ready.” Deploy eden, commit atan ya da mesaj gönderen skill’ler bu türden. Claude Code bu ayarla skill’in açıklamasını bağlama hiç koymaz, böylece listede yer de kaplamaz. Elle çağrılan bir skill örneğini, bir inceleme isteğini /incele komutuna çeviren kod inceleme prompt’u yazımızda bulabilirsiniz.

Gemini CLI’da durum farklı: skill’i açan activate_skill aracını yalnız ajan çağırabilir, siz çağıramazsınız. Bunun yerine ajan, bir skill’i her açışında sizden onay ister.

Skill çalışıyor mu, nasıl anlaşılır?

Claude Code’un belgesi bir uyarıyla başlıyor: “Seeing a skill trigger tells you Claude found it, not that it did what you intended.” Skill’in açılması ile işi doğru yapması iki ayrı soru ve ikisi ayrı ayrı ölçülür.

İkisinin ölçüsü de karşılaştırma. Birkaç gerçekçi istem toplayın; her birini yeni bir oturumda bir kez skill açıkken, bir kez kapalıyken çalıştırın ve sonuçları yan yana koyun. Yeni oturum şart, çünkü skill’i yazarken biriken bağlam talimattaki eksikleri gizler.

Skill’in ne kadar sık açıldığını ölçmek için agentskills.io’nun rehberi somut bir tarif veriyor:

• Yaklaşık 20 istem yazın: yarısı skill’i açmalı, yarısı açmamalı.
• Açmaması gerekenleri benzer işlerden seçin. Aynı kelimeleri kullanan ama başka bir şey isteyen istemler, açıklamanın ne kadar keskin olduğunu en iyi gösterir.
• Model her seferinde aynı kararı vermez. Her istemi birkaç kez çalıştırın (3 kez iyi bir başlangıç) ve açılma oranını hesaplayın.
• Eşik olarak 0,5 makul: açması gereken istemlerde oran bunun üstünde, açmaması gerekenlerde altında olmalı.

Tek bir deneme bu yüzden sonuç sayılmaz. Aynı istemin bir koşuda skill’i açıp ötekinde açmaması olağandır; bir açıklamayı değiştirdiğinizde aynı istemleri aynı sayıda yeniden çalıştırın.

Başkasının yazdığı skill’i kurmadan önce neye bakmalı?

Skill yalnız metin değildir: betik çalıştırabilir, bazı araçların sorulmadan kullanılmasına izin verebilir ve talimatlarıyla ajanı yönlendirir. Anthropic’in belgesi, kötü niyetli bir skill’in ajanı söylediği amaca uymayan araç çağrılarına ya da kod çalıştırmaya yönlendirebileceğini yazıyor ve yalnız güvendiğiniz kaynaklardan skill kullanmanızı öneriyor.

Araçlar güven konusunda farklı davranıyor:

• Claude Code bir proje skill’inin allowed-tools alanını, hiç güvenmediğiniz bir klasördeki -p koşusunda bile uygular. Belge bu yüzden depoya eklenmiş skill’lerin bu alanını, Claude Code’u orada çalıştırmadan önce okumanızı istiyor. Bu alan araçları kısıtlamaz; listedeki araçları skill’in çağrıldığı turda sormadan kullandırır.
• Copilot, gh skill ile kurulan skill’lerin GitHub tarafından doğrulanmadığını ve istem enjeksiyonu, gizli talimat ya da zararlı betik içerebileceğini yazıyor. Kurmadan önce gh skill preview ile bakmanızı öneriyor.
• Gemini CLI uzak bir adresten kurarken kaynağı onaylatır ve skill’i her açışında izin ister. .gemini/skills altındaki proje skill’lerini de yalnız çalışma klasörü güvenilir olarak işaretlendiyse yükler.
• Codex ve Cursor’un skill sayfalarında güvenle ilgili bir kural yok: belgede yazmıyor.

Standardın araç geliştirenlere yazdığı rehber de proje skill’lerini yalnız güvenilir olarak işaretlenmiş klasörlerde yüklemeyi öneriyor. Yeni klonladığınız bir depo, siz fark etmeden ajanın bağlamına talimat ekleyebilir.

Skill mi, AGENTS.md mi?

İkisi birbirinin yerine geçmiyor ve popüler depolar ikisini birlikte kullanıyor. Taradığımız depolarda SKILL.md taşıyan 41 deponun 35 tanesinin kökünde AGENTS.md ya da CLAUDE.md de var.

Ayrım, bilginin ne zaman gerektiğinde. Her işte geçerli olanı (projenin yapısı, derleme komutları, “şunu asla yapma” kuralları) kural dosyasına, ara sıra gereken bir iş akışını ya da uzun bir başvuru metnini skill’e yazın. Claude Code’un belgesindeki ölçü işe yarıyor: CLAUDE.md’deki bir bölüm bilgi olmaktan çıkıp bir prosedüre dönüştüyse onu skill yapın.

Vercel bu soruyu 27 Ocak 2026 tarihli yazısında kendi testleriyle sordu. Next.js 16 API’leri üzerine kurduğu testlerde skill, vakaların %56’sında hiç çağrılmadı. AGENTS.md’ye gömülen 8 KB’lık bir belge dizini %100 başarı aldı; skill’in en iyi sonucu %79 oldu. Bu, tek bir ekibin tek bir konudaki ölçümü; yazı kaç görevle ölçüldüğünü de söylemiyor. Vercel’in kendi vardığı yer de “ya biri ya öteki” değil: “The two approaches complement each other.” Yazıya göre kullanıcının açıkça başlattığı belirli iş akışları skill’de daha iyi çalışıyor.

Her pull request’te uyulması gereken bir kural da kural dosyasının işi. diffox bir pull request’i incelerken deponun kökündeki AGENTS.md’yi, yoksa CLAUDE.md’yi okur ve oradaki kuralları inceleme kuralı olarak kullanır. Bir kuralın her incelemede geçerli olmasını istiyorsanız onu kural dosyasına yazın.