Claude Code’u geliştirirken öğrendiklerimiz: Skills’ü nasıl kullanıyoruz

• Claude Code’da Skills, en sık kullanılan genişletme noktalarından biri ve Anthropic, içeride yüzlerce skill’i gerçekten işleterek biriktirdiği pratik deneyimi paylaşıyor
• Skill’ler basit Markdown dosyaları değil; script, asset, veri ve daha fazlasını içeren klasör yapıları ve ajanların keşfedip kullanabileceği bir biçimde tasarlanıyor
• Library reference, ürün doğrulama, veri analizi, kod scaffolding, CI/CD gibi 9 skill kategorisine ayrılıyor; iyi bir skill tek bir kategoriye temiz biçimde oturmalı
• Skill yazarken Gotchas bölümü, dosya sisteminden yararlanma, aşamalı ifşa (Progressive Disclosure) ve veri saklama gibi pratik ipuçları kritik önem taşıyor
• Organizasyon ölçeği büyüdüğünde, skill’leri iç plugin marketplace üzerinden dağıtmak ve kullanım ölçüm hook’larıyla etkisini izlemek öneriliyor

---

Skills nedir

• Skills hakkındaki yaygın yanlış anlama, bunun “sadece bir Markdown dosyası” olduğu yönünde; oysa gerçekte script, asset, veri ve benzerlerini içeren bir klasör yapısıdır
• Ajan bu klasörü gezebilir, içeriğini keşfedebilir ve üzerinde işlem yapabilir
• Claude Code’da Skills, çeşitli yapılandırma seçenekleri sunar ve dinamik hook’ların kaydını da mümkün kılar
• En ilginç skill’ler, bu yapılandırma seçeneklerini ve klasör yapısını yaratıcı biçimde kullananlardır

Skill’lerin 9 kategorisi

• İçeride kullanılan tüm skill’ler sınıflandırıldığında, tekrar eden bazı kategoriler etrafında kümelendikleri görülüyor
• İyi bir skill tek bir kategoriye net biçimde oturur; kafa karıştırıcı skill’ler ise birden fazla kategoriye yayılır

• 1. Library & API Reference

  • Library, CLI ve SDK’lerin doğru kullanımını anlatan skill’ler
  • Sadece iç library’ler değil, Claude Code’un sık hata yaptığı genel amaçlı library’ler de buna dahil
  • Çoğu zaman referans kod snippet klasörü ve uyarılar (gotchas) listesi içerir
  • Örnekler: billing-lib (iç ödeme library’sinin edge case’leri), internal-platform-cli (iç CLI wrapper’ının tüm alt komutları ve kullanım örnekleri), frontend-design (tasarım sisteminin daha iyi uygulanması)

• 2. Product Verification

  • Kodun doğru çalışıp çalışmadığını test etme ve doğrulama yöntemlerini anlatan skill’ler
  • Sıklıkla Playwright, tmux gibi harici araçlarla birlikte kullanılır
  • Claude’un çıktısının doğruluğunu güvenceye almak için çok faydalıdır; mühendislerin gerekirse bir haftayı ayırıp doğrulama skill’lerini mükemmelleştirmesi değerlidir
  • Claude’un çıktıyı video olarak kaydetmesi veya her adımda duruma ilişkin programatik assertion’ların zorunlu kılınması önerilir
  • Örnekler: signup-flow-driver (kayıt → e-posta doğrulama → onboarding akışını headless browser ile yürütür), checkout-verifier (Stripe test kartıyla ödeme arayüzünü çalıştırıp fatura durumunu doğrular), tmux-cli-driver (TTY gerektiren etkileşimli CLI testleri için)

• 3. Data Fetching & Analysis

  • Veri ve izleme stack’ine bağlanan skill’ler
  • Credential içeren veri getirme library’leri, belirli dashboard ID’leri ve genel workflow kılavuzları içerebilir
  • Örnekler: funnel-query (kayıt → aktivasyon → ödeme funnel’ı için gerekli event’ler ve canonical user_id içeren tablolar), cohort-compare (iki kohortun retention/dönüşüm oranlarını karşılaştırır ve istatistiksel anlamlılığı işaretler), grafana (data source UID’leri, cluster adları, problem → dashboard eşleme tablosu)

• 4. Business Process & Team Automation

  • Tekrarlayan workflow’ları tek komutla otomatikleştiren skill’ler
  • Genellikle nispeten basit talimatlardan oluşur ama başka skill’lere veya MCP’ye karmaşık bağımlılıklar içerebilir
  • Önceki çalıştırmaların sonuçlarını log dosyasında saklamak, modelin tutarlılığı korumasına ve geçmiş çalıştırmaları yansıtmasına yardımcı olur
  • Örnekler: standup-post (ticket tracker, GitHub etkinliği ve Slack’i birleştirip biçimli standup üretir), create-ticket (şema zorlaması ve oluşturma sonrası workflow), weekly-recap (merge edilen PR’ler + kapanan ticket’lar + deploy’ları özet yazıya dönüştürür)

• 5. Code Scaffolding & Templates

  • Kod tabanındaki belirli özellikler için framework boilerplate’i üreten skill’ler
  • Birleştirilebilir script’lerle birlikte kullanılabilir; yalnızca kodla tam karşılanamayan doğal dil gereksinimleri olduğunda özellikle faydalıdır
  • Örnekler: new-framework-workflow (anotasyonlar içeren yeni servis/workflow/handler scaffold’u), new-migration (migration dosyası şablonu ve dikkat edilmesi gerekenler), create-app (kimlik doğrulama, loglama ve deploy ayarları hazır bağlı yeni iç uygulama)

• 6. Code Quality & Review

  • Organizasyon içinde kod kalitesini zorunlu kılan ve code review’a yardımcı olan skill’ler
  • Azami sağlamlık için deterministik script’ler veya araçlar içerebilir
  • Hook ya da GitHub Action’ın bir parçası olarak otomatik de çalıştırılabilir
  • Örnekler: adversarial-review (yeni bakış açısına sahip alt ajan eleştirir → düzeltir → yorumlar nitpick düzeyine inene kadar tekrarlar), code-style (Claude’un varsayılan olarak iyi yapamadığı kod stilini zorlar), testing-practices (testlerin nasıl yazılacağını ve neyin test edileceğini anlatır)

• 7. CI/CD & Deployment

  • Kod tabanı içinde kodu çekme, push etme ve deploy etme işlerini yapan skill’ler
  • Veri toplamak için başka skill’lere başvurabilir
  • Örnekler: babysit-pr (PR izleme → flaky CI’yı yeniden deneme → merge conflict çözme → auto-merge etkinleştirme), deploy-service (build → smoke test → aşamalı trafik rollout’u → hata oranı karşılaştırması → regresyon durumunda otomatik rollback), cherry-pick-prod (izole worktree → cherry-pick → conflict çözümü → şablon PR oluşturma)

• 8. Runbooks

  • Belirtiyi (Slack thread’i, alarm, hata imzası vb.) girdi olarak alıp çok araçlı inceleme yapan ve yapılandırılmış rapor üreten skill’ler
  • Örnekler: service-debugging (belirti → araç → sorgu kalıbı eşlemesi), oncall-runner (alarmları getirir → yaygın nedenleri kontrol eder → sonucu biçimlendirir), log-correlator (request ID ile ilişkili tüm sistem loglarını toplar)

• 9. Infrastructure Operations

  • Günlük bakım ve operasyon prosedürlerini yürüten, yıkıcı işlemler için guardrail’ler içeren skill’ler
  • Mühendislerin kritik operasyonlarda best practice’leri izlemesini kolaylaştırır
  • Örnekler: resource-orphans (sahipsiz Pod/volume bulma → Slack bildirimi → bekleme süresi → kullanıcı onayı → kademeli temizleme), dependency-management (organizasyonun dependency onay workflow’u), cost-investigation (storage/egress maliyet sıçramalarının nedenini araştırmak için bucket ve sorgu kalıpları)

Skill yazma ipuçları

• Bariz olanı yazmayın

  • Claude Code, kod tabanı hakkında zaten çok şey bilir ve kod yazımı konusunda temel görüşlere sahiptir
  • Bilgi odaklı bir skill hazırlıyorsanız, Claude’un genel düşünme biçiminden sapmasını sağlayacak bilgilere odaklanmalısınız
  • frontend-design skill’i buna iyi bir örnektir; Anthropic mühendisleri bunu müşterilerle tekrar tekrar çalışarak Claude’un tasarım sezgisini geliştirmek için oluşturmuş, Inter fontu ve mor degrade gibi tipik kalıplardan kaçınacak şekilde düzenlemiştir

• Gotchas bölümü oluşturun

  • Tüm skill’lerde en yüksek sinyal değerine sahip içerik Gotchas bölümüdür
  • Bu bölüm, Claude’un skill kullanırken sık karşılaştığı başarısızlık noktaları üzerinden biriktirilmelidir
  • Zaman içinde bu gotchas listesinin sürekli güncellenmesi idealdir

• Dosya sistemini ve aşamalı ifşayı kullanın

  • Skill bir klasör olduğundan, tüm dosya sistemini bağlam mühendisliği ve aşamalı ifşa aracı olarak değerlendirmek gerekir
  • Claude’a skill içinde hangi dosyaların olduğunu söylerseniz, bunları uygun anda okur
  • En basit biçim: ayrıntılı fonksiyon imzaları ve kullanım örneklerini references/api.md gibi ayrı bir Markdown dosyasına ayırmak
  • Nihai çıktı Markdown ise, assets/ klasöründe şablon dosyaları da bulunabilir
  • Referans, script ve örnek klasörleri Claude’un çalışma verimliliğini artırır

• Claude’u aşırı kısıtlamayın

  • Claude talimatlara uymaya çalışır; ancak skill’ler yüksek yeniden kullanılabilirliğe sahip olduğundan aşırı spesifik talimatlar konusunda dikkatli olunmalıdır
  • Gerekli bilgiyi verin ama duruma esnek biçimde uyum sağlayabileceği alan bırakın

• Setup sürecini tasarlayın

  • Bazı skill’lerde kullanıcıdan bağlam toplayan bir kurulum aşaması gerekir
  • Örneğin Slack’e standup gönderen bir skill, bunun hangi kanala gönderileceğini sormalıdır
  • İyi bir kalıp: kurulum bilgisini skill dizinindeki config.json dosyasında saklamak, yapılandırma yoksa ajanın kullanıcıya soru sorması
  • Yapılandırılmış çoktan seçmeli sorular sunmak için AskUserQuestion aracının kullanılması istenebilir

• Description alanı model içindir

  • Claude Code oturumu başlattığında, mevcut tüm skill’lerin description listesini oluşturur
  • Claude bu listeyi tarayarak “bu isteğe uygun bir skill var mı?” diye karar verir
  • Bu yüzden description alanı bir özet değil, bu skill’in ne zaman tetiklenmesi gerektiğinin açıklamasıdır

• Bellek ve veri saklama

  • Skill’lere veri saklayan bir bellek biçimi eklenebilir
  • Basit metin log dosyalarından JSON dosyalarına, hatta SQLite veritabanına kadar pek çok biçim mümkündür
  • Örnek: standup-post skill’i tüm geçmişi standups.log içinde saklarsa, sonraki çalıştırmada Claude bunu okuyup dünden beri neyin değiştiğini anlayabilir
  • Skill dizininde saklanan veriler, skill yükseltmesi sırasında silinebileceğinden ${CLAUDE_PLUGIN_DATA} adlı kararlı klasörde tutulmalıdır

• Script saklama ve kod üretimi

  • Claude’a verebileceğiniz en güçlü araçlardan biri kodun kendisidir
  • Script ve library sağlarsanız, Claude boilerplate’i yeniden kurmak yerine birleştirmeye (composition) odaklanabilir
  • Örnek: veri bilimi skill’ine event source’lardan veri çeken yardımcı fonksiyon library’si eklemek
  • Claude bu işlevleri birleştirerek anlık script’ler üretebilir ve “Salı günü ne oldu?” gibi karmaşık analizlerde kullanabilir

• On Demand Hooks

  • Skill, yalnızca çağrıldığında etkinleşen ve oturum süresince kalan hook’lar içerebilir
  • Her zaman çalıştırmak için ağır olan ama belirli durumlarda çok yararlı güçlü görüşlü hook’lar için uygundur
  • Örnekler:
    • /careful — rm -rf, DROP TABLE, force-push, kubectl delete işlemlerini PreToolUse matcher ile engeller; yalnızca production işlemlerinde etkinleştirilir
    • /freeze — belirli bir dizin dışındaki tüm Edit/Write işlemlerini engeller; debugging sırasında istenmeyen değişiklikleri önlemek için kullanışlıdır

Skill dağıtımı

• Skill’lerin büyük avantajlarından biri, tüm takımla paylaşılabilmeleridir
• İki paylaşım yöntemi vardır:
  • Skill’i repo’ya commit etmek (./.claude/skills altına)
  • Plugin’e dönüştürüp Claude Code Plugin marketplace’e yüklemek, ardından kullanıcıların bunu kurması

• Marketplace yönetimi

  • Küçük bir takımın az sayıda repo üzerinde çalıştığı durumlarda repo’ya commit etme yöntemi uygundur
  • Commit edilmiş skill’ler modelin bağlamına yavaş yavaş eklenir; ölçek büyüdüğünde iç plugin marketplace daha avantajlı hale gelir
  • Marketplace’e hangi skill’lerin gireceğine karar veren merkezi bir ekip yoktur; en faydalı skill’ler doğal olarak öne çıkar
  • Denemek istediğiniz bir skill varsa, bunu GitHub’daki sandbox klasörüne yükleyip Slack gibi kanallarda duyurabilirsiniz
  • Yeterli ilgi/çekim elde ettiğinde, skill’in sahibi bunu marketplace’e taşıyan bir PR açar
  • Kötü ya da yinelenen skill’ler kolayca üretilebildiğinden, yayın öncesi kürasyon mekanizması önemlidir

• Skill birleştirme (Composing Skills)

  • Skill’ler arasında bağımlılıklar gerekebilir (ör. dosya yükleme skill’i + CSV oluşturup yükleme skill’i)
  • Marketplace veya skill sisteminde bağımlılık yönetimi yerleşik olarak bulunmasa da, başka skill’lere adlarıyla referans verilirse, kurulu olmaları durumunda model bunları çağırır

• Skill ölçümü

  • Skill’lerin etkisini anlamak için, şirket içinde skill kullanımını PreToolUse hook ile log’larlar
  • Bu sayede popüler skill’ler veya beklenenden daha az tetiklenen skill’ler bulunabilir

Sonuç

• Skills, ajanlar için çok güçlü ve esnek bir araç; ancak hâlâ erken aşamada ve herkes en iyi kullanım biçimini birlikte keşfediyor
• Bu yazı kesin kurallar koyan bir rehber değil, sahada işe yarayan ipuçlarının derlemesi
• Skill’lerin çoğu birkaç satır ve tek bir gotcha ile başladı; Claude yeni edge case’lerle karşılaştıkça insanlar ekleme yaparak bunları sürekli iyileştiriyor

[xguru]

Bu aralar Anthropic’e bakınca hissettiğim şey, geliştiricilerin kendi deneyimlerini olabildiğince paylaşarak insanları ürünlerini daha iyi kullanmaya yönlendirmesi.

Sanki “yapay zeka çağının geliştirme ekosistemi işte böyle kuruluyor”u bizzat gösteren bir örnek gibi.