Claude Code skills nasıl yazılır? Adım adım rehber

Claude Code'da skill, Claude'a belirli bir görevi ya da iş akışını adım adım nasıl yapacağını öğreten paketlenmiş bir kurallar serisi. Skill yazmak için zorunlu olan tek şey bir SKILL.md dosyası: içine skill'in ne yaptığını, ne zaman kullanılacağını ve hangi adımları izleyeceğini net bir şekilde yazıyorsunuz. Scriptler, referans dokümanları ve şablonlar isteğe bağlı ekler.

Claude'un skill'ler için yayınladığı 33 sayfalık detaylı bir teknik doküman var. Ben onu daha kullanılabilir bir rehbere dönüştürdüm. Bu yazıda planlamadan teste, oradan canlıya almaya kadar o rehberin özünü anlatıyorum.

Skill nedir, ne işe yarar?

Video oluşturma, video düzenleme, YouTube otomasyonu ya da e-ticaret: bunların hepsi düzenlenmiş, kategorilere ayrılmış birer işlem. Bunları Claude'a skill olarak verdiğinizde, bir uygulamanın yaptığı işlemi takip eder gibi tutarlı şekilde takip ediyor. Örneğin Remotion bir skill; ekledikten sonra Claude Code'la hem kaliteli videolar üretebiliyor hem de düzenleme tarafını halledebiliyorsunuz.

"Paketlenmiş" kısmı önemli. n8n, araçları birbirine bağlayarak otomasyon kurduğunuz bir platform; oradaki otomasyonları bir kez kurarsınız, sonra sürekli çalışır. Skill de aynı mantıkta. İsterseniz bir skill'i Modal'a deploy ederek bulutta da çalıştırabilirsiniz.

Skill'ler en çok üç gruba fayda sağlıyor:

• Claude'un belirli iş akışlarında tutarlı kalmasını isteyen geliştiriciler.
• "Her sabah saat 9'da kontrol et" ya da "her gün kanalıma iki video at" gibi özel iş akışlarını otomatikleştirmek isteyen ileri düzey kullanıcılar.
• Claude Code'u birlikte kullanıp organizasyon genelinde standart oluşturmak isteyen ekipler.

Bir tavsiyem: terimleri İngilizce öğrenin. "Yetenek" diye düşünmek karışıklık yaratabiliyor; skill ve MCP gibi kavramları terim olarak bilin.

Skill ile MCP arasındaki fark nedir?

MCP (Model Context Protocol), yapay zeka ile araçlar arasındaki bağlantının adı. Normal bir API gibi, Claude'u Notion ya da Asana gibi bir araca bağlayıp gerçek zamanlı veri çekiyorsunuz. Skill ise Claude'un bu araçlarla ne yapacağını belirliyor.

Skill olmadan kullanıcılar MCP'yi bağlıyor ama sistem ne yapacağını bilmiyor. İsterseniz bin araç verin; o araçlarla ne yapacağını bilmiyorsa tutarsız sonuç alırsınız. Kısacası MCP bağlantıyı, skill ise yöntemi sağlıyor.

Skill yazmadan önce neyi planlamalısınız?

Her şeyden önce net bir kullanım senaryonuz olmalı. Remotion'ın vaadi çok net: videoları yapay zekaya prompt yazarak oluşturabilirsin. Bunu yapabilmesi için içinde örnek video ve motion paketleri ve hangi paketin ne zaman, nasıl kullanılacağını anlatan bir kurallar listesi var. Sizin skill'inizde de tetikleyiciler, adımlar ve istenen sonuç bu kadar net olmalı.

Planlarken kendinize üç soru sorun:

1. Kullanıcı neyi başarmak istiyor? Örneğin bir şirket pazarlama verisini daha iyi analiz edip daha iyi reklamlar çıkmak istiyor.
2. Hangi iş akışlarını gerektiriyor? Facebook'un bağlanması, ürün görselleri için Nano Banana'nın kullanılması gibi.
3. Hangi uygulama ve veriyle çalışacak? Deneme verisi ya da gerçek verinin analiz edilmiş hali olabilir.

Yaygın skill türleri üç başlıkta toplanıyor: belge, sunum, uygulama ve tasarım gibi yüksek kaliteli çıktılar üretmek (frontend design skill'i daha profesyonel web siteleri yapıyor), birden fazla MCP sunucusu arasında koordinasyon kuran iş akışı otomasyonu ve kendi MCP sunucunuzu geliştirmek. Yazılımcıların eskiden "bunu üç ayda yaparız" dediği bu işler artık Claude'a söyleyerek 30 dakikaya düştü.

SKILL.md dosyası nasıl yazılır?

1. Klasör yapısını kurun

Ana dosya SKILL.md ve kesinlikle zorunlu. Altına isteğe bağlı olarak scriptler (örneğin her saat başı çalışacak bir ajanın kodu), references klasöründe ek dokümanlar ve şablonlar ekleyebilirsiniz. Klasör adını kebab-case yazın, yani kelimeleri tire ile ayırın. README dosyasını skill klasörünün içine koymayın.

References tarafında Pinecone kullanabilirsiniz. Pinecone, belgeleri anlamlarına göre aranabilir hale getiren bir vektör veritabanı. Bir klasöre bin PDF ya da bin fatura yüklediğinizi düşünün: Claude önce hepsini Pinecone'a kaydediyor, sonra referans olarak kullanıyor.

2. Açıklamayı formüle göre yazın

Açıklama (description) üç şeyi söylemeli: ne yapar, ne zaman kullanılır ve neye ihtiyaç duyar. Kötü örnek: "Proje yönetimi için bana skill oluştur." İyi örnek:

Linear'da sprint planlama ve görev oluşturma skill'i. Kullanıcı yeni bir sprint atamak ya da görevleri önceliklendirmek istediğinde kullanılır. Linear MCP sunucusunu gerektirir.

Bu kadar net yazılmış bir skill'i başka biri kendi bilgisayarında kurup çalıştırabilir; siz de bunu şirketlere hizmet olarak satabilirsiniz. Yanlış tetiklenmeler ya da hiç tetiklenmeme genellikle açıklamanın bu formüle uymamasından kaynaklanıyor.

3. Talimatları numaralı adımlarla yazın

Skill'in içinde aşamalı bir talimat listesi olmalı. İçine istediğiniz kadar ek skill ve araç yükleyebilirsiniz. Skill'i buluta koymak, bir uygulamaya çevirmek ya da kendi bilgisayarınızda çalıştırmak gibi her yerde kullanılabilir yazmak da önemli.

Claude talimatlara uymuyorsa adımları numaralandırın. Çok fazla kural verdiğinizde takip edemeyip inisiyatif kullanmaya başlayabiliyor; bu yüzden "asla" ve "her zaman" gibi kesin ifadeler kullanın.

4. Sınır ve filtre koyun

Bir araçtan çok fazla veri dönüyorsa ve token sınırı aşılıyorsa filtre koyun. Token, modelin işlediği metin birimi; kullanım bunun üzerinden ölçülüyor. Ben web siteme blog eklerken bunu çok kullanıyorum. Her yazıda en az iki üç görsel ve iki video istiyorum; sınır koymazsam çok sayıda istek atıp bütün tokenleri harcayabilir.

Bu yüzden "günde en fazla 20 görsel, en fazla 30 video oluşturabilirsin" gibi limitler yazıyorum. Böylece kendini sınırlıyor ve kaç tane ürettiğini, kaç tane kaldığını takip ediyor.

5. Test edin

Skill'i yükleyip "çalıştır" diyerek elle test edebilirsiniz. Tekrarlanabilir testler için test prompt senaryoları kullanın, terminalde çalıştırın ya da projeyi Modal'a deploy edip API anahtarıyla çağırın. Bir skill'in çalıştığını şu ölçütlerle anlarsınız:

• 10 ile 20 arası test sorgusu çalıştırın; kaç kez otomatik yüklendiğine ve kaç kez doğru cevap verdiğine bakın.
• Doğru MCP ve API çağrılarını yapıyor mu kontrol edin; başarısız çağrıların oranını ve hata kodlarını çıkarın.
• Aynı isteği üç beş kez çalıştırın. Çıktılar yapılandırılmış, kaliteli ve tutarlıysa doğru yoldasınız.
• Yeni bir Claude oturumunda, ek açıklama yapmadan işi yapabiliyor mu bakın. Her saat başı çalışması gerekiyorsa gerçekten çalıştığından emin olun.

Skill creator ile daha hızlı skill yazmak

Skill creator, skill yazan bir skill. İhtiyacınızı anlatıyorsunuz; taslağı hazırlıyor, mevcut skill'inizi analiz edip iyileştiriyor. Elle yaptığınızda 15 mesaj, 10 dakika ve 3 başarısız API çağrısı süren bir iş, skill creator ile iki mesaj ve bir dakikaya iniyor. Claude Code'un içinde gelen skill'lerden biri; / yazarak çağırabiliyorsunuz.

Sıralı iş akışı mı, çoklu MCP koordinasyonu mu?

Sıralı iş akışında adımlar birbirini izliyor: müşteri verilerini topla, hoş geldin maili gönder, Slack'ten ekibi bilgilendir. Çoklu MCP koordinasyonunda ise Claude birden fazla araçla aynı anda çalışıyor: Figma'dan tasarım tokenlerini çekiyor, Google MCP'si üzerinden kaydediyor, Linear'da görev oluşturuyor, Slack'ten geliştiricileri uyarıyor.

Bence Claude Code'u n8n'den ayıran en önemli nokta bu: işleri eş zamanlı yürütebilmesi. n8n'i kullanmaya devam ediyoruz, ama n8n daha çok şirketlere hizmet satarken sunduğunuz bir şey. Claude Code ise doğru skill'leri eklediğinizde uygulama yaparken tek başına kullanabileceğiniz bir platform.

Hangi ileri teknikler işe yarar?

• Kendini düzeltme: Kurallara "ilk taslağı oluştur, ekran görüntüsünü al, her şey doğru mu kontrol et, değilse yeniden oluştur" yazabilirsiniz. Rakipleri araştırıp en iyi içeriklere benzer kaydırmalı Instagram gönderileri üreten bir sistemde bu çok işe yarıyor.
• Bağlam farkındalığı: Dosya türüne göre yönlendirme yapın; görsel gelirse şunu, video gelirse bunu yap.
• Büyük veri: 100.000 kişilik bir kullanıcı verisi ya da bir milyon oturumluk site trafiği gibi büyük verilerde kuralları gösterip veriyi Pinecone ile vektör veritabanına çevirerek Claude'a soru sorabilirsiniz.

Skill nasıl canlıya alınır?

Tam anlamıyla bir skill mağazası yok. Skill dizinlerinde ve GitHub'da çok fazla şey var, ama GitHub şimdiden biraz çöplüğe döndü; neyin iyi olduğunu çoğu zaman yıldız sayısına ve popülerliğe bakarak anlıyorsunuz. Kendi skill'inizi değere çevirmek için onu bir uygulamaya dönüştürmeniz gerekiyor:

1. Ajanı Modal'a deploy edin.
2. İsterseniz bir arayüz oluşturun.
3. Projeyi GitHub'a yükleyip Vercel'de yayına alın.
4. Abonelik sistemi ekleyip ödeme alın.

Arayüz istemiyor, sadece API anahtarıyla istek atmak istiyorsanız Modal'a kurmanız yeterli. Sonra onu kendi uygulamanıza ya da müşterinizin sistemine bağlayabilirsiniz.

Başlamadan önce kontrol listesi

• Görevi önce elle başarıyla tamamladınız mı?
• MCP'ler kurulu ve çalışıyor mu?
• Dosya ve klasör adları doğru mu? Skill yüklenmiyorsa ilk bakacağınız yer burası.
• Açıklama ne yaptığını ve ne zaman kullanılacağını söylüyor mu?
• Adımlar net bir şekilde numaralandırılmış mı?

Bu sorulara evet diyebiliyorsanız skill'inizi kaydedip sürekli kullanılabilir hale getirebilirsiniz. Ne yapmak istediğinizi bildiğiniz sürece bunların hepsini sadece prompt yazarak kurmak mümkün.

Bu yazı, Claude Code Skills Rehberi: Kendi Yapay Zeka Yeteneklerinizi Sıfırdan Oluşturun videomdan derlendi.

Sık sorulan sorular

Claude Code skill klasörü hangi dosyaları içermeli?

Zorunlu olan tek dosya SKILL.md; skill'in ne yaptığı, ne zaman kullanılacağı ve adımları burada yazıyor. İsteğe bağlı olarak scriptler, references klasöründe ek dokümanlar ve şablonlar ekleyebilirsiniz. Klasör adını kebab-case yazın, yani kelimeleri tire ile ayırın ve skill klasörünün içine README koymayın.

Claude Code'da skill ile MCP arasındaki fark nedir?

MCP, Claude'u Notion, Asana ya da Slack gibi araçlara bağlayan protokol; bağlantıyı ve gerçek zamanlı veriyi sağlıyor. Skill ise Claude'un bu araçlarla ne yapacağını ve hangi adımları izleyeceğini belirliyor. Skill olmadan bin araç bağlasanız bile Claude ne yapacağını bilmediği için tutarsız sonuç alırsınız.

Claude Code skill tetiklenmiyorsa veya talimatlara uymuyorsa ne yapmalıyım?

Önce dosya ve klasör adlarını kontrol edin. Tetiklenme sorunları genellikle açıklamanın "ne yapar, ne zaman kullanılır" formülüne uygun yazılmamasından kaynaklanıyor. Talimatlara uymuyorsa adımları numaralandırın, kural sayısını azaltın ve "asla", "her zaman" gibi kesin ifadeler kullanın.

Skill creator nedir, skill yazmayı nasıl hızlandırır?

Skill creator, skill yazan bir skill ve Claude Code'un içinde geliyor. İhtiyacınızı anlattığınızda taslağı hazırlıyor, mevcut skill'inizi analiz edip iyileştiriyor. Elle 15 mesaj ve 10 dakika süren bir işi iki mesaj ve bir dakikaya indirebiliyor.