SKILL.md Nasıl Yazılır? Kod Bilmeden, Adım Adım Rehber

SKILL.md, bir yapay zeka asistanına (Claude gibi) belirli bir işi her seferinde aynı şekilde nasıl yapacağını öğreten kısa bir metin dosyasıdır — kod değil, düz yazıyla yazılmış bir talimat setidir. Örneğin ‘her yeni sayfa yayınlamadan önce şunları kontrol et’ gibi bir işi asistana bir kez öğretirsiniz, o andan sonra her seferinde hatırlar. Bu sayfada üç şeyi öğreneceksiniz: bir SKILL.md dosyasının hangi parçalardan oluştuğu, kod bilmeden nasıl yazılacağı ve kopyalayıp kullanabileceğiniz gerçek bir örnek. Sonunda en sık yapılan 3 hatayı da göreceksiniz.

Bir SKILL.md Dosyasının Anatomisi

Bir SKILL.md dosyası iki parçadan oluşur, ikisi de düz metin — hiçbirinde kod yok.

1. Kimlik kartı (başlık ve açıklama). Dosyanın en üstünde, iki satırlık kısa bir tanıtım bulunur: skill’in adı ve ne işe yaradığı. Bu kısım kısa olmalı çünkü asistan, elindeki onlarca skill’in hangisini kullanacağına önce bu iki satıra bakarak karar verir. Claude Skills’in nasıl çalıştığını burada daha detaylı anlattım; burada sadece yazım tarafına odaklanıyorum.

2. Ne zaman devreye girmeli. Bu, insanların en çok atladığı kısım. Açıklamaya sadece ‘bu skill ne yapar’ yazmak yetmez — ‘bu skill’i ne zaman kullan’ da yazmalısınız. Asistan bu cümleyi okuyup şu an konuşulan işin buna benzeyip benzemediğine karar veriyor. Belirsiz yazarsanız (örn. ‘içerik yardımcısı’), asistan ya hiç tetiklemez ya da alakasız durumlarda devreye girer.

3. Adım adım talimatlar. Kimlik kartından sonra gelen gövde metni, işin nasıl yapılacağını anlatır. Burayı bir asistana iş tarif eder gibi yazın — sanki işe yeni başlamış, konuyu hiç bilmeyen ama akıllı bir yardımcıya anlatıyormuşsunuz gibi. Sırayla ne yapılacağını, hangi sırada, hangi dosyaya bakılacağını, sonucun nasıl görünmesi gerektiğini yazın.

Adım Adım: Kod Bilmeden Nasıl Yazılır

Kod yazmadan, sadece düz cümlelerle bir SKILL.md dosyası şöyle kurulur:

1. İşi tek cümlede tanımlayın. ‘Bu skill ne yapıyor?’ sorusuna tek cümlelik dürüst bir cevap yazın. Uzun tanımlar asistanı değil sizi yoruyor.
2. Tetikleyiciyi yazın. ‘Şu durumda kullan’ diye ayrı bir cümle ekleyin. Ne kadar somut olursa o kadar iyi çalışır — ‘raporlarla ilgili’ değil, ‘haftalık rakip fiyat raporunu hazırlarken’ gibi.
3. Adımları numaralandırın. İşi kafanızda nasıl sırayla yapıyorsanız öyle yazın: önce şunu kontrol et, sonra şuraya bak, sonra şu formatta yaz. Adım atlamayın — asistan sizin aklınızdan geçeni bilmiyor, sadece yazılanı biliyor.
4. Somut bir örnek ekleyin. ‘Böyle bir girdi gelirse, sonuç böyle olmalı’ tarzında tek bir örnek, on satır soyut açıklamadan daha güçlü çalışır.
5. Test edin ve daraltın. İlk denemede skill ya çok sık ya da hiç tetiklenmez. İki üç gerçek durumda deneyin, tetikleyici cümleyi buna göre netleştirin.

Benim gördüğüm kadarıyla en çok zaman kaybettiren adım 5’i atlamak. İnsanlar yazıp bir daha bakmıyor; oysa skill’in gerçek testi ilk kullanımda değil, üçüncü-dördüncü kullanımda ortaya çıkıyor.

Örnek: Tam Bir SKILL.md Dosyası

Aşağıda basit bir iş için — yeni bir blog sayfası yayınlamadan önce kontrol listesi — tam bir SKILL.md içeriği var. Kopyalayıp kendi işinize göre değiştirebilirsiniz.

`--- name: sayfa-yayin-kontrolu description: Yeni bir blog sayfası veya makale yayınlanmadan önce başlık, açıklama, görsel ve iç link kontrolü yapar. Kullanıcı “yayınlamadan önce kontrol et”, “sayfa hazır mı” veya “yayına almadan bak” dediğinde devreye gir.

Yayın Öncesi Sayfa Kontrolü

Bu skill, bir sayfa yayınlanmadan önce beş kalemi sırayla kontrol eder.

Adımlar

1. Başlığın 50-60 karakter arasında olduğunu ve hedef anahtar kelimeyi içerdiğini doğrula.
2. Meta açıklamanın 140-160 karakter arasında olduğunu ve somut bir fayda içerdiğini doğrula.
3. Sayfada en az bir görsel olduğunu ve görselin boş olmayan bir “alt” metni bulunduğunu kontrol et.
4. Sayfanın en az bir iç link içerdiğini doğrula (ilgili başka bir sayfaya).
5. Yukarıdaki dört maddeden herhangi biri eksikse, hangi maddenin eksik olduğunu ve nasıl düzeltileceğini açıkça listele. Hepsi tamamsa “yayına hazır” de.

Not

Bu kontrol yalnızca biçimseldir; içeriğin doğruluğunu veya kalitesini değerlendirmez.`

Dikkat ederseniz açıklama tek cümlede hem ‘ne yapar’ hem ‘ne zaman kullan’ bilgisini veriyor, adımlar numaralı ve somut, ‘not’ kısmı da skill’in sınırını dürüstçe belirtiyor.

En Sık Yapılan 3 Hata

Onlarca SKILL.md okudum ve yazdım; aynı üç hata sürekli tekrarlanıyor.

1. Çok genel yazmak. ‘İçerik yardımcısı’, ‘SEO uzmanı’ gibi geniş tanımlar asistana hiçbir şey söylemiyor. Ne kadar spesifik yazarsanız, skill o kadar doğru anda devreye giriyor.
2. Çok uzun yazmak. Sayfalarca arka plan bilgisi, gerekçe, felsefe eklemek işe yaramıyor — tam tersi, asistanın önemli adımı gözden kaçırmasına yol açıyor. Ne yapılacağını söyleyin, neden yapıldığını değil.
3. Ne zaman tetikleneceğini belirsiz bırakmak. En yaygın hata bu. İnsanlar ‘bu skill şunu yapar’ yazıp orada bırakıyor, ‘ne zaman kullan’ cümlesini atlıyor. Sonuç: skill ya hiç çalışmıyor ya da alakasız bir konuşmada araya giriyor.

Gerçek Hayattan: Bu Sitede Nasıl Kullanılıyor

Bunu teoride değil, kendi işimde de kullanıyorum. Bu sitenin arka planında, yeni bir sayfa yayınlanmadan önce başlığı, açıklamayı, görseli ve şema işaretlemesini otomatik kontrol eden bir skill çalışıyor — tek satırlık bir komutla tetikleniyor ve hangi standarda göre bakılacağını ben her seferinde hatırlamak zorunda kalmıyorum, skill hatırlıyor. Aynı mantığı müşterilerim için de kuruyorum: haftalık rakip fiyat taraması, kampanya raporu hazırlama, yeni ürün sayfası kontrolü gibi tekrar eden işler için.

Bunun daha geniş resmini Agentic AI Rehberi’nde anlattım — skill’ler, bu rehberde bahsettiğim ‘asistana iş devretme’ fikrinin somut bir uygulaması.

Bu İşi Benden İsteyebilirsiniz

Kendi işiniz için bir SKILL.md yazmak ya da mevcut birkaç skill’i birbirine bağlamak istiyorsanız, bunu ben kuruyorum. Uzaktan, saatlik ücretle çalışıyorum; basit bir kontrol listesi skill’i genelde 2 saat sürer, birden fazla skill’in birbirine bağlandığı bir sistem 2 haftaya kadar çıkabilir. Kendi yapay zeka asistanınız sayfasında kapsamı görebilir, ya da doğrudan yazabilirsiniz.

Sıkça Sorulan Sorular

SKILL.md dosyasını nereye kaydetmem gerekiyor?

Skill’i kullandığınız araca göre değişir; genelde skill’in kendi adını taşıyan bir klasörün içine SKILL.md adıyla kaydedilir, aynı klasöre ekstra dosya (şablon, örnek liste) da koyabilirsiniz. Kod bilmeseniz de klasör oluşturup dosya kaydetmek yeterli — bir metin editörü ve doğru konum dışında bir şey gerekmez.

SKILL.md yazmak için kod bilmem gerekir mi?

Hayır. Dosyanın kendisi düz metin ve markdown biçiminde yazılır — başlık, madde işaretleri, numaralı liste dışında özel bir sözdizimi yok. Zorlaşan tek yer, işi net ve sırayla anlatabilmek; bu bir yazım becerisi, kodlama becerisi değil.

Bir skill ne zaman devreye girer, ben mi tetiklerim yoksa asistan mı karar verir?

İkisi de mümkün. Çoğu zaman asistan, konuşmanın içeriğini dosyadaki ‘açıklama’ kısmıyla karşılaştırıp kendi karar verir. Bu yüzden açıklamayı net yazmak bu kadar önemli. İsterseniz skill’i isim vererek de doğrudan çağırabilirsiniz.

SKILL.md ile asistana yazdığım normal bir talimat (prompt) arasındaki fark nedir?

Normal bir talimatı her seferinde yeniden yazarsınız, o konuşmada kalır. SKILL.md bir kere yazılır, kaydedilir ve her ilgili durumda otomatik hatırlanır — asistana kalıcı bir alışkanlık kazandırmak gibi düşünebilirsiniz.