Claude Code skill yazma: SKILL.md dosyasını doğru biçimde hazırlamak ve denetlemek

Claude Code skill, Claude'a belirli bir işi nasıl yapacağını öğreten, SKILL.md adlı bir dosyada tutulan talimat paketidir. Ekibinin tekrarlayan iş akışlarını (kod incelemesi, sürüm notu, PR açıklaması gibi) her seferinde baştan anlatmak istemeyen geliştiriciler ve teknik ekipler için yazılır. Doğru yazılmış bir skill, Claude'un o işi her seferinde aynı kurallarla yapmasını sağlar. Otopilot'un Skill Yazma Botu, tarif ettiğiniz işi bu biçimde bir SKILL.md taslağına dönüştürür ve dosyanın biçim kurallarına uyup uymadığını denetler.

Bu rehberde önce SKILL.md dosyasının yapısını ve iyi bir skill'in özelliklerini anlatıyoruz; bu kısım botu kullanmasanız da işinize yarar. Ardından Skill Yazma Botu'nun ne yaptığını, kurulumunu ve sınırlarını açıklıyoruz.

SKILL.md nedir, Claude skills nasıl çalışır?

Anthropic'in Agent Skills belgelerine göre bir skill, bir klasör ve bu klasörün içindeki SKILL.md dosyasından oluşur. Dosyanın başında YAML önbilgisi (frontmatter) bulunur; burada skill'in adı ve açıklaması yazılır. Önbilginin altında ise Claude'un izleyeceği talimatlar Markdown olarak yer alır.

Çalışma mantığı şöyledir: Claude, kullanılabilir skill'lerin yalnız adını ve açıklamasını baştan bilir. Elindeki iş bir skill'in açıklamasıyla örtüşürse o skill'in tam talimatlarını okur ve uygular. Bu yüzden açıklama, skill'in ne zaman kullanılacağını söyleyen en kritik alandır. Açıklama belirsizse skill ya hiç devreye girmez ya da yanlış işte devreye girer.

Claude Code'da skill'ler proje klasöründe ya da kullanıcının kendi ayar klasöründe tutulabilir. Proje içinde tutulan skill'ler depoyla birlikte ekibe dağılır; herkes aynı talimatları kullanır.

Skill md yaml frontmatter kuralları

SKILL.md dosyası YAML önbilgisiyle başlamak zorundadır; aksi halde araçlar "SKILL.md must start with YAML frontmatter" gibi bir uyarı verir. Belgelerde yazan temel biçim kuralları şunlardır:

• Ad (name): Küçük harf, rakam ve tire içerir; en çok 64 karakterdir.
• Açıklama (description): Skill'in ne yaptığını ve ne zaman kullanılacağını anlatır; en çok 1024 karakterdir.
• Gövde: Talimatlar, örnekler ve gerekirse yardımcı dosyalara bağlantılar.

Bir kural da güvenlikle ilgilidir: SKILL.md içine API anahtarı, token ya da şifre yazılmaz. Skill dosyaları çoğunlukla depoda paylaşılır; içine düşen bir anahtar herkesin eline geçer.

İyi bir Claude Code skill nasıl yazılır?

Biçim kurallarına uymak skill'in çalışması için gereklidir, ama yeterli değildir. İyi bir skill'i ayıran birkaç özellik var:

• Tek bir işe odaklanır. "Geliştirme yardımcısı" gibi geniş bir skill yerine "değişikliklerden PR açıklaması yazan skill" gibi dar bir tanım daha güvenilir çalışır.
• Açıklamada tetikleyiciyi söyler. "Kullanıcı PR açıklaması istediğinde ya da bir dalı incelemeye hazırladığında kullan" gibi bir cümle, Claude'un skill'i doğru anda seçmesini sağlar.
• Ne zaman kullanılmayacağını da yazar. Benzer işler için başka bir skill varsa sınırı çizmek karışıklığı önler.
• Adımları sırayla verir. Talimatlar numaralı ve kısa olduğunda takip etmek kolaylaşır.
• Örnek içerir. Beklenen çıktının bir örneği, uzun açıklamalardan daha etkilidir.
• Ekibin gerçek kurallarını yansıtır. Commit biçimi, dil tercihi, test komutları gibi bilgiler skill'i genel bir şablondan ekibinize özel bir araca dönüştürür.

Örnek: PR açıklaması yazan bir skill

Somut bir örnekle düşünelim. Ekibiniz her çekme isteğine (PR) aynı biçimde açıklama yazmak istiyor: değişikliğin amacı, etkilenen dosyalar, test adımları ve riskler. Skill'in adı pr-aciklamasi olabilir. Açıklaması da şöyle bir cümle: "Kullanıcı bir dal için PR açıklaması istediğinde ya da değişiklikleri incelemeye hazırlarken kullan; ekibin dört bölümlü PR şablonunu uygular."

Ne Zaman Kullanılır bölümünde PR açıklaması istenen durumlar listelenir; sürüm notu ya da commit mesajı gibi benzer ama farklı işler için kullanılmaması gerektiği de yazılır. Temel İlkeler bölümünde ekibin değişmez kuralları yer alır: açıklama Türkçe yazılır, test edilmeyen bir şey test edildi diye gösterilmez. Talimatlar bölümü sırayı verir: önce farkları oku, sonra amacı tek cümleyle yaz, ardından dosyaları grupla, en son test adımlarını ve riskleri ekle. Örnekler bölümünde ise daha önce beğenilen bir PR açıklaması durur.

Tablodaki bölüm adları Skill Yazma Botu'nun ürettiği şablona aittir. Kendi skill'lerinizde farklı başlıklar kullanabilirsiniz; önemli olan bu işlevlerin karşılanmasıdır.

Skill Yazma Botu ne yapar?

Skill Yazma Botu, tarif ettiğiniz işi Claude Code ve Agent Skills biçiminde bir SKILL.md dosyasına dönüştürür. Ürettiği dosyada ad ve açıklama önbilgisi ile Ne Zaman Kullanılır, Temel İlkeler, Talimatlar ve Örnekler bölümleri bulunur.

Botun iki kipi vardır:

1. Yapay zekâ kipi: Fikrinizden içerik üretir. Sizin kendi OpenAI ya da OpenAI uyumlu servis anahtarınızla çalışır; kullanım ücreti doğrudan sağlayıcıdaki hesabınızdan düşer.
2. Şablon kipi: Anahtar gerektirmez; doğrulamayı geçen bir iskelet üretir. İskelet genel adımlar içerir ve sizin doldurmanız gerekir.

Botun bir de yerleşik doğrulayıcısı vardır. Ad biçimini, açıklama uzunluğunu, zorunlu bölümleri ve gizli anahtara benzeyen değerleri denetler. Bu doğrulayıcı yalnız yeni üretilen dosyalarda değil, elinizdeki mevcut bir SKILL.md dosyasında da çalışır ve anahtar gerektirmez. Ürettiği skill doğrulamayı geçemezse bot dosyayı yazmaz ve sorunu listeler.

Pakette yalnız Otopilot'un kendi şablonu ve örnekleri bulunur; üçüncü taraf skill içerikleri kullanılmaz.

Kimler için uygun?

• Claude Code için ekibine özel skill hazırlayan geliştiriciler.
• Tekrarlayan iş akışlarını SKILL.md olarak belgelemek isteyen ekipler.
• Elindeki SKILL.md dosyalarının biçim kurallarına uyup uymadığını denetlemek isteyenler.
• Yapay zekâ anahtarı olmadan skill iskeleti başlatmak isteyenler.

Kurulum ve claude code skill ekleme adımları

Paket Python 3.10 ya da üstü gerektirir. Botun bizim sunucumuzda çalıştığı seçenek de vardır; aşağıdaki adımlar indirilen paket içindir.

1. Lisanslarım sayfasından paketi indirin ve skill-writer-bot klasörüne geçin.
2. Bağımlılıkları kurun: pip install -r requirements.txt.
3. Ayar dosyasını oluşturun: cp config.example.json config.json.
4. Gizli değerleri verin: export BOT_LICENSE_KEY=...; yapay zekâ kipinde ayrıca export OPENAI_API_KEY=....
5. Anahtarsız iskelet istiyorsanız ayar dosyasında mode değerini template yapın.
6. Lisansı kontrol edin: python3 bot.py check.
7. Skill üretin: python3 bot.py run --idea "Değişikliklerden PR açıklaması yazan skill" --name pr-aciklamasi.
8. Önce denemek isterseniz --dry-run ekleyin; dosya yazılmaz, sonucun başı ekrana yazılır.
9. Üretilen dosya skills/<ad>/SKILL.md yoluna yazılır. İçeriği kendi iş akışınıza göre gözden geçirin.
10. Elle düzenlediğiniz ya da başka bir SKILL.md dosyasını doğrulayın: python3 bot.py run --validate skills/pr-aciklamasi/SKILL.md.

Doğrulamayı geçen klasörü Claude Code'un skill aradığı yere, yani projenizin skill klasörüne ya da kendi kullanıcı klasörünüze kopyaladığınızda skill kullanılabilir hale gelir. Ekipçe kullanacaksanız proje klasörünü tercih edin ve değişiklikleri kod incelemesinden geçirin.

Yapay zekâ anahtarının nasıl alınacağını ve saklanacağını yapay zekâ API anahtarları rehberinde anlattık. İyi talimat yazmanın genel ilkeleri skill için de geçerlidir; bunları prompt nasıl yazılır rehberinde ayrıntılı ele aldık.

Elle yazmak mı, botla başlamak mı?

Tek bir skill yazacaksanız ve biçim kurallarını biliyorsanız elle yazmak yeterlidir. Bot şu durumlarda zaman kazandırır:

Son satır önemli: hiçbir şablon, skill'in sizin projenizde doğru sonucu verdiğini garanti etmez. Taslağı gerçek bir iş üzerinde deneyin, Claude'un nerede yanlış anladığına bakın ve talimatları buna göre düzeltin.

Sınırlar ve dikkat edilmesi gerekenler

Skill Yazma Botu'nun bot sayfasında yazan sınırları şunlardır:

• Her çalıştırmada tek bir fikirden tek bir SKILL.md üretilir; toplu üretim parametresi yoktur.
• Çıktı yalnız yerel dosyadır; siteye ya da başka bir sisteme gönderim yapılmaz.
• Doğrulayıcı biçimi denetler; talimatların doğru çalışıp çalışmadığını denetlemez.
• Şablon kipindeki iskelet genel adımlar içerir ve sizin doldurmanız gerekir.
• Aynı adla yeniden üretilen skill önceki dosyanın üzerine yazılır.
• Yapay zekâ kipinde her skill bir çağrıdır ve ücreti kendi sağlayıcı hesabınıza yansır.

Bir de güvenlik notu: Skill'ler Claude'a komut çalıştırma ya da dosya düzenleme gibi işler yaptırabilir. Başkasından aldığınız bir skill'i kullanmadan önce içeriğini okuyun; bilmediğiniz bir kaynağın talimatlarını körü körüne çalıştırmayın. Bot, ürettiği ve doğruladığı dosyalarda gizli anahtara benzeyen değerleri yakalar, ama talimatların ne yaptığını sizin okumanız gerekir.

Paketin güncel fiyatı, süre seçenekleri ve günlük temel hacmi Claude Code skill yazma botu sayfasında yazar. Otopilot'un diğer hazır paketleri modül mağazası sayfasında listelenir; indirilen bir paketin kendi sunucunuzda nasıl çalıştığına dair başka bir örnek için makale botu rehberine bakabilirsiniz. Bir claude code skill ekibinizin bilgisini kalıcı hale getirir; iyi bir açıklama ve net talimatlarla başlamak, sonradan yapılacak düzeltmeleri azaltır.

Sık sorulan sorular

Claude Code skill nedir?

Claude Code skill, Claude'a belirli bir işi nasıl yapacağını anlatan ve SKILL.md dosyasında tutulan talimat paketidir. Dosyanın başında ad ve açıklama bulunur; Claude elindeki iş açıklamayla örtüştüğünde skill'in talimatlarını okuyup uygular. Tekrarlayan iş akışlarını her seferinde aynı kurallarla yaptırmak için kullanılır.

SKILL.md nedir, hangi alanları içermelidir?

SKILL.md, bir skill'in talimatlarını taşıyan Markdown dosyasıdır. YAML önbilgisiyle başlar; burada küçük harf ve tireden oluşan, en çok 64 karakterlik bir ad ile en çok 1024 karakterlik bir açıklama yer alır. Altında talimatlar ve örnekler bulunur.

Claude Code skill ekleme nasıl yapılır?

Skill klasörünü, içinde SKILL.md olacak biçimde projenizin skill klasörüne ya da kendi kullanıcı klasörünüze koyarsınız. Proje içindeki skill'ler depoyla birlikte ekibe dağılır. Eklemeden önce dosyanın biçim kurallarına uyduğunu kontrol etmek, skill'in hiç yüklenmemesi gibi sorunları önler.

Skill Yazma Botu yapay zekâ anahtarı olmadan çalışır mı?

Evet. Kipi template yaparsanız fikrinizden doğrulamayı geçen bir iskelet üretilir. Mevcut dosyaları denetleyen --validate komutu da anahtar gerektirmez. Yapay zekâ kipi ise kendi OpenAI ya da uyumlu servis anahtarınızla çalışır.

Skill yazma botu ücretli mi?

Evet, lisansla satılır. Güncel fiyat ve süre seçenekleri bot sayfasında yazar. Yapay zekâ kipinde kullanım ücreti ayrıca sizin sağlayıcı hesabınızdan düşer; lisans ücretine dahil değildir.

Kaynaklar

• Claude Docs: Agent Skills genel bakış
• Claude Docs: Skill yazımı için en iyi uygulamalar
• Claude Docs: Prompt engineering genel bakış
• OpenAI: API anahtarı güvenliği için en iyi uygulamalar