Geçen ay bir gün not defterimde "prompt-parcalari.txt" diye bir dosya olduğunu fark ettim. İçinde kopyalayıp yapıştırdığım paragraflar vardı: "Migration dosyalarını Flyway formatında yaz, tablo isimleri çoğul olsun, updated_at kolonunu unutma, testleri Testcontainers ile yaz..." Her yeni oturumda bu metni asistana tekrar tekrar veriyordum. Model zeki, orası tamam. Ama beni, ekibimi ve bizim işleri nasıl yaptığımızı her seferinde sıfırdan öğrenmesi gerekiyordu.
İşte o dosyayı sildiğim gün, Agent Skills ile ciddi ciddi uğraşmaya başladığım gündü.
Asıl Sorun Zekâ Değil, Hafıza
Bugünkü modellerin kod yazma becerisi konusunda pek tartışacak bir şey kalmadı. Takıldığımız yer başka: model sizin bağlamınızı bilmiyor. Hangi kütüphaneyi neden seçtiğinizi, deploy öncesi hangi kontrolleri yaptığınızı, code review'da en çok neye kızdığınızı bilmiyor.
Bunun için ilk akla gelen çözüm, projenin köküne bir CLAUDE.md ya da AGENTS.md koyup her şeyi oraya yazmak. Ben de öyle yaptım. Birkaç hafta sonra dosya 600 satırı geçmişti. Asistan sadece bir README düzeltmesi yapacak olsa bile migration kurallarımızı, Kafka topic isimlendirme standartlarımızı ve release sürecimizi okuyordu. Token ekonomisi yazısında bahsettiğim israfın ta kendisi: her istekte, ihtiyaç olmayan bilgiyi bağlam penceresine taşımak.
Skill'ler tam olarak bu noktada devreye giriyor.
Skill Dediğimiz Şey Aslında Bir Klasör
Anthropic'in geçen yıl ortaya attığı ve kısa sürede açık bir standarda dönüşen bu yapının güzel yanı, şaşırtıcı derecede sade olması. Bir skill; içinde SKILL.md dosyası bulunan bir klasörden ibaret. İsterseniz yanına script'ler, şablonlar veya referans dokümanlar da koyabiliyorsunuz.
SKILL.md dosyasının başında iki zorunlu alan var: name ve description. Altında da düz markdown ile yazılmış talimatlar. Ne özel bir DSL var ne de bir SDK. Bir junior'a iş anlatır gibi yazıyorsunuz.
İşin Sihri: Kademeli Yükleme
Beni asıl ikna eden kısım bu oldu. Oturum başladığında asistan tüm skill'lerin içeriğini okumuyor. Sadece isimlerini ve açıklamalarını görüyor; skill başına birkaç düzine token. Siz "şu tabloya yeni bir kolon ekleyelim" dediğinizde model açıklamalara bakıyor, migration skill'inin bu işle ilgili olduğunu anlıyor ve ancak o zaman SKILL.md dosyasının geri kalanını yüklüyor. Talimatlarda "isimlendirme kuralları için references/naming-conventions.md dosyasına bak" yazıyorsa, o dosya da ancak gerçekten gerektiğinde okunuyor.
Bunu bir kütüphane rafı gibi düşünebilirsiniz. Rafın önünden geçerken kitapların sırtlarını okursunuz, hepsini açıp baştan sona okumazsınız. İhtiyacınız olanı çekip alırsınız, belki içinden sadece bir bölümü okursunuz.
Pratikteki karşılığı şu: onlarca skill tanımlayıp bağlam penceresini neredeyse hiç şişirmeyebilirsiniz. 600 satırlık o dev dosya bizde artık 40 satıra indi, geri kalan her şey ilgili skill'in içine taşındı.
Gerçek Bir Örnek: Migration Skill'i
Ekipte kullandığımız skill'in sadeleştirilmiş hali aşağıda. Dikkat ederseniz talimatların çoğu "ne yap" kadar "neden" de anlatıyor. Bu bilinçli bir tercih; birazdan açacağım.
---
name: db-migration
description: Use when creating or modifying database schema - new tables, columns, indexes or Flyway migration files under src/main/resources/db/migration.
---
# Database Migration
## Kurallar
- Dosya adı: V{yyyyMMddHHmm}__{kisa_aciklama}.sql
(Timestamp kullanıyoruz çünkü paralel branch'lerde versiyon çakışması yaşadık.)
- Mevcut bir migration dosyasını ASLA düzenleme, yeni dosya oluştur.
(Production'da checksum hatası alırız.)
- Büyük tablolara index eklerken CREATE INDEX CONCURRENTLY kullan.
- NOT NULL kolon ekliyorsan önce nullable ekle, backfill yap, sonra constraint koy.
## Kontrol
Dosyayı yazdıktan sonra scripts/validate_migration.sh çalıştır.
İsimlendirme detayları için references/naming-conventions.md dosyasına bak.
Bu skill devredeyken bir oturumda neler olduğuna bakalım. Asistana "orders tablosuna cancelled_reason kolonu ekle, zorunlu olsun" diyorum. Model açıklamada "new columns" ifadesini görüyor ve skill'i yüklüyor. Kuralları okuyunca kolonu direkt NOT NULL olarak eklemek yerine işi üç adıma bölüyor: önce nullable kolon, sonra mevcut kayıtlar için bir varsayılan değer, en son constraint. Ardından dosya adını timestamp formatında veriyor, validasyon script'ini çalıştırıyor ve script bir yazım hatası yakalayınca dosyayı kendisi düzeltiyor.
Skill'den önce aynı istek bana tek satırlık bir ALTER TABLE olarak dönüyordu. Kâğıt üzerinde doğru, ama milyonlarca satırlık bir tabloda production'ı kilitleyebilecek bir satır. Aradaki fark modelin zekâsında değil, ona verdiğim bağlamda.
Description'ı Hafife Almayın
İlk yazdığım skill'in açıklaması "Veritabanı işlemleri için yardımcı" gibi bir şeydi. Sonuç? Skill neredeyse hiç devreye girmedi. Asistan yeni kolon eklerken bildiği genel yolu izledi, benim kurallarımı hiç açmadı.
Sebebi basit: model skill'i yükleyip yüklememeye sadece o açıklamaya bakarak karar veriyor. Açıklama belirsizse karar da belirsiz oluyor. "Ne zaman kullanılmalı" sorusuna somut cevap veren, dosya yollarını ve anahtar kelimeleri içeren bir açıklama yazdığımda durum tamamen değişti. Şimdi bir skill yazarken en çok zamanı gövdeye değil, o tek satıra harcıyorum.
Skill mi, CLAUDE.md mi, MCP mi?
Bu üçü sık sık birbirine karıştırılıyor. Benim kafamdaki ayrım şöyle:
- CLAUDE.md / AGENTS.md: Her görevde geçerli olan, kısa ve genel kurallar. "Bu proje Java 21 kullanıyor, testleri şu komutla çalıştır" gibi.
- Skill: Belirli bir iş akışına dair uzmanlık. Migration yazmak, incident raporu hazırlamak, yeni bir endpoint'i standartlara uygun eklemek.
- MCP: Dış dünyaya erişim. Veritabanına sorgu atmak, Jira'dan ticket okumak, bir API'yi çağırmak.
Kısacası MCP asistana el veriyor, skill ise o eli nasıl kullanacağını öğretiyor. İkisi birbirinin alternatifi değil, çoğu zaman birlikte çalışıyorlar.
Birkaç Ay Sonra Öğrendiklerim
Kısa tutun. Model zaten zeki. Ona Flyway'in ne olduğunu anlatmanıza gerek yok. Sadece sizin projenize özgü olanı yazın. Bir skill gövdesi birkaç yüz satırı geçmeye başladıysa, detayları references/ altına taşımanın vakti gelmiş demektir. Böylece ana dosya okunabilir kalıyor, detaylar da sadece gerektiğinde yükleniyor.
"Neden"i yazın. "Mevcut migration'ı düzenleme" kuralını gerekçesiyle yazdığımda, asistan benzer ama kurallarda yazmayan durumlarda da doğru kararı vermeye başladı. Gerekçe, kuralın genellenmesini sağlıyor.
Deterministik işleri script'e bırakın. Dosya adı formatını doğrulamak gibi kesin sonucu olan işleri modele "dikkat et" diyerek değil, bir script ile yaptırın. Model script'i çalıştırıyor, sonuca bakıyor, gerekirse düzeltiyor.
Gerçek bir görevle test edin. Skill'i yazdıktan sonra temiz bir oturum açıp gerçekten o işi yaptırın. Skill tetiklendi mi, talimatlara uyuldu mu, bakın. Ben ilk denemelerimde yazdığım kuralların yarısının belirsiz olduğunu böyle fark ettim.
Repo'ya koyun, review'dan geçirin. Skill'ler .claude/skills/ altında projeyle birlikte yaşadığında, ekipteki herkesin asistanı aynı kuralları biliyor. Bir kural değiştiğinde de pull request açıyoruz, tıpkı kod gibi.
Kaynağını bilmediğiniz skill'i kurmayın. İnternette hazır skill paketleri çoğalıyor. Unutmayın, skill'ler script çalıştırabiliyor. Başkasının yazdığı bir skill'i kurmadan önce içini, özellikle scripts/ klasörünü mutlaka okuyun. Bir npm paketinden daha az dikkat etmeniz için hiçbir sebep yok.
Son Söz
Bana kalırsa skill'lerin en değerli tarafı teknik değil. Yıllardır ekiplerde "bu bilgi kimin kafasında?" sorusuyla boğuşuyoruz. Wiki sayfaları yazılıyor, kimse okumuyor. Onboarding dokümanları hazırlanıyor, üç ay içinde eskiyor.
Skill ise okunan bir doküman. Üstelik yanlışsa bunu hemen fark ediyorsunuz, çünkü asistan yanlış şeyi yapıyor. Bu da onu güncel tutmak için garip ama etkili bir motivasyon yaratıyor.
Bir de işin şu tarafı var: skill yazmak, sizi kendi süreçlerinizi açıkça ifade etmeye zorluyor. "Biz bunu neden böyle yapıyoruz?" sorusuna cevap veremediğim birkaç kuralı yazarken fark ettim ve bir kısmını tamamen kaldırdık. Yani skill'ler sadece asistanı değil, ekibi de biraz daha düzenli hale getiriyor.
Başlamak için büyük bir plana gerek yok. En sık tekrar ettiğiniz talimatı alın, bir klasör açın, iyi bir açıklama yazın ve bir hafta kullanın. Neyin eksik olduğunu kullandıkça göreceksiniz.
Ekibinizde herkesin bildiği ama hiçbir yere yazılmamış o kuralları bir düşünün. Belki ilk skill'iniz tam olarak onlardan biri olmalı.