Gerçekten Çalışan Bir Claude Code Skill Nasıl Oluşturulur (Tam Kılavuz)

Claude'u bir haftadır kullanıyorsun ve her seferinde aynı şeyi yazıyorsun. Her kod gönderdiğinde, commit formatınla ilgili aynı üç kuralı yapıştırıyorsun. Her doküman yazdığında, stilini yeniden açıklıyorsun. Claude bunu iyi yapıyor, ama sohbet biter bitmez unutuyor ve yarın yine her şeyi baştan yazıyorsun.

Bir skill (beceri) bunu çözer. Claude'a kalıcı olarak bir iş akışı öğreten, bir kere yazdığın küçük bir klasördür. Böylece her oturumda, sen sormadan uygulanır.

İşte kısaca nasıl çalıştığı: skill, içinde bir dosya bulunan bir klasördür. Claude, her zaman görüş alanında skill'in tek satırlık bir özetini tutar ve tam talimatları yalnızca talebin eşleştiğinde getirir. Mekanizmanın tamamı bu.

Bu kılavuzda, sıfırdan gerçek bir skill oluşturacağız: commit-messages. Bu skill, git commit'lerini senin belirlediğin formatta yazar. Claude'u yüklüyse ve başka bir şeyin yoksa, her adımı takip edebilirsin.

Elde edeceğin şey

Temelinde bir skill, gerekli bir dosya olan SKILL.md'yi içeren bir klasördür. Skill büyüdükçe devreye giren üç isteğe bağlı klasör daha vardır:

1your-skill-name/
2├── SKILL.md          # Gerekli - ana skill dosyası
3├── scripts/          # İsteğe bağlı - çalıştırılabilir kod
4├── references/       # İsteğe bağlı - dokümantasyon
5└── assets/           # İsteğe bağlı - şablonlar vb.

SKILL.md dosyasının iki bölümü vardır: Claude'a skill'i ne zaman kullanacağını söyleyen kısa bir başlık ve altında Claude'a ne yapacağını söyleyen talimatlar. Bu ayrımın önemli bir nedeni var. Claude başlığı sürekli okur, böylece skill'in varlığından her zaman haberdar olur, ancak talimatları yalnızca talebin eşleştiğinde yükler. Bu ayrımı aklında tut, çünkü bu kılavuzdaki neredeyse her şey bundan türetilmiştir.

Oluştur

Skill'ler, ana dizinindeki .claude/skills adlı bir klasörde bulunur. Claude Code ve masaüstü uygulaması bu klasörü okur. Bu gizli bir klasördür ve büyük olasılıkla henüz mevcut değildir. Bu yüzden, skill'in klasörüyle birlikte oluşturmanın en hızlı yolu tek bir komuttur.

Mac'te Terminal'i aç ve şunu çalıştır:

1mkdir -p ~/.claude/skills/your-skill-name

Windows'ta PowerShell'i aç ve şunu çalıştır:

1New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\your-skill-name"

Klasör adı sadece görsel değildir. Claude bunu skill'in tanımlayıcısı olarak kullanır ve bir biçimlendirme kuralı, diğerlerinden daha fazla insanı yanıltır:

• Kebab-case kullan: notion-project-setup ✔
• Boşluk yok: Notion Project Setup ✖
• Alt çizgi yok: notion_project_setup ✖
• Büyük harf yok: NotionProjectSetup ✖

Bu klasörün içinde, tam olarak SKILL.md adında bir dosya oluştur ve herhangi bir metin düzenleyicide aç. Buradan itibaren her şey bu dosyaya yazılacak.

Yazmadan önce tasarla

İşe yarayan skill'ler, dosyanın bir satırını yazmadan önce verilen iki kararla başlar. İkisi de atlanabilir gibi görünür, ama hiçbiri değildir.

İlk olarak, skill'in tam olarak ne zaman devreye girmesi gerektiğine karar ver. Kullanıcının gerçekten yazacağı sözcüklerle iki veya üç gerçek durum yaz:

• "bu değişiklikleri gönder"
• "bu diff için bir commit mesajı yaz"
• "stage et ve commit yap"

Bu gereksiz bir iş değil. Bu ifadeler, daha sonra açıklaman ve testlerin için ham malzeme haline gelir. Bunlar olmadan tasarlanan bir skill, tam da tetiklenmesini engelleyecek şekilde belirsiz olma eğilimindedir.

İkinci olarak, işe yaradığını nasıl anlayacağına karar ver. Diğerlerinden daha önemli olan kriter, skill'in ismini söylemene gerek kalmadan kendi kendine yüklenip yüklenmediğidir. Her seferinde manuel olarak çağırman gerekiyorsa, skill teknik olarak çalışıyor olsa da asıl görevinde başarısız olmuş demektir. Bununla birlikte izlenmesi gereken diğer şeyler: görevi, sen ortada düzeltme yapmadan tamamlayıp tamamlamadığı ve farklı oturumlarda sana aynı şekilde sonuç verip vermediğidir.

Açıklama, başarıyı getiren ya da bitiren şeydir

Dosyadaki her şeyden daha önemlisi, başlıktaki açıklama en kritik işi yapar, çünkü Claude'un skill'i yükleyip yüklemeyeceğine karar verirken okuduğu tek kısım burasıdır. Talimatların kusursuz olabilir, ama açıklama eşleşmezse Claude onlara asla ulaşamaz. "Çalışmayan" skill'lerin çoğu aslında tam da burada başarısız olur.

Güçlü bir açıklama, tek bir cümlede iki soruyu yanıtlar: skill ne yapar ve Claude ne zaman buna başvurmalı? İkinci kısım, insanların atladığı kısımdır.

İşte farkı:

1# zayıf - ne olduğunu söyler, Claude'a bir taleple eşleştirecek bir şey vermez
2description: Git commit'lerine yardımcı olur.
3
4# güçlü - devreye girmesi gereken anları adlandırır
5description: Git commit mesajlarını Conventional Commits formatında yazar. Kullanıcı değişiklikleri göndermek, bir commit mesajı yazmak veya dosyaları stage edip commit yapmak istediğinde kullan.

Zayıf versiyon, Claude'a skill'in varlığını söyler ama onu söyleyeceğin hiçbir şeyle ilişkilendirmez. Güçlü versiyon ise gerçek ifadeleri adlandırır, böylece "bu değişiklikleri gönder" yazdığında Claude'un eşleştirecek bir şeyi olur. Kullanıcının gerçekten kullanacağı sözcükleri adlandır, her şeyi 1024 karakterin altında tut ve içine < veya > koyma.

Bir skill tetiklenmediğinde, çözüm neredeyse her zaman buradadır. Gerçekten kullandığın ifadeleri ekle. "işimi kaydet" dersen ama açıklama sadece "commit"ten bahsediyorsa, Claude'un ikisini ilişkilendirmesi mümkün değildir. Tam tersi olursa, yani skill gereksiz yere tetiklenirse, açıklamayı daralt veya olumsuz bir tetikleyici ekle:

1description: Git commit mesajlarını Conventional Commits formatında yazar. Değişiklikleri gönderirken kullan. Kod yorumları veya dokümantasyon yazmak için kullanma.

Güvenmeden önce çalışmanı hızlıca kontrol etmenin bir yolu var. Claude'a doğrudan sor:

"Commit-messages skill'ini ne zaman kullanırdın?"

Claude, açıklamanı kendi sözcükleriyle geri okuyacaktır. Bu, skill'in gerçekten devreye girmesini istediğin zamanlarla uyuşmuyorsa, sorununu buldun demektir. Sorun, alttaki talimatlarda değil, açıklamadadır.

Claude'un gerçekten uyguladığı talimatları yaz

Başlığın altında, düz Markdown formatında gövde gelir. Gerçek iş akışın burada yaşar ve Claude'un uyguladığı talimatları, sessizce yok saydıklarından ayıran iki alışkanlık vardır.

İlki, spesifik olmaktır. Claude somut talimatlara uyar, belirsiz olanları ise geçiştirir. Ne kadar kesin olursan, o kadar güvenilir davranır:

1# Kötü
2Commit'i sonlandırmadan önce doğrula.
3
4# İyi
5`python scripts/validate.py "<message>"` komutunu çalıştır.
6Başarısız olursa, şunları düzelt:
7- Geçersiz tür: feat, fix, docs, refactor, test, chore kullan
8- Özet 60 karakterden uzun: kısalt

İkincisi ise sıralamadır. Claude, en önce okuduğuna daha fazla ağırlık verir. Bu nedenle, uzun bir dosyanın altına gömülü bir kural, gözden kaçan bir kuraldır. Bozulmaması gereken her şeyi, bunu belirten bir başlık altında en üste koy:

1## Önemli
2- Özet satırı her zaman 60 karakterin altında olmalı
3- Sadece şimdiki zaman kullan: "ekle", "ekledi" değil

Ayrıca dilin garanti edebileceğinin bir sınırı vardır. Talimatlar yorumlanır, yani Claude onları iyi takip eder ama her seferinde birebir aynı şekilde değil. Bir kontrolün her çalıştırmada gerçekten geçmesi gerektiğinde, bunu düz yazıyla anlatma, bir betiğe taşı ve talimatların onu çalıştırmasını sağla. Kod her seferinde aynı şeyi yapar; bir cümle yapmaz. (scripts/ klasörü tam da bunun içindir, bir sonraki bölümde ele alınacak.)

Çoğu skill'de işe yarayan bir yapı şöyledir:

1# Skill Adı
2
3## Önemli
4Atlanmaması gereken kritik kurallar.
5
6## Talimatlar
7Adım adım, spesifik ve uygulanabilir.
8
9## Örnekler
10Somut girdi ve çıktı. Claude, kuralları takip etmektense örnekleri kopyalamada daha başarılıdır.

Dosyayı zayıf tut. Temel talimatlarının ötesine geçmeye başladığı an, fazla detayı dışarı taşıma zamanıdır. İsteğe bağlı klasörler tam olarak bunun içindir.

Betikler, referanslar, varlıklar

Şu ana kadar anlatılanlar, Claude'a talimatlar veren bir skill üretir. İsteğe bağlı üç klasör ise onu Claude'a araçlar veren bir skill'e dönüştürür ve skill'in düz bir istemin yapamayacağı şeyleri yapmasını sağlar.

scripts/ klasörü, Claude'un hassas olması gereken her şey için çalıştırdığı kodu barındırır. Claude'un bir commit'in doğru biçimlendirilip biçimlendirilmediğini göz kararıyla belirlemesine güvenmek yerine, ona kontrol eden bir betik verirsin:

1# scripts/validate.py
2import sys
3msg = sys.argv[1]
4types = ("feat", "fix", "docs", "refactor", "test", "chore")
5
6if msg.split(":")[0] not in types:
7    print(f"Geçersiz tür. Şunları kullan: {', '.join(types)}")
8elif len(msg.split("\n")[0]) > 60:
9    print("Özet çok uzun (60 karakterden fazla)")
10else:
11    print("TAMAM")

Sonra SKILL.md dosyasında Claude'a bunu kullanmasını söylersin:

1Sonlandırmadan önce, `python scripts/validate.py "<message>"` komutunu çalıştır
2ve işaret ettiği her şeyi düzelt.

Artık biçim kuralı, Claude'un kontrol etmeyi hatırlamasına bağlı olmak yerine, her seferinde aynı şekilde çalışan bir kod tarafından uygulanır.

references/ klasörü, yalnızca ihtiyaç duyulduğunda yüklenen dokümantasyonu barındırır. Diyelim ki commit kuralların, kapsamlar, altbilgiler ve uç durumlarla dolu iki sayfa tutuyor. Bunların hepsini SKILL.md'ye koyarsan, tek satırlık bir commit'te bile her seferinde yüklenir. Bunun yerine bir referans dosyasına taşı:

1your-skill-name/
2├── SKILL.md
3└── references/
4    └── conventions.md

Ve ana dosyadan buna işaret et:

1Tam kural listesi için references/conventions.md dosyasına bakın

Claude bu dosyayı yalnızca görev gerektirdiğinde açar. Skill'lerin çalıştırılmasının ucuz kalmasının tüm nedeni budur: ağır detay, her seferinde bağlamda taşınmak yerine, gerçekten alakalı olana kadar diskte bekler.

assets/ klasörü, skill'in rehberlik için okumak yerine çıktısında kullandığı dosyaları barındırır. Örneğin bir şablon, bir yapılandırma dosyası veya bir logo. Bir commit skill'i bunlardan herhangi birine ihtiyaç duymaz, ancak rapor oluşturan bir skill, burada bir template.md bulundurabilir ve her seferinde onu doldurarak her raporun aynı yapıyla çıkmasını sağlayabilir.

Bir araya getirildiğinde, bu üç klasör, Claude'a nasıl çalıştığını söyleyen bir skill ile ona işi senin tarzında yapmak için gereken araçları veren bir skill arasındaki farktır.

Hatırlanması gereken tek şey

Bir skill, Claude'a yeni bir yetenek öğretmez. Nasıl commit yazılacağını zaten biliyor. Skill'in yaptığı şey, işi her seferinde, sen tekrar açıklamak zorunda kalmadan, senin tarzında yapmasını sağlamaktır.

Ve bir skill çalışmadığında, neden neredeyse hiçbir zaman üzerinde uğraştığın talimatlar değildir. Açıklamadır. Claude, skill'i yükleyip yüklemeyeceğine, alttaki çalışmayı okumadan önce, o tek satırdan karar verir. Açıklamayı doğru yap, alttaki her şey nihayet kullanılsın.

Bu faydalıysa, profilime gidip takip edin. Teknoloji, yapay zeka ve gerçekten işleyen sistemler hakkında yazıyorum.

Hoşçakalın,

@undefinedKi