Blog
Claude Code'da skill ve agent: hangisini ne zaman yazarsınız
Kısaca: Claude Code'da tekrar eden işi kaydetmenin iki yolu var. Skill bir tariftir: siz veya Claude çağırınca aynı işi aynı sırayla yaptırır. Agent ayrı bir çalışandır: kendi bağlamında çalışır, sadece verdiğiniz araçlara erişir, size özet döner. İkisi de tek bir markdown dosyasıdır. Aşağıda aynı iş üzerinden kurulmuş bir skill ve bir agent örneği, kopyala-yapıştır dosya şablonlarıyla var.
Claude Code'u çoğu kişi gelişmiş bir sohbet penceresi gibi kullanır. Aynı talimatı her seferinde yeniden yazar, aynı formatı her seferinde yeniden tarif eder, üçüncü haftada yazmayı bırakır.
Oysa o talimatı bir dosyaya kaydedip doğru klasöre koymak beş dakika sürüyor. İki yolu var ve aralarındaki farkı bilmek işin yarısı.
Skill bir tarif, agent bir çalışandır
Skill, bir işin nasıl yapıldığını yazdığınız talimat dosyasıdır. Çağrıldığında içeriği sohbetinize yüklenir ve Claude o talimata göre devam eder. Sizin bağlamınızda, sizin açık dosyalarınızla, sizin konuşmanızın içinde çalışır. Bir kurum içi şablon, bir kontrol listesi, bir yazım kuralı seti skill olur.
Agent ise ayrı bir bağlamda başlayan bağımsız bir oturumdur. Kendi sistem talimatı vardır, sadece siz izin verdiğiniz araçlara erişir ve işi bitince size bir özet döner. Sizin konuşma geçmişinizi görmez; başlangıç bağlamında sistem talimatı, verilen görev, CLAUDE.md dosyaları ve önceden yüklenen skill'ler bulunur, sohbet geçmişi bulunmaz.
Ayrım pratikte tek soruya iner: çıktının tamamını görmek istiyor musunuz, yoksa sadece sonucunu mu. Bir metni kurum formatına çevirmek istiyorsanız skill yazın; çıktıyı görmek istersiniz. Kırk dosyayı tarayıp uymayanları listelemek istiyorsanız agent yazın; kırk dosyanın içeriği değil, liste lazım.
İkinci soru araç kısıtıdır. Agent'ta hangi araçlara erişileceğini dosyada yazarsınız. Bir denetim işinde yazma yetkisini hiç vermemek, "lütfen dosyaları değiştirme" demekten daha güvenlidir.
Skill nasıl kurulur
Skill bir klasör ve içinde SKILL.md adlı tek bir dosyadır. Klasörün adı komutun adı olur.
Sadece sizde çalışsın istiyorsanız kişisel klasöre koyarsınız: ~/.claude/skills/<ad>/SKILL.md. Ekibin tamamı kullansın istiyorsanız projenin içine koyar ve depoya gönderirsiniz: .claude/skills/<ad>/SKILL.md. İkincisi çoğu kurumsal işte doğru olanıdır; skill'i depoya koyduğunuz an kurumun ortak bilgisi haline gelir.
Dosyanın başındaki YAML bloğunda tek önemli alan description. Claude skill'i otomatik çağırıp çağırmayacağına bu satıra bakarak karar verir, o yüzden "ne yapar" ve "ne zaman kullanılır" bilgisini birlikte yazın. Diğer alanların hepsi isteğe bağlıdır.
Aşağıdaki örnek gerçek bir iş üzerine kurulu: kurumsal girişim programına gelen başvuruları şirketin standart değerlendirme formatına indirmek.
--- ~/.claude/skills/basvuru-ozeti/SKILL.md ---
---
name: basvuru-ozeti
description: Girisim basvurusunu sirketin standart
degerlendirme formatina cevirir. Kullanici bir basvuru
metni, sunum ya da form ciktisi verip ozet istedigi
zaman kullan.
allowed-tools: Read Glob Grep
---
Sana verilen basvuruyu su basliklarla ozetle:
1. Girisimin tek cumlelik tanimi
2. Cozdugu problem ve problemin kim icin oldugu
3. Urunun bugunku olgunlugu: fikir, prototip,
pilot, satista
4. Bizim icin somut kullanim alani, tek cumle
5. Basvuruda bulunmayan ve sorulmasi gereken
uc bilgi
Kurallar:
- Basvuruda yazmayan bir bilgiyi ekleme.
- Rakam varsa basvurudaki haliyle yaz, yuvarlamalar.
- Bilinmeyen alani "belirtilmemis" diye birak.
- Yorum ve tavsiye yazma, sadece ozetle.Dosyayı kaydettiğiniz an skill hazırdır. Oturumda /basvuru-ozeti yazarak doğrudan çağırabilir ya da bir başvuru metni yapıştırıp özet isteyerek Claude'un kendiliğinden çağırmasını bekleyebilirsiniz. Yüklü skill'leri görmek için /skills komutunu çalıştırın; liste her skill'in nereden geldiğini de gösterir.
İki ayrıntı işi kolaylaştırır. Birincisi, SKILL.md'yi kısa tutun; dokümantasyon 500 satırın altında kalmasını öneriyor, uzun referans metinlerini aynı klasöre ayrı dosya olarak koyup SKILL.md içinden bağlantı verirsiniz. İkincisi, açıklama alanı sınırsız değil; description metni belli bir uzunluktan sonra kırpılıyor, o yüzden asıl kullanım durumunu ilk cümleye yazın.
Agent nasıl kurulur
Agent tek bir markdown dosyasıdır, klasör gerekmez. Kişisel için ~/.claude/agents/<ad>.md, proje için .claude/agents/<ad>.md.
Burada iki alan zorunludur: name ve description. Gövdeye yazdığınız her şey agent'ın sistem talimatı olur. tools alanı erişebileceği araçları, model alanı hangi modelle çalışacağını belirler.
Aynı işin denetim tarafını agent yapalım: klasördeki bütün başvuruları tarayıp eksik alanları listelesin, hiçbir dosyaya dokunmasın.
--- .claude/agents/basvuru-denetcisi.md ---
---
name: basvuru-denetcisi
description: Basvuru klasorundeki tum dosyalari tarar,
eksik ve tutarsiz alanlari listeler. Toplu kontrol
gerektiginde kullan.
tools: Read, Glob, Grep
model: haiku
maxTurns: 20
---
Sen bir basvuru denetcisisin. Dosyalari sadece okursun,
hicbirini degistirmezsin.
Sana verilen klasordeki her basvuru dosyasi icin kontrol et:
- girisimin adi ve iletisim bilgisi var mi,
- cozdugu problem yazilmis mi,
- urun olgunlugu belirtilmis mi,
- talep edilen destek yazilmis mi.
Ciktin tek bir tablo olsun:
dosya adi | eksik alanlar | tek cumlelik not
Tabloyu eksik alani en cok olandan basla.
Dosyalarin icerigini tek tek aktarma,
sadece tabloyu don. Eksik olmayan dosyalari
tabloya yazma, sayilarini en altta topla.Çağırmak için sohbette @agent-basvuru-denetcisi yazıp klasörü verirsiniz. Claude uygun gördüğü yerde kendiliğinden de devreye alabilir; description satırı bunun için var.
Model seçimi burada bilinçli. Kırk dosyada tek tek alan kontrolü yapmak muhakeme değil, tarama işidir; ucuz ve hızlı modelle yapılır. Asıl değerlendirmeyi kendiniz, güçlü modelle yaparsınız.
Bir not: /agents komutu artık agent oluşturma sihirbazı açmıyor, size dosyayı doğrudan düzenlemenizi ya da Claude'dan yazmasını istemenizi hatırlatıyor. En pratik yol ikincisidir.
Bana bir Claude Code agent dosyasi yaz.
Gorev: [agentin yapacagi isi tek cumleyle yazin]
Kosullar:
- sadece okuma yapsin, dosya degistirmesin,
- ciktisi tek tablo olsun, uzun metin dondurmesin,
- name ve description alanlarini doldur,
- description tek cumle olsun, ne zaman
cagrilacagini soylesin.
Dosyayi .claude/agents/ altina kaydet
ve yolunu bana yaz.Bu promptu bir kez çalıştırıp çıkan dosyayı elle düzeltmek, dosyayı sıfırdan yazmaktan hızlıdır. Dosya düz metin olduğu için yanlış giden her şeyi tek satır değiştirerek düzeltirsiniz.
İkisini birlikte çalıştırmak
Asıl kazanç ikisini zincirlediğinizde çıkar. Denetçi agent klasörü tarar ve eksikleri tabloya döker. Siz eksiksiz dosyaları alıp skill ile tek tek özetlersiniz. Elli başvuruluk bir dönemde bu iki dosya, bir kişinin iki gününü yarım güne indirir.
Zincirin doğru yönü de önemlidir. Denetim önce gelir, özet sonra. Eksik bir başvuruyu özetlemek boş bir özet üretir ve o özet listede diğerleriyle aynı görünür.
Nerede durmak gerekir
Üç sınır var.
Birincisi, bunları kişi denetimine çevirmeyin. Bir denetçi agent'ı dosya eksiklerini bulmak için yazılır, çalışanın kaç hata yaptığını saymak için değil. Çıktıyı kişiye bağlayan bir tabloya dönüştürdüğünüz an ekip bu araçları kullanmayı bırakır.
İkincisi, agent'a yazma yetkisini alışkanlıkla vermeyin. tools alanına ne yazarsanız agent onu yapar. Okuma yeten bir işte yazma yetkisi vermek, ileride sessizce değişmiş bir dosyayla karşılaşmak demektir. Yazma gereken işlerde de değişikliği önce ayrı bir dalda deneyin.
Üçüncüsü, model her iki yapıda da uydurabilir. Skill'deki "yazmayan bir bilgiyi ekleme", agent'taki "sadece tabloyu don" satırları bunun için var ama garanti değil. Karara girecek her satırı kaynak dosyadan gözünüzle doğrulayın.
Son olarak Claude Code hızlı değişen bir araç. Alan adları ve komutlar sürümle birlikte güncelleniyor; bir şey beklediğiniz gibi çalışmazsa önce /skills çıktısına ve güncel dokümantasyona bakın.
Bu hafta ne yapabilirsiniz
Son bir ayda Claude'a en az üç kez yazdığınız talimatı bulun. Muhtemelen bir format tarifi ya da bir kontrol listesidir.
O talimatı ~/.claude/skills/ altında bir klasöre SKILL.md olarak kaydedin. Beş dakika sürer. Bir hafta kullanın, her kullandığınızda eksik kalan bir satırı ekleyin.
İkinci hafta, çıktısını okumadığınız ama sonucuna baktığınız bir işi seçin ve onun için tek bir agent yazın. Araç listesini olabilecek en dar halde tutun.
Ayın sonunda iki dosyanız olur ve ikisi de düz metindir. Çalışmayanı silersiniz, çalışanı depoya koyarsınız.
Bir yapay zeka aracını gerçekten kullanmaya başladığınız an, ona her seferinde ne yapacağını anlatmayı bırakıp bir kez yazıp kaydettiğiniz andır.