Claude Code skills: beceriler nasıl çalışır, SKILL.md nedir ve ajan onu ne zaman yükler

Claude Code skills nedir

Skill (beceri), belirli bir görev türü için talimat içeren SKILL.md dosyasının bulunduğu bir klasördür: projenin nasıl deploy edileceği, incelemenin nasıl yapılacağı, sürümün nasıl çıkarılacağı. Ajan becerinin varlığını oturumun başından beri bilir, ama tamamını yalnızca görev bunu gerektirdiğinde okur.

Claude Code skills, CLAUDE.md'yi uzun süre tutan herkesin tanıdığı bir sorunu çözer: talimat dosyası büyür. Haftada bir gerekli olan 80 satırlık bir deploy süreci, her oturumda bağlamda yer kaplar — README'deki bir yazım hatasını düzeltirken bile. Beceri bu tür süreçleri kalıcı bağlamdan çıkarıp istek üzerine devreye sokar.

Bir beceri neyden oluşur

En küçük beceri tek bir klasör ve tek bir dosyadır. Proje becerileri depoda durur, kişisel beceriler kullanıcının ana dizininde:

.claude/skills/deploy/SKILL.md      # proje becerisi, git üzerinden ekiple ortak
~/.claude/skills/review/SKILL.md    # kişisel beceri, tüm projelerde kullanılabilir

SKILL.md'nin yanına yardımcı dosyalar da koyabilirsiniz: şablonlar, betikler, referans notları. Ajan bunları yalnızca ana metin onlara atıf yaptığında ve ihtiyaç duyulduğunda açar:

.claude/skills/deploy/
├── SKILL.md           # ana talimat
├── checklist.md       # ayrıntılı kontrol listesi, bağlantıyla okunur
└── rollback.sh        # geri alma betiği

Frontmatter: name ve description

Dosya, --- satırları arasındaki bir YAML bloğuyla başlar. Diğer tüm alanlardan önemli olan iki alan vardır: name — becerinin kısa adı, ve description — becerinin ne yaptığını ve ne zaman uygulanacağını anlatan açıklama.

---
name: deploy
description: Siteyi FTP ile hosting'e deploy etme. Değişiklikleri sunucuya göndermek, sunucudaki farkları kontrol etmek veya deploy'u geri almak gerektiğinde kullan.
---

# Deploy

1. Önce deneme çalıştırması: `./deploy.sh -n`.
2. Dosya listesini kontrol et: içinde sır veya test betiği olmamalı.
3. Yükle: `./deploy.sh`.
4. Değişen sayfaları açıp 200 döndüğünden emin ol.

Geri alma için bu klasördeki rollback.sh'e bak.

Frontmatter'ın altı sıradan Markdown'dır: adımlar, komutlar, kısıtlar, yan dosyalara bağlantılar. Bunu, işi ilk kez yapacak yeni bir ekip arkadaşına yazar gibi yazın.

Ajan bir beceriyi ne zaman yükler

Oturumun başında bağlama yalnızca her mevcut becerinin adı ve açıklaması girer. Beceri başına birkaç satırdır, bu yüzden onlarcasını tutabilirsiniz. Kullanıcının isteği veya mevcut adım açıklamayla örtüştüğünde ajan beceriyi çağırır ve ancak o zaman SKILL.md'nin tamamı bağlama yüklenir.

Buradan temel pratik kural çıkar: beceri açıklamasına göre devreye girer. Ajan, açmaya karar vermeden becerinin gövdesini görmez. description alanına "Yardımcı beceri" yazarsanız ajan ne zaman gerektiğini anlamaz. "Hosting'e deploy; değişiklikleri sunucuya göndermek veya deploy'u geri almak gerektiğinde kullan" yazarsanız anlar.

Otomatik seçimin yanı sıra beceriyi açıkça da çağırabilirsiniz: /deploy gibi eğik çizgiyle adını yazarak. Hangi sürecin gerektiğini tam olarak biliyorsanız ve ajanın isteği açıklamayla kendisinin eşleştireceğine güvenmek istemiyorsanız bu yararlıdır.

description nasıl yazılır ki beceri devreye girsin

• Ne yaptığı — tek cümlede, fiille: "Sitenin deploy'u", "Commit öncesi değişikliklerin incelenmesi".
• Ne zaman kullanılacağı — kullanıcının bu görevi gerçekten istediği ifadeleri sıralayın: "sunucuya at", "yayınla", "geri al".
• Ne zaman kullanılmayacağı, eğer beceri komşusuyla karışabiliyorsa: "botun deploy'u için değil, yalnızca sitenin".
• "Faydalı beceri" ve "işe yardımcı olur" gibi genel ifadelerden kaçının — sinyal taşımazlar.

Kademeli açılım

Beceriler kademeli açılım (progressive disclosure) ilkesine dayanır: bilgi katmanlar halinde verilir ve her sonraki katman yalnızca gerektiğinde yüklenir.

Bu, uzun bir talimat dosyası yerine bir yönlendirici kullanma fikridir: kısa bir harita her zaman elde, ayrıntılar bağlantıyla. Fark şudur: beceri bu yüklemeyi standart bir mekanizma haline getirir; ajanın ilgili belgeyi kendiliğinden açmasına bel bağlanmaz. Ayrıca üçüncü katmandaki bir betiği ajan kodunu bağlama tamamen yüklemeden doğrudan çalıştırabilir.

Skills, CLAUDE.md ve slash komutları: farkları

Üç mekanizma da ajana talimat verir, ama farklı anlarda ve bağlam için farklı maliyetle.

Seçim kuralı basit: talimat neredeyse her görevde gerekiyorsa yeri CLAUDE.md'dir. Yalnızca belirli türdeki görevlerde gerekiyorsa beceridir. Her seferinde elle yazdığınız uzun bir istek varsa, bu bir komut ya da elle çağrılan bir beceri adayıdır.

Kesin yasakları beceriye taşımayın. Beceri hiç yüklenmeyebilir, ama "asla sır commit etme" kuralının her zaman geçerli olması gerekir. Bu tür değişmez kurallar CLAUDE.md'de kalır ve mümkünse mekanizmayla desteklenir: hook'lar, erişim hakları, CI kontrolleri.

Claude Code için beceri nasıl oluşturulur: adım adım

1. Tekrarlanan süreci bulun. İyi bir işaret: ajana aynı şeyi üç kez anlattınız ya da CLAUDE.md'de on görevden birinde gerekli bir bölüm var.
2. Klasörü oluşturun: .claude/skills/<ad>/ ve içine SKILL.md.
3. Frontmatter yazın: name ve description, beceriyi ne zaman uygulayacağı açıkça belirtilmiş olarak.
4. Adımları yazın: somut komutlar ve tamamlanma ölçütleriyle — neyi kontrol edeceğiniz, neyin başarı sayılacağı.
5. Uzun kısımları ayırın: yan dosyalara taşıyın ve ana metinden bağlayın.
6. CLAUDE.md'deki tekrarı kaldırın, yalnızca "Deploy — deploy becerisi" gibi tek satırlık bir işaretçi bırakın.
7. Test edin: yeni bir oturumda görevi beceri adını anmadan, kendi cümlenizle isteyin ve ajanın onu alıp almadığına bakın. Almıyorsa açıklamayı yeniden yazın.

Beceri örnekleri

Deploy becerisi

Klasik aday: süreç nadir, uzun ve tehlikelidir; hata pahalıya patlar. Becerinin içinde adımların sırası (önce deneme çalıştırması, sonra yükleme), neyin yüklenmemesi gerektiği, sonucun nasıl doğrulanacağı ve nasıl geri alınacağı yazılır. Ajanın sunucuya dokunulduğunda değil, her kod düzenlemesinde bunu aklında tutması gerekmez.

İnceleme (review) becerisi

---
name: review
description: Commit öncesi mevcut değişikliklerin incelenmesi. Diff'i kontrol etmek, düzenlemelerdeki hataları bulmak veya değişiklikleri commit'e hazırlamak istendiğinde kullan.
---

# Değişikliklerin incelenmesi

1. Diff'i al: `git diff` ve `git diff --staged`.
2. Değişen her dosya için kontrol et:
   - kullanıcı girdisi çıktıda kaçışlanıyor (escape);
   - SQL sorguları parametreli;
   - hata ayıklama çıktısı ve geçici dosyalar yok.
3. Projenin testlerini ve linter'ını çalıştır (komutlar CLAUDE.md'de).
4. Rapor: sorunların listesi, dosya ve satırla, ciddiden küçüğe doğru.
   Sorun yoksa bunu açıkça yaz, uydurma yorum ekleme.

Böyle bir beceri "bir bak, her şey yolunda mı" isteğini, her seferinde aynı maddelerle yapılan tekrarlanabilir bir kontrole dönüştürür.

Oturumu tamamlama becerisi

Bir başka faydalı tür, çalışmanın sonundaki bir ritüeldir: yerel ortamı durdurmak, geçici dosyaları silmek, ilerleme günlüğüne neyin yapıldığını ve neyin kaldığını yazmak, ayrıntılı açıklamayla commit atmak. Bu, oturumlar arasındaki bağlam kaybını doğrudan giderir: sonraki oturum tahmin yerine deponun güncel durumuyla başlar.

Sık yapılan hatalar

• Belirsiz açıklama. Beceri var ama ajan çağırmıyor. Çözüm: description'ı somut tetikleyicilerle yeniden yazmak.
• Dev beceri metni. SKILL.md'ye eski bölümün tamamı, 400 satır olarak taşındı. Bağlam şişkinliği sorunu sonra geri gelir. Ana metni kısa tutun, ayrıntıları yan dosyalara koyun.
• CLAUDE.md ile çakışma. Aynı süreç iki yerde yazılı ve zamanla ayrışıyor. Tek bir doğruluk kaynağı olmalı.
• Çakışan beceriler. Benzer açıklamalı iki beceri: ajan ikisi arasında rastgele seçiyor. "Kullan / kullanma" ile ayırın.
• Güncelliğini yitirmiş komutlar. Betik yeniden adlandırıldı, beceri eski adı kullanıyor. Beceri projenin kodudur: süreçle aynı commit'te güncelleyin.

Bir bölümü beceriye taşıma zamanı geldi mi

Ara sıra CLAUDE.md'yi gözden geçirin ve her bölüm için sorun: sıradan görevlerin ne kadarında gerçekten gerekli? Neredeyse her zaman gerekiyorsa yerinde kalmalı. On görevden birinde gerekiyorsa beceri adayıdır.

İkinci işaret uzunluktur. Tek ekrana sığmayan bir bölüm neredeyse kesinlikle bir kural değil, bir süreci anlatır. Süreçler, uygulanırken baştan sona okunmak için daha uygundur; bütün oturum boyunca arka planda tutulmaları gerekmez.

Üçüncü işaret tekrarlanan açıklamalardır. Aynı görev için ajana aynı düzeltmeleri defalarca yazıyorsanız, bunları bir kez beceriye yazın. Bir hafta sonra elle yapılan düzeltmelerin azaldığına bakın: becerinin işe yaradığının kanıtı budur.

Sonuç

Claude Code skills, süreçleri projenin yanında tutmanın ve her oturumda bağlam olarak ödemeden saklamanın bir yoludur. Becerinin açıklaması her zaman görünür, gövdesi gerektiğinde yüklenir, yardımcı dosyalar ise daha da sonra. CLAUDE.md'de proje haritası ve sert kurallar kalır; deploy, inceleme, sürüm çıkarma ve belirli türdeki diğer görevler becerilere taşınır. Talimat dosyalarının yapısı ve bağlamın kademeli açılımı, harness engineering kursunda uygulamalı olarak ele alınır.