Claude Code'da skill yazmak

Claude Code’la çalışırken bazı cümleleri tekrar tekrar yazdığımı fark ettim. “Önce etkilenecek satırları göster.” “Oturumu kapatmadan kısa bir not bırak.” “Şu adımları şu sırayla yap.” Her seferinde aynı açıklama, her seferinde biraz farklı kelimelerle ve her seferinde bir şeyi unutma riskiyle.

Bunları skill’e çevirdim. Bu yazı, skill’in ne olduğunu, ne zaman işe yaradığını ve iyi bir skill’in nasıl yazıldığını anlatıyor.

Skill nedir

Skill, içinde bir SKILL.md dosyası olan bir klasör. Dosyanın başında iki alan var: name ve description. Altında da Claude’un izleyeceği talimatlar.

Nerede durduğu kapsamını belirliyor:

Konum	Kapsam
~/.claude/skills/<ad>/SKILL.md	Makinedeki tüm projeler
.claude/skills/<ad>/SKILL.md	Sadece o proje, repoyla birlikte paylaşılabilir
Eklenti	Eklentiyle birlikte gelir

Asıl önemli nokta şu: skill’in sadece açıklaması her turda Claude’un bağlamında duruyor. Gövdesi ise yalnızca skill çağrıldığında yükleniyor. Yani on satırlık bir açıklama sürekli yer kaplıyor, iki sayfalık bir prosedür ise sadece gerektiğinde.

Skill iki yoldan tetikleniyor. Sen /ad yazarak doğrudan çağırabilirsin. Ya da Claude, isteğinin açıklamayla eşleştiğini görüp kendisi çağırır.

Skill mi, CLAUDE.md mi, hook mu

Üçü farklı işler için:

Araç	Ne zaman
CLAUDE.md	Her oturumda geçerli kurallar. Kısa olmalı, çünkü her oturumda tamamı yükleniyor.
Skill	Belirli durumlarda izlenen prosedürler. Uzun olabilir, sadece gerektiğinde yüklenir.
Hook	Bir olayda mutlaka çalışması gereken işler. Örneğin her dosya düzenlemesinden sonra formatter.

Pratik bir ayrım: “her zaman” diye başlayan bir cümle CLAUDE.md’ye gider. “Şu olduğunda şunları yap” diye başlayan bir paragraf skill’e gider. “Bu kesinlikle olmalı, Claude unutsa bile” diyorsan hook’a gider. Claude bir talimatı unutabilir, hook’u unutamaz.

Bir skill’in anatomisi

Uzun bir oturumu kapatıp yenisine geçmeden önce Claude’a kısa bir devir notu yazdırmak için kullandığım skill:

---
name: devir-notu
description: Uzun bir oturumu kapatıp yenisine geçmeden önce kısa bir devir notu yazar. "devir notu yaz", "yeni oturuma geçelim", "handoff", PR açıldıktan, ticket kapandıktan ya da deploy bittikten sonra kullan.
---

# Devir notu

Amaç: yeni oturum, eski oturumun bağlamını taşımadan kaldığı yerden devam edebilsin.

1. Proje kökünde `.claude/handoff/` klasörüne `YYYY-MM-DD-<kisa-konu>.md` yaz.
2. En fazla 25 satır, şu başlıklarla: Amaç, Durum, Yapılanlar, Açık işler, Dikkat, İlgili dosyalar.
3. Kod, log, sorgu çıktısı ya da sır koyma. Sadece yol ve kimlik ver.
4. Kullanıcıya yeni oturumda yazacağı tek satırı ver.

Bu kadar. Kısa, numaralı ve çıktısı belli.

Açıklamayı iyi yazmak

Açıklama, skill’in tetik mekanizması. Claude hangi skill’i çağıracağına buna bakarak karar veriyor. İyi bir açıklamada üç şey var:

• Ne yaptığı. Tek cümle.
• Hangi kelimelerle çağrılacağı. Kendi kullandığın ifadeler, kendi dilinde. Ben Türkçe yazıyorsam açıklamada da “devir notu yaz”, “yeni oturuma geçelim” geçiyor.
• Hangi durumda kullanılacağı. “PR açıldıktan sonra” gibi bir an. Böylece Claude, sen istemeden de önerebiliyor.

Kaçınılacak şey belirsizlik. “Veritabanı işleri için” gibi geniş bir açıklama, yanlış anlarda tetiklenen bir skill demek. “Kayıt güncelleme, silme, geri alma” gibi somut fiiller daha iyi çalışıyor.

Gövdeyi yazmak

Gövde için kurallarım:

1. Numaralı adımlar. Sıra önemliyse sırayı yaz.
2. Çıktının biçimi. Nereye, hangi adla, kaç satır, hangi başlıklarla.
3. Yapılmayacaklar. “Sır koyma”, “onay almadan çalıştırma” gibi. Bunlar en sık unutulan ve en pahalıya patlayanlar.
4. Kısa tut. Uzun bir referans gerekiyorsa ayrı bir dosyaya koy ve skill’den adıyla işaret et. Claude onu da sadece gerektiğinde okur.

İkinci örnek, veri düzeltme için kullandığım protokol. Gövdesi beş adım:

1. Etkilenecek satırları önce say ve birkaç örnek göster, onay almadan devam etme.
2. Güncellemeyi bir transaction içinde yaz. WHERE koşuluna eski değeri de koy, kayıt arada değiştiyse sorgu hiçbir şeye dokunmasın.
3. Geri alma sorgusunu da hazırla.
4. Yazma sorgusunu kimin çalıştıracağını netleştir.
5. Çalıştırdıktan sonra ilk sorguyu tekrar at ve karşılaştır.

Bunu her seferinde anlatmak yerine artık sadece “şu kaydı düzelt” diyorum, gerisini skill hatırlıyor.

Test ve bakım

• Çağır ve izle. Yeni bir skill’i önce /ad ile çağır, sonra doğal bir cümleyle tetiklenip tetiklenmediğine bak. Tetiklenmiyorsa açıklamaya o cümleyi ekle.
• Bir skill, bir iş. İki farklı prosedürü tek skill’e koyma. Açıklama bulanıklaşır, yanlış anda tetiklenir.
• Kullanılmayanı sil. Her skill’in açıklaması her turda bağlamda duruyor. On kullanılmayan skill, her turda boşa giden token demek. Aynı işi yapan eklentileri de temizle.
• Paylaşılacaksa repoya koy. Proje skill’leri .claude/skills/ altında repoyla birlikte ekibe gidiyor. Kişisel olanlar kullanıcı klasöründe kalıyor.

Sonuç

Skill, Claude’a bir kez öğretip her seferinde yeniden anlatmamanın yolu. Kural her zaman geçerliyse CLAUDE.md’ye, prosedür belli durumlarda gerekiyorsa skill’e, iş mutlaka olmalıysa hook’a. Açıklamayı kendi kelimelerinle yaz, gövdeyi kısa ve numaralı tut, kullanmadığını sil.