AI ajan yeteneklerinizi otomatik olarak 0-100 arasında SKILL.md puanlayın

AI ajanları için geliştirilen yetenek dosyaları (SKILL.md), proje performansını doğrudan etkileyen kritik bir bileşen haline geldi. Ancak çoğu geliştirici, bu dosyaları oluştururken subjektif yöntemler kullanıyor ve kalite ölçütlerinden yoksun bırakıyor. Bu boşluğu doldurmak için skillscore adı verilen yeni bir komut satırı aracı geliştirildi.

Bu araç, herhangi bir SKILL.md dosyasını statik olarak analiz ederek 0 ile 100 arasında bir puanlama yapıyor. Ayrıca harf notu ve düzeltme önerileri sunan skillscore, AI ajan yeteneklerinin kalitesini nesnel bir şekilde değerlendiriyor. Aracın en önemli avantajlarından biri, Claude, Codex ve Antigravity gibi popüler AI modelinin yetenek oluşturma kılavuzlarına dayanan 24 adet kontrol kuralı içermesi.

skillscore’un ortaya çıkış nedeni

AI ajan yetenekleri, son dönemde standart bir dosya yapısına dönüştü. Bu yetenekler, name ve description içeren YAML önyüzü ve Markdown formatında talimatlardan oluşan bir SKILL.md dosyası ile tanımlanıyor. Dosya ayrıca references/, examples/ ve scripts/ gibi alt klasörleri de barındırabiliyor. Claude Code, Codex, Antigravity, Gemini CLI ve Cursor gibi araçlar bu standart yapıyı destekliyor.

Ancak burada kritik bir sorun ortaya çıkıyor: AI ajan, yeteneğin `name` ve `description` bilgilerini sürekli olarak bağlam penceresinde tutar. Bu da bulanık bir tanımın sadece kullanılmama riskini artırmakla kalmayıp, her sorguya ek yük getirmesine neden oluyor. AI modelleri, gereksiz bağlam yükünden kaçınmak için net ve öz tanımlara ihtiyaç duyuyor.

AI model üreticileri bu sorunu çözmek için yetenek oluşturma kılavuzları yayınladı. Bu kılavuzlar, tetikleyicilerin öne çıkarılmasını, üçüncü şahıs anlatımının kullanılmasını ve yeteneğin ne zaman kullanılmaması gerektiğinin belirtilmesini öneriyor. Ancak bu kılavuzlar dağınık durumda ve uygulanabilirliği bulunmuyordu. İşte skillscore, bu boşluğu doldurmak için geliştirildi.

skillscore nasıl çalışıyor?

skillscore, AI yetenek dosyalarını doğrulayan ve puanlayan bir CLI aracıdır. Aracın çalışma prensibi, yetenek dosyalarını 7 farklı kategoride analiz etmeye dayanıyor:

• Önyüz geçerliliği (Frontmatter validity): Dosya önyüzündeki --- sınırlayıcıları, name formatı ve description varlığı kontrol ediliyor.
• Tanım kalitesi (Description quality): Üçüncü şahıs anlatımı, öne çıkarılmış tetikleyiciler ve sınırlama cümleleri inceleniyor.
• Özlülük (Conciseness): Dosya uzunluğu, gereksiz açıklamalar ve "veya" zincirleri araştırılıyor.
• Yapı (Structure): İlerleyici açıklama, derin olmayan bağlantılar ve uzun referanslar için içerik tablosu kullanımı değerlendiriliyor.
• Talimat kalitesi (Instruction quality): İş akışı kontrol listeleri, geri bildirim döngüleri ve kod örnekleri inceleniyor.
• İçerik hijyeni (Content hygiene): Tarih referanslarının güncelliği, yol tanımlarının tutarlılığı ve terimlerin uyumu kontrol ediliyor.
• Güvenlik ve betikler (Safety & scripts): Betiklerin belgelenip belgelenmediği ve güvenlik bölümünün varlığına dair cezalandırma puanı uygulanıyor.

Araç, bu kategorilerdeki performansa göre 0 ile 100 arasında bir puan veriyor. Her kategori farklı ağırlıklara sahip ve puanlama sistemi, farklı AI modeli kılavuzlarına göre uyarlanabiliyor. Örneğin, Flutter ekibinin açık kaynaklı bir yetenek dosyası üzerinde yapılan testte, araç %90 puan verdi ve geliştirilmesi gereken iki küçük nokta belirledi.

Aracın kurulumu oldukça basit:

dart pub global activate skillscore

Daha sonra yetenek dosyasını ya da klasörünü şu komutla analiz edebilirsiniz:

skillscore path/to/SKILL.md  # Tek bir yetenek dosyasını puanla
skillscore path/to/skills/   # Tüm yetenekleri analiz et

Gerçek bir yetenek dosyasının analizi

Araç, Flutter ekibinin açık kaynaklı bir yetenek dosyasını (flutter-add-widget-test/SKILL.md) analiz ettiğinde şu sonuçları verdi:

• Toplam puan: 90/100 (A notu)

Kategorilere göre detaylı puanlama:

• Önyüz geçerliliği: 15/15
• Tanım kalitesi: 21/25
• Özlülük: 15/15
• Yapı: 15/15
• Talimat kalitesi: 14/20
• İçerik hijyeni: 10/10

Araç ayrıca iki uyarıda bulundu:

1. E1_anti_patterns: Dosya içerisinde "yapma", "asla" ya da "kaçın" gibi yasaklayıcı ifadeler bulunmuyor. Öneri: "Testler arasında WidgetTester paylaşma."
2. B5_boundary_clause: Tanımda yeteneğin ne zaman kullanılmaması gerektiğine dair bir sınırlama cümlesi yok. Öneri: "Çok sayfalı entegrasyon testleri için kullanma."

Bu bulgular, araç tarafından yayınlanan kılavuzlardan doğrudan alındı ve geliştiricilere net iyileştirme önerileri sunuldu.

CI/CD entegrasyonu ve otomatik denetim

skillscore’un en önemli özelliklerinden biri, CI/CD boru hatlarına kolayca entegre edilebilmesi. Aşağıdaki gibi bir GitHub Actions workflow dosyası ile yeteneklerinizi otomatik olarak denetleyebilirsiniz:

# .github/workflows/skills.yml
- name: AI yeteneklerini denetle
  run: |
    dart pub global activate skillscore
    skillscore skills/ --min-score 80 --no-color

Araç ayrıca farklı çıktı formatları sunuyor:

• JSON formatı: Puanları ve bulguları yapılandırılmış olarak görüntüler.
• SARIF 2.1.0 formatı: GitHub Code Scanning ile entegre olarak pull request'lerde doğrudan hata olarak gösterir.

Komut satırı çıktıları da CI dostu şekilde tasarlandı:

• Çıkış kodu 0: Tüm yetenekler geçer.
• Çıkış kodu 1: En az bir yetenek eşik puanın altında.
• Çıkış kodu 2: Kullanım hatası.

skillscore, LLM’lere karşı avantajları neler?

skillscore, yetenek dosyalarını analiz ederken bazı önemli farklılıklar sunuyor:

• Schema doğrulama: Dosya yapısını ve zorunlu alanları kontrol eder.
• Markdown denetimi: Dosya içeriğinin kalitesini ölçer.
• Kaynak gösterimi: Her bulgu için ilgili kılavuzun kaynağını belirtir.

Buna karşılık, sıradan bir LLM sadece genel bir yorum yapabilir ve kaynağı gösteremez. skillscore’un sunduğu nesnel puanlama ve otomatik düzeltme önerileri, yetenek dosyalarının kalitesini artırmada çok daha etkili bir yol sunuyor.

Gelecekte AI ajanların yetenek dosyaları, proje performansının ayrılmaz bir parçası haline gelecek. skillscore gibi araçlar, geliştiricilerin bu dosyaları daha verimli ve kaliteli bir şekilde oluşturmasına yardımcı olacak. Şimdiden AI projelerinizdeki yetenek dosyalarını analiz etmek için skillscore’u deneyebilir ve puanlarınızı iyileştirmeye başlayabilirsiniz.