Claude Skills nedir? Skill dosyası nasıl yazılır ve kurulur

Claude Code'a ya da Codex'e aynı işi her seferinde baştan anlatmak zaman kaybı. Bir skill kurduğunda aynı talimatı yeniden yazmana gerek kalmaz: Claude, isteğini skill'in açıklamasıyla eşleştirdiğinde ilgili SKILL.md dosyasını kendiliğinden okur ve o işi tarif edildiği gibi yapar.

Bu yazı skill'in prompt ve MCP'den farkını, SKILL.md'nin resmi ön bilgi alanlarını, Claude Code'a kurulum adımlarını, iyi bir skill'in nasıl yazıldığını, hazır örneklerin nerede durduğunu ve skill'in ne zaman yetmediğini sırayla anlatıyor.

Skill nedir, prompt ve MCP'den farkı ne?

Skill, Claude'a ya da dosya okuyabilen başka bir kodlama ajanına belirli bir işi nasıl yapacağını öğreten, bir klasöre konan talimat paketidir. Klasörde en az bir SKILL.md dosyası bulunur, ayrıca isteğe bağlı yardımcı script ve referans dosyaları eklenebilir. Skill, konuşma sırasında yazdığın tek seferlik bir prompt değildir: dosya sisteminde kalıcı durur, ihtiyaç duyulduğunda otomatik ya da elle çağrılır ve aynı işte tekrar tekrar kullanılır.

Skill'i MCP ile karıştırmak kolay ama ikisi farklı katmanda çalışır. Skill, modelin zaten sahip olduğu yetenekleri (dosya okuma, bash çalıştırma, kod yazma) bir talimat ve iş akışına paketler, yeni bir dış bağlantı açmaz. MCP ise Claude'u canlı bir dış sisteme, bir veritabanına ya da bir API'ye bağlayan protokoldür ve modele önceden sahip olmadığı yeni araçlar kazandırır.

Üçü birbirini dışlamaz. Bir skill, içindeki talimatla bir MCP aracına atıfta bulunup "şu aracı şu sırayla çağır" diye yönlendirebilir. Kurallı bir çalışma biçimi arıyorsan kalite kapısı mantığına da bakmak faydalı, çünkü iyi bir skill de aynı doğrulama fikrini kullanır.

Skill dosyasının yapısı nedir? (SKILL.md, ön bilgi alanları)

Her skill en az bir SKILL.md dosyasından oluşur. Dosyanın başında YAML ön bilgi (frontmatter) bloğu, altında Markdown talimat gövdesi yer alır. Resmi dokümana göre bu blokta yalnız iki alan zorunludur.

Anthropic'in resmi skill yazım rehberine göre 2026 itibarıyla bir SKILL.md dosyasının adı en fazla 64 karakter, açıklaması ise en fazla 1.024 karakter olabiliyor. description alanı özenle yazılmalı, çünkü Claude onlarca skill arasından doğru olanı seçerken yalnız bu tek cümleye bakıyor.

Ön bilgi bloğunun altına gövdeyi yazarsın: hangi durumda ne yapılacağı, hangi script'in çalıştırılacağı, hangi ek dosyaya bakılacağı. En küçük çalışır şablon şöyle görünür:

---
name: ozet-cikar
description: Bir metinden 3 maddelik özet çıkarır. Kullanıcı uzun bir metin yapıştırıp özet istediğinde kullan.
---

## Talimat

1. Metni oku, ana fikri belirle.
2. En fazla 3 madde halinde özetle.
3. Her maddeyi tek cümlede tut.

Skill'in üç katmanlı bir yükleme mantığı var. Resmi dokümana göre bir skill'in adı ve açıklaması Claude başlarken sistem istemine yükleniyor ve bu yaklaşık 100 token'a karşılık geliyor; SKILL.md gövdesi ise yalnız skill tetiklendiğinde okunuyor ve genellikle 5.000 token'ın altında tutuluyor. Klasördeki ek dosyalar (referans metinleri, script'ler) üçüncü katmandır: yalnız SKILL.md onlara işaret ettiğinde ve gerçekten okunduklarında bağlama girerler, script'lerin kodu hiç girmez, yalnız çıktısı girer.

Claude Code'a skill nasıl kurulur?

Claude Code'da bir skill, iki yerden birine konan bir klasördür. Kişisel skill bu bilgisayardaki tüm projelerde çalışır, proje skill'i yalnız o depoda ve Git'e eklenirse takım arkadaşlarında da çalışır.

1. Klasörü oluştur. Kişisel skill için mkdir -p ~/.claude/skills/ozet-cikar yaz.
2. SKILL.md dosyasını yaz. Önceki bölümdeki şablonu klasörün içine kaydet.
3. Claude Code'u başlat ya da yeniden başlat. Terminalde claude yaz; açık bir oturum varsa yeni skill'i görmesi için oturumu yeniden başlat.
4. Test et. Skill'in konusuna giren bir istek yaz, description eşleşiyorsa Claude otomatik okur. Emin olmak istersen elle /ozet-cikar yazıp da çağırabilirsin.

description cümlesini kurarken kalıp arıyorsan hazır prompt şablonlarına bakmak da işe yarar; ikisi de aynı netlik kuralına uyar: ne istediğini ve ne zaman istediğini açıkça söylemek.

Kendi skill'ini yazmadan önce hazır örnekleri denemek istersen Anthropic'in resmi skill deposunu eklenti olarak kurabilirsin: /plugin marketplace add anthropics/skills yazıp ardından /plugin install example-skills@anthropic-agent-skills ile örnek skill setini indirirsin.

İyi bir skill nasıl yazılır? (kapı, girdi, çıktı)

Resmi en iyi uygulama rehberi, 2026'da SKILL.md gövdesinin en iyi performans için 500 satırın altında tutulmasını öneriyor. Uzayan içerik ayrı dosyalara (reference.md, examples.md) bölünür, SKILL.md yalnız bu dosyalara işaret eder; tıpkı bir iş akışının içindekiler sayfası gibi.

Girdi ve çıktı net olmalı: skill'in hangi bilgiyi (bir dosya, bir metin, bir sayı) girdi olarak beklediği ve hangi biçimde bir çıktı üreteceği açıkça yazılır. Belirsiz bir talimat yerine ("dosyayı işle") somut bir çıktı tarifi ("PDF'i al, metnini çıkar, output.txt'e yaz") Claude'un işin ne zaman bittiğini nasıl anlayacağını da netleştirir.

Sıfırdan Sistem'in kendi döngü mantığıyla örtüşen kısım tam burada: iyi bir skill de bir kapı, yani bir doğrulama adımı içerir. Karmaşık işlerde önerilen kalıp "doğrula, düzelt, tekrar et" döngüsüdür; skill bir script'le ya da bir kontrol listesiyle kendi çıktısını denetler, hata varsa geri döner.

Teslim etmeden önceki kontrol listesi:

• description hem "ne yapar" hem "ne zaman kullan"ı içeriyor mu?
• SKILL.md gövdesi 500 satırın altında mı, uzunsa ayrı dosyaya bölündü mü?
• Zamana duyarlı bilgi (bir fiyat, bir sürüm numarası) ana gövdeye değil ayrı bir "eski yöntem" notuna mı konuldu?
• En az üç gerçek senaryoda denendi mi, skill olmadan yapılan denemeyle karşılaştırıldı mı?
• Terminoloji baştan sona tutarlı mı, aynı kavrama iki farklı ad verilmemiş mi?

Hazır skill örnekleri nerede?

Anthropic, github.com/anthropics/skills deposunda kendi örnek skill'lerini açık kaynak olarak yayınlıyor. Depo dört başlık altında toplanıyor: yaratıcı ve tasarım, geliştirme ve teknik, kurumsal iletişim ve belge skill'leri.

"mcp builder skill" araması burada yanıltıcı olabilir: mcp-builder yeni bir skill üretmiyor, yeni bir MCP sunucusu yazmana yardım ediyor; ikisini birbirine karıştırma, bir önceki bölümdeki tabloya bakarsan fark netleşir.

Kurulum için Claude Code kurulu bir makinede /plugin marketplace add anthropics/skills komutunu bir kez çalıştırman, ardından ihtiyacın olan seti /plugin install ile eklemen yeterli.

Codex ve Cursor aynı skill klasörlerini okuyabiliyor, çünkü üçü de aynı açık standardı izliyor. OpenAI'nin Codex dokümantasyonu 2026'da skill dosyalarının depo, depo üstü, depo kökü, kullanıcı, yönetici ve sistem düzeyinde olmak üzere 6 farklı konumdan tarandığını yazıyor; Cursor'ın resmi dokümanına göre ise uyumluluk için .claude/skills/ ve .codex/skills/ klasörleri de otomatik olarak taranıyor.

Skill ne zaman yetmez?

Skill, statik bir talimat ve script paketidir; kendi başına ağa çıkıp canlı bir sisteme yazamaz. Claude Code'da skill'ler bilgisayarındaki her programla aynı ağ erişimine sahiptir, ama Claude API üzerinde çalışan skill'lerin hiç ağ erişimi yoktur. Gerçek zamanlı bir CRM'e yazmak, bir takvime etkinlik eklemek ya da dış bir veritabanını sorgulamak gibi canlı bağlantı gerektiren işlerde ihtiyacın olan şey skill değil, MCP sunucusudur.

İkinci sınır ölçek: bir skill tek bir işi öğretir. Birden fazla adımın birbirini beklediği, ara denetimlerin olduğu, haftalarca süren bir üretim süreci tek bir SKILL.md'ye sığmaz; bu durumda skill'ler birbirine referans veren daha büyük bir iş akışının parçası olur ya da tamamen ayrı bir orkestrasyon katmanı devreye girer.

Üçüncü sınır dürüstlük: zamana duyarlı bilgiyi (bir fiyat, bir API sürümü, bir kampanya tarihi) SKILL.md'nin gövdesine gömmek, skill'i birkaç ay içinde yanlış bilgi veren bir kaynağa çevirir. Böyle bilgi ya script ile taze çekilir ya da ayrı bir "eski yöntem" notunda saklanır.

Sıfırdan Sistem'in KADRAJ, İZCİ, VİTRİN ve ZARF ajanları da aslında bu mantığın büyütülmüş hâlidir: klasöre konan .md talimat dosyalarıdır. Farkları, tek bir işi değil, baştan sona kapılı (denetimli) bir üretim döngüsünü tarif etmeleridir; bir skill'in birkaç yüz satırlık kapsamının çok üzerine çıkarlar.