SKILL.md Formatı ve YAML Frontmatter Doğrulayıcı

Yapay zeka ajanları belirli iş akışlarını yürütürken harici beceri tanımlarına ihtiyaç duyar. Agent Skills standardı, bu becerilerin standart bir dosya ve dizin yapısı üzerinden tanımlanmasını sağlar. Temel prensip oldukça basittir: Her beceri, kendi adını taşıyan bir klasör içerisinde yer alan SKILL.md adlı bir Markdown belgesiyle ifade edilir. Bu belgenin en üst kısmında üç adet tire ile sınırlandırılmış bir YAML frontmatter bloğu, alt kısmında ise ajanın takip edeceği adım adım talimatları barındıran Markdown gövdesi bulunur.

Ajan sistemleri çalışma anında tüm beceri gövdelerini belleğe doğrudan yüklemez. İlk aşamada yalnızca frontmatter içinde yer alan name ve description alanları taranır. Ajan, kullanıcının talebini yerine getirmek için hangi becerinin uygun olduğuna bu özet bilgilere bakarak karar verir. İlgili beceri tetiklendiğinde gövde metni ve varsa yardımcı referans dosyaları işleme dahil edilir. Bu iki aşamalı yaklaşım hem bağlam penceresi tüketimini düşürür hem de gereksiz token harcamasını önler. Yapılandırma bloklarının doğruluğunu denetlemek için SKILL.md Doğrulayıcı aracını kullanarak söz dizimi hatalarını önceden tespit edebilirsiniz.

Bir SKILL.md belgesinin geçerli sayılabilmesi için YAML frontmatter bloğunun kesin kurallara uyması gerekir. Yapılandırma bloğunda eksik, kapanmamış veya geçersiz söz dizimi bulunması ajanın beceriyi tamamen yok saymasına yol açar. Frontmatter yapısını hazırlarken karmaşık nesneleri dönüştürmek için JSON YAML dönüştürücüsü gibi araçlardan yararlanabilirsiniz.

İsim alanı yalnızca küçük harf, rakam ve ardışık olmayan tek tire içerebilir. Klasör adı belirtilmişse name değeri klasör adıyla birebir eşleşmelidir. Tanım alanı en fazla 1.024, uyumluluk alanı ise en fazla 500 karakter uzunluğunda olmalıdır. Bu sınırların aşılması durumunda SKILL.md Doğrulayıcı doğrudan hata raporlar.

Bir beceri dosyasında en kritik alan description bölümüdür. Ajanlar bir beceriyi seçip çalıştırma kararını neredeyse tamamen bu alandaki ifadelere dayandırır. Tanım alanı teknik olarak 1.024 karaktere kadar izin verse de içerik kalitesi doğrudan tetiklenme başarısını belirler.

Tanımın 60 karakterden kısa olması veya becerinin hangi durumlarda devreye girmesi gerektiğini belirtmemesi yaygın bir eksikliktir. Etkili bir açıklama iki temel unsuru içermelidir: Becerinin ne yaptığı ve tam olarak hangi durumlarda tetiklenmesi gerektiği. Örneğin, "PostgreSQL yedeklerini alır" şeklindeki kısa bir ifade zayıf kalır. Bunun yerine "PostgreSQL veritabanı yedeklerini pg_dump aracıyla alır ve sıkıştırır. Veritabanı yedeği alma, geri yükleme veya tablo dışa aktarma taleplerinde kullanılır." kalıbı ajanın doğru eşleşme kurmasını sağlar. Doğrulama aracı, tanım metninde bu tür tetikleyici anahtar kelimelerin eksikliğini not olarak bildirir.

Frontmatter bloğunun ardından gelen Markdown gövdesi, ajanın beceriyi adım adım işletmesini sağlayan talimatları barındırır. Gövdenin 20 kelimeden kısa olması yetersiz talimat uyarısına, gereğinden uzun olması ise bağlam penceresinin şişmesine neden olur.

Agent Skills şartnamesi gövde metninin 500 satır veya yaklaşık 5.000 token sınırının altında tutulmasını önerir. Doğrulama sürecinde yaklaşık token hesabı 4 karaktere bir token oranıyla tahmin edilir. Türkçe gibi eklemeli dillerde gerçek token sayısı alt kelime parçalamasına bağlı olarak farklılık gösterebilir. Ayrıntılı veri yapıları veya uzun şemalar doğrudan gövdede tutulmak yerine references/ alt klasörüne taşınmalıdır. Gövde içindeki dosya bağlantıları mutlaka göreli olmalı, sistem kök dizinine işaret eden mutlak yollardan kaçınılmalıdır. Belge içinde unutulmuş taslak veya yer tutucu metinler de uyarı olarak listelenir.

Agent Skills açık standart bir belirtimdir; ancak farklı yürütme ortamları bu yapıya kendi özel alanlarını ekleyebilir. Taşınabilir beceriler geliştirmek için standart alanlar ile platforma özgü uzantılar arasındaki farkı bilmek gerekir. Yapılandırma alanlarını programatik olarak işlerken YAML JSON dönüştürücüsü ile nesne modelleri arasında geçiş yapabilirsiniz.

Claude Code ortamında sıkça kullanılan model veya hooks gibi alanlar temel şartnamede yer almaz. Bu alanlar Claude Code tarafından başarıyla işlenirken standart uyumlu diğer ajanlar tarafından göz ardı edilir. Benzer şekilde allowed-tools alanı şartnamede deneysel statüdedir ve YAML dizisi yerine boşlukla ayrılmış tek bir metin dizesi olarak tanımlanmalıdır. Standarda dahil olmayan özel anahtarların doğrudan kök düzeyde değil, metadata nesnesi altında toplanması taşınabilirliği garanti altına alır. Otomasyon ve entegrasyon süreçlerinde güvenliği sağlamak adına harici servis erişimlerinde bot yetkilendirme anahtarları ile kimlik doğrulama katmanları kurgulanmalıdır.

SKILL.md Doğrulayıcı çıktısı üç farklı önem derecesinde bulgu üretir: Hata, uyarı ve not. Bir belgenin geçerli kabul edilmesi için sıfır hata içermesi şarttır. Hatalar belirtim ihlallerini, uyarılar şartname tavsiyelerine aykırı durumları, notlar ise platforma özgü ayrıntıları temsil eder.

İnceleme paneli dosya boyutu, tahmini token adedi, satır ve kelime istatistiklerini özetler. Bulgular tablosu tespit edilen satır numaralarını ve önerilen çözüm adımlarını içerir; bu tablo CSV formatında dışa aktarılabilir. Doğrulayıcı yalnızca söz dizimi ve yapı kurallarını denetler; bağlantı verilen harici dosyaların diskte var olup olmadığını kontrol etmez veya talimatların mantıksal doğruluğunu puanlamaz. Analiz işlemi tamamen tarayıcı içinde yürütülür, kaynak kodlarınız veya kurum içi iş akışlarınız hiçbir sunucuya yüklenmez.