Neredeyse bir yıldır ekibimle birlikte tamamen Claude Code içinde yaşıyoruz. "Bir sprint deneriz" gibi değil, "CI'ımız bunun üzerinde çalışıyor ve pull request şablonlarımız aslında Claude prompt'ları" kıvamında bir yaşam. Bu yolculuğun bir yerinde hırs yaptım ve ekibimize özel bir skill seti hazırladım: `code-review`, `debug-protocol` ve `team-conventions`. `.claude/skills/` klasöründe duruyorlar, harika görünüyorlar, hayal edebileceğiniz tüm YAML frontmatter'ları içeriyorlar — ve ilk birkaç hafta boyunca çoğunlukla öylece durdular. Sessiz. Kimse umursamadı. Sanki sadece yangın çıktığında çalan bir yangın alarmı gibi.
En sinir bozucu kısım şuydu: skill dosyaları doğruydu. Yollar doğruydu. Markdown temiz ve belgelenmişti. Ama skill bir türlü devreye girmiyordu. Aylarca kafa yorduktan sonra gerçeği öğrendim: sorun hiçbir zaman skill'de değildi. Sorumun bendeydi.
"Skill Devreye Girmedi" Tuzağı
Claude Code skill yapılandırmasının derinliklerine henüz inmemiş olanlar için kısa özet: skill'ler `.claude/skills/
```markdown
---
name: code-reivew
description: Use when the user asks for a code review.
---
```
Bu masum görünüyor. Ama Claude Code'un bir skill'i devreye sokup sokmayacağına karar verme şekli aslında şu: *her* skill açıklamasını okuyor, hepsini sistem prompt'una karıştırıyor ve mevcut isteğinizi bunlarla eşleştiriyor. Yani skill aktivasyonu tamamen bir niyet eşleştirme oyunu. Eğer açıklamanızı birebir anahtar kelime tetikleyici gibi yazdıysanız, oyun daha baştan kaybedilmiştir.
Üç hafta boyunca Claude'u suçladık, API'yi suçladık, ayın evrelerini suçladık. Sonra resmi skill dokümantasyonunu [docs.anthropic.com/en/docs/claude-code/skills](https://docs.anthropic.com/en/docs/claude-code/skills) gerçekten okuduk ve rahatsız edici bir şeyi fark ettik: model tembel değil, sadece lafından çıkmıyor. O sadece açıklamadan *alakalı olduğunu anladığı* bir skill'i devreye sokabiliyor. Ve bizim açıklamalarımız berbattı.
Asıl Sorun: Açıklama Uyumsuzluğu
Anlamamız çok uzun süren şey şu: **skill bir boşlukta var olmuyor.** Diğer skill'lerle, yerleşik davranışlarla ve Claude'un bağlamındaki her ne varsa onunla birlikte bir çorbanın içinde yaşıyor. Bir geliştirici bir şey yazdığında Claude hızlı bir zihinsel hesap yapıyor: *"Bu herhangi bir skill açıklamasıyla eşleşiyor mu? Birden fazla eşleşme varsa hangisi en yakın? Yoksa doğrudan mı cevap versem?"*
Eğer skill açıklamanız çok dar, çok muğlak ya da fazla anahtar kelime odaklıysa Claude onu ıskalar. Ve eğer açıklamanız başka bir skill'le ya da yerleşik bir komutla çakışıyorsa Claude yanlış olanı seçer. SKILL.md dosyanızdaki kod asla sorun değildir. Metadata sorundur.
Gerçek ekipleri en çok vuran üç durum şunlar:
Senaryo 1: Uyuklayan Code Review Skill'i
`code-review` skill'ini dünyanın en bariz açıklamasıyla yazdım: *"Use when the user asks for a code review."* Basit, değil mi? Yanlış.
Geliştiricilerimiz asla "code review" demiyordu. Diyorlardı ki:
- "PR'ıma bir bakar mısın, şöyle bir kontrol et?"
- "Şu diff'e bakar mısın, bir şeyler ters."
- "Bunu göndermeden önce bir gözden geçir."
- "Bu fazla mı mühendislik olmuş?"
Sence hangisi skill'i tetikledi? Hiçbiri. Claude bu mesajlara skill'i devreye sokmadan doğrudan cevap verdi, çünkü "code review" ifadesi mesajın hiçbir yerinde geçmiyordu. Çözüm utanç verici derecede basitti. Açıklamayı birebir değil, anlamsal olarak yeniden yazdık:
```yaml
description: >-
Use for reviewing code changes, pull requests, diffs, or merge requests.
Trigger on phrases like "review this PR", "check my diff", "sanity-check
this code", "is this good to merge", or "look at these changes".
Not for general debugging or explaining code.
```
Ayrıca bir "Şunun için değildir" maddesi ekledik. Bu tek değişiklik skill'in devreye girme sıklığını yaklaşık %80 artırdı. Claude Code skill'leri temel olarak prompt mühendisliğidir — ve prompt da açıklamanın kendisidir.
Senaryo 2: Bizi Hayaletleyen Debug Protokolü
`debug-protocol` skill'imiz ekibin kahramanı olacaktı. Hata üretmek, logları kontrol etmek, durumu incelemek ve çözüm önermek için adım adım yapılandırılmış bir süreç. Çok güzeldi. Ama bir türlü devreye girmedi.
Neden mi? Çünkü açıklama "debug" kelimesiyle başlıyordu. Ve "debug" Claude Code'un her yerinde var. Yerleşik bir debug bayrağı var, sistem seviyesinde hata ayıklama davranışı var ve aynı dizinde muhtemelen benzer dili kullanan üç skill daha var. Geliştiricilerimiz "şu başarısız testi debug etmeme yardım et" dediğinde Claude'un dört olası eşleşmesi vardı ve genel prompt alaka düzeyi en güçlü olanı seçti — genellikle bizim özel skill'imizi değil, yerleşik davranışı.
Buradan iki ders çıkardık:
1. **Skill'lere benzersiz, spesifik isimler verin.** `debug-protocol` çok jenerik. `sentry-repro-protocol` ya da `memory-leak-hunt` daha iyi olurdu. Jenerik isimler, jenerik niyet tarafından ezilir.
2. **Manuel geçersiz kılmayı kullanın.** Claude Code'da bir skill'i çalıştırmak için her zaman `/debug-protocol` yazabilirsiniz. Bunu ekibimizin konvansiyonlarına ekledik ve birden skill ölü değilmiş gibi oldu — sadece doğrudan bir davetiye istiyordu.
Ama asıl derin içgörü şuydu: model yanlış skill'i seçti çünkü *biz* bir çakışma tasarlamıştık. Birbirine benzeyen iki skill'iniz varsa Claude tahmin yürütür. Açıklamaları birbirini eleyecek şekilde yazın. Claude'a açıkça söyleyin: "Sunucu loglarıyla ilgili bir sorun olduğunda genel hata ayıklama davranışı yerine bunu kullan."
Senaryo 3: Her Şeyi Unutan Takım Konvansiyonları Skill'i
En tuhaf hata `team-conventions` skill'imizden geldi. Commit mesajları, branch isimlendirme ve PR açıklamaları için kuralları içeriyordu. Oturumun başında harika çalışıyor, yaklaşık 20. mesajdan sonra duruyordu. Modelin "unuttuğunu" varsaydık. Ama bu bir hafıza hatası değildi — bağlam sorunuydu.
Claude Code tüm skill açıklamalarını sistem prompt'una döker. Uzun açıklamalar bağlam yer. Sohbet büyüdükçe sistem, yer açmak için sistem prompt'unu sıkıştırmaya veya kırpmaya başlar. Bizim `team-conventions` açıklamamız bir duvar yazısıydı — üç paragraf kurumsal jargon. Bağlam penceresi daraldığında elden çıkarılan ilk şey o oldu.
Çözüm, açıklamayı iki üç cümleye indirmek ve asıl kuralları skill klasörünün içindeki referanslı bir dosyaya taşımaktı. Artık açıklama sadece bir yön tabelası: *"Commit mesajı, branch isimlendirme ve PR kuralları için kullan. Tam kurallar convention.md dosyasında."* Model bunu tutabiliyor ve skill devreye girdiğinde tam dosyayı okuyor. Ayrıca skill olmayan kuralları da ekip geneli talimatlar için daha güvenilir şekilde yüklenen `CLAUDE.md` proje hafıza dosyamıza taşıdık.
Bugünden Başlayabileceğiniz Pratik Çözümler
Haftalarca süren acıdan sonra, ilk gün birinin bana vermesini dilediğim kontrol listesi şu:
Açıklamayı Arama Sorgusu Gibi Düşünün
Birisi skill açıklamanızı aratsa, gerçekten istediğiniz şeyle eşleşir miydi? Açıklamayı anlamsal bir arama dizesi gibi yazın. Eş anlamlılar, ekibinizin gerçekten kullandığı ifadeler ve açık dışlamalar ekleyin. Modelin "ne demek istediğinizi bildiğini" varsaymayın. O sadece yazdığınızı bilir.
Skill Dosyalarını Kısa Tutun
500 satırlık bir skill dosyası bir yüktür. Bağlam yer, kırpılır ve güvenilmez hale gelir. SKILL.md dosyasını *ne zaman devreye gireceğine* odaklayın. Ağır detayları yardımcı dosyalara taşıyın — `prompt.md`, `criteria.md`, `checklist.md` — Claude bunları skill aktifleştikten sonra okusun.
Olumsuz Örnekler Ekleyin
Kulağa ters geliyor ama işe yarıyor. Açıklamada skill'in *neye yaramadığını* açıkça belirtin. *"Genel mimari tartışmaları için değildir. Sözdizimi soruları için değildir."* yazın. Bu, yanlış pozitifleri azaltır ve modelin benzer skill'ler arasında ayrım yapmasına yardımcı olur. Olumsuz örnekler kutudaki en keskin araçtır.
Manuel Geçersiz Kılma İçin `/` Kullanın
Metadata'nız ne kadar iyi olursa olsun, otomatik algılamanın başarısız olduğu bir an mutlaka olacaktır. Ekibinize zorla aktifleştirmek için `/skill-adı` yazmalarını öğretin. Bu bir başarısızlık değil — bir yedek plandır. En akıllı ekipler otomatik skill tetiklemeyi bir bağımlılık değil, bir kolaylık olarak görür.
Diğer Kodlar Gibi Debug Edin
Claude Code'un `--debug` bayrağı var. Kullanın. Oturum başında birleştirilen sistem prompt'unu inceleyin ve skill açıklamalarınızın gerçekten orada olduğunu doğrulayın. Bu basit görünüyor ama biz YAML frontmatter bloklarından birindeki sondaki virgülün tüm dosyayı sessizce geçersiz kıldığını keşfettik. Skill hiç yüklenmemişti. Niyet eşleştirme yüzünden değil — bir ayrıştırma hatası yüzünden. Debug çıktısı on saniyede yakaladı.
Farklı İfade Biçimleriyle Test Edin
Dokümantasyonunuzdaki birebir ifadeyi test etmekle kalmayın. Yeni bir oturum açın ve ekibinizin gerçekten konuştuğu dağınık, insani, muğlak şekilde yazın. "Bu PR patlayacak mı?" ifadesi, açıklamalarınız doğruysa review skill'inizi tetiklemeli. Tetiklemiyorsa açıklamanız henüz yeterince iyi değil demektir.
SSS
Skill'im yeni oturumda çalışıyor ama sonra devreye girmiyor, neden?
Bu neredeyse her zaman bağlam kırpmasıdır. Uzun skill açıklamaları sohbet büyüdükçe sistem prompt'undan düşer. Açıklamayı inceltin veya bir referans dosyasıyla yeniden yapılandırın. Bu bir hafıza sorunu değil — bir alan sorunu.
Skill açıklamalarında anahtar kelime mi yoksa doğal dil mi daha iyi?
İkisi de doğru oranda. Niyetin tek cümlelik anlamsal bir açıklamasıyla başlayın ("kod değişikliklerini incelemek için kullan"), ardından yaygın tetikleyici ifadelerin listesini ekleyin. Sadece anahtar kelimeye güvenmeyin, ama o kadar soyut da olmayın ki hiçbir şey eşleşmesin.
Özel bir skill, Claude Code'un yerleşik davranışını geçersiz kılabilir mi?
Doğrudan kılamaz. Yerleşik davranışlar, skill'inizin geçersiz kılamayacağı bir seviyede bağlıdır. Ama skill açıklamanızı ekibinizin gerçek durumuna daha spesifik ve alakalı hale getirerek eşleşmeyi kazanabilirsiniz. Takıldıysanız `/skill-adı` ile zorlayın veya isteği yerleşik yolun artık uymayacağı şekilde yeniden ifade edin.
Skill dosyamın yüklenip yüklenmediğini nasıl anlarım?
`claude --debug` çalıştırın ve çıktıyı inceleyin. Skill'lerinizin sistem prompt birleştirmesinde listelendiğini görmelisiniz. Skill'iniz listelenmiyorsa YAML frontmatter'ı, klasör yapısını ve dosya adını kontrol edin. Geçerli bir `SKILL.md` olmayan bir skill klasörü sadece bir dekorasyondur.
Özet
İşte rahatsız edici gerçek: bir skill devreye girmediğinde, sorun neredeyse hiçbir zaman skill dosyası değildir. Sorun, insan niyetini — "işimi gözden geçir, kurallarımıza uy, bu hatayı anlaştığımız şekilde düzelt" — Claude'un gerçekten okuduğu metadata'ya ne kadar iyi çevirdiğinizdir. Mesele daha iyi kod yazmak değil. Mesele daha iyi *yön tabelaları* yazmak.
Sessiz kalan skill'lerden dolayı hayal kırıklığına uğradıysanız markdown'u sıfırdan yazmayın. Açıklamalarınızı yeniden yazın. Gerçek örnekler ekleyin. Dışlamalar ekleyin. Dosyayı kısa tutun. Ve her şey başarısız olduğunda, doğrudan `/skill-adı` yazın ve gününüze devam edin.
Skill bozuk değil. İster inanın ister inanmayın, Claude da bozuk değil. Biz sadece modelin, odanın karşısından belli belirsiz bir baş selamıyla partiye davet edilemeyeceğini unuttuk.
Yorumlar (0)
Henüz yorum yapılmamış. İlk yorumu siz yapın!
Yorum Yap