Ajan becerileri: yapısı, yüklenmesi, taşınabilirliği ve sınırları

Ajan becerisi, bir ajana belirli türde bir işi iyi yapmayı öğreten talimatlardan ve isteğe bağlı olarak betiklerden ve referans dosyalarından oluşan bir klasördür. Fikir mütevazıdır. Aynı uzun açıklamayı her sohbete yapıştırmak ya da her zaman yüklü duran bir sistem istemine gömmek yerine, onu bir kez paketlersiniz ve ajan görev gerektirdiğinde içeri alır. Pek çok ajan aracının bugün paylaştığı biçim, SKILL.md adlı bir dosyanın etrafında kuruludur. Bu yazı bir becerinin nasıl yapılandığını, ne zaman yüklendiğini, gerçekte ne kadar taşınabilir olduğunu ve yetkisinin nerede bittiğini anlatıyor.

Bir becerinin anatomisi

Beceri bir dizindir. Yalnızca bir dosya zorunludur; geri kalan her şey isteğe bağlıdır.

release-notes/
  SKILL.md            zorunlu: üst veri ve talimatlar
  scripts/
    collect.sh        ajanın çalıştırabileceği yardımcı betik
  references/
    style-guide.md    uzun içerik, yalnızca gerektiğinde okunur
  assets/
    template.md       çıktıda kullanılan dosyalar

SKILL.md, küçük bir YAML ön bilgi (front matter) bloğuyla açılır, ardından sıradan Markdown gelir:

---
name: release-notes
description: Son etiketten bu yana birleştirilen değişikliklerden sürüm
  notu taslağı hazırlar. Sürüm notu, değişiklik günlüğü girdisi ya da
  nelerin yayına çıktığının özeti istendiğinde kullan. Pazarlama
  duyuruları için değil.
---

# Sürüm notları

1. Son etiketten bu yana birleştirilen değişiklikleri listelemek için
   scripts/collect.sh betiğini çalıştır.
2. Değişiklikleri Eklenenler, Değişenler, Düzeltilenler ve Kaldırılanlar
   başlıkları altında grupla.
3. Üslup ve uzunluk için references/style-guide.md dosyasına uy.
4. Belirli bir değişikliğe bağlayamadığın her şeyi "doğrulanmadı" diye işaretle.

Yükün çoğunu iki zorunlu alan taşır. name kısa, küçük harfli ve tireyle ayrılmış bir tanımlayıcıdır. description ise becerinin ne yaptığını ve ne zaman kullanılacağını söyler; ajanın beceriyi yükleyip yüklememeye karar vermeden önce gördüğü tek kısım budur. Bazı araçlar lisans, uyumluluk notları ya da becerinin beklediği araçların listesi gibi ek isteğe bağlı alanları da okur; ajanınızın hangilerini desteklediğini kontrol edin. Açık spesifikasyon agentskills.io adresinde yayımlanıyor.

Beceri ne zaman yüklenir

Beceriler kademeli açılım ilkesine göre tasarlanmıştır: ajan ayrıntının bedelini yalnızca ona ihtiyaç duyduğunda öder.

1. Başlangıçta ajan, kurulu her becerinin yalnızca adını ve açıklamasını okur; böylece kalabalık bir koleksiyon bile bağlamda çok az yer kaplar.
2. Bir görev bir açıklamayla eşleştiğinde ajan o SKILL.md dosyasının gövdesini baştan sona okur.
3. Talimatlar bir dosyayı işaret ettiğinde ajan o dosyayı açar ya da bir betiği çalıştırıp yalnızca çıktısını okur. Klasörün tamamını hiçbir zaman içeri çekmez.

Bundan iki pratik sonuç çıkar. Birincisi, tetikleyici açıklamadır. Belirsiz bir açıklama ("dokümanlarla ilgili yardım eder") yanlış anlarda yüklenir ya da hiç yüklenmez; somut bir açıklama ise görevi, insanların o görev için kullandığı ifadeleri ve kapsamadığı durumları adıyla söyler. İkincisi, gövdeyi yalın tutun. Uzun referans içeriğini ayrı dosyalara koyun ki gerekene kadar hiçbir bedeli olmasın; bir dosya biçimini ayrıştırmak gibi belirlenimci işleri de ajandan düz yazıyla yapmasını istemek yerine betiklere taşıyın.

Beceri, araç, istem ve MCP

Beceriler sık sık bir ajanı genişletmenin diğer yollarıyla karıştırılır. Fark, her birinin ne sağladığındadır.

Bunlar doğal olarak birlikte çalışır. Bir beceri, bir MCP sunucusunun sunduğu aracın nasıl kullanılacağını anlatabilir ya da bir komut satırı programını bir betikle sarmalayabilir. Seçim yapmanız gerektiğinde üçünü MCP, beceri mi CLI mı yazısı karşılaştırıyor; bir beceriyi adım adım kurmayı ise bir CLI'ı ajan becerisine dönüştürmek rehberi anlatıyor.

Beceriler gerçekte ne kadar taşınabilir

Beceri düz dosyalardan oluştuğu için kolayca taşınır: klasörü kopyalarsınız, bir depoya eklersiniz, ekiple paylaşırsınız. Aynı düzeni okuyan ajan araçları giderek çoğalıyor. Talimatlar iyi taşınır; varsaydıkları ortam ise her zaman onlarla birlikte gelmez.

• Betikler bir yorumlayıcı, bir kabuk ve bir işletim sistemi varsayar. Bash ile yazılmış bir yardımcı, yalnızca PowerShell bulunan bir yerde olduğu gibi çalışmaz.
• Talimatlar bir ajanda bulunup diğerinde bulunmayan araçların adını verebilir. "Tarayıcı aracını kullan" talimatı, tarayıcısı olmayan bir ajan için hiçbir şey ifade etmez.
• İsteğe bağlı alanlar her yerde aynı şekilde dikkate alınmaz. Bir üründe araçları kısıtlayan bir alan, bir sonrakinde görmezden gelinebilir.
• Yollar ve kimlik bilgileri makineden makineye, ekipten ekibe değişir.

Bir beceriyi taşınabilir tutmak için tek bir ürünün araç adları yerine ulaşılacak sonucu anlatın, bağımlılıkları en başta belirtin, betiklerde yaygın yorumlayıcıları tercih edin ve beceriyi çalıştırmasını beklediğiniz her ajanda test edin.

Beceriyi kod gibi inceleyin

Beceri; ajanın zaten sahip olduğu erişimle izleyeceği bir talimat ve çalıştırabileceği betiklerdir. Herkese açık bir koleksiyondan beceri kurmak, yeni bir bağımlılık eklerken gösterdiğiniz dikkati hak eder. Kurmadan önce okuyun ve şunlara bakın:

• Ajana onayları atlamasını, kontrolleri kapatmasını ya da yaptığını gizlemesini söyleyen talimatlar.
• Ağ çağrısı yapan, kimlik bilgilerini okuyan ya da görevin kapsamı dışındaki dosyalara dokunan betikler.
• İlgisiz görevlerde de yüklenip onların davranışını sessizce değiştirecek kadar geniş bir açıklama.
• Referans dosyalarında ajana seslenip yeni talimat veren metinler.

İncelediğiniz sürümü sabitleyin, her değişikliğin bir fark (diff) olarak görünmesi için becerileri sürüm denetiminde tutun ve kimsenin kullanmadığı becerileri kaldırın. Daha kapsamlı bir yöntem için topluluk becerilerini kurmadan önce incelemek yazısına bakın.

Beceri bir izin değildir

En önemli sınır aynı zamanda en kolay unutulanıdır: beceri bir şeyin nasıl yapılacağını anlatır, kimseye onu yapma yetkisi vermez. "Canlı ortama dağıtım yapabilirsin" diyen bir SKILL.md hiçbir şey vermez. Ajanın dağıtım yapıp yapamayacağı; taşıdığı kimlik bilgilerine, çağırmasına izin verilen araçlara ve ortamının uyguladığı onaylara bağlıdır. Bir becerinin talimatları ajanın mevcut erişimiyle tehlikeli olacaksa çözüm beceriyi yeniden yazmak değil, erişimi daraltmaktır.

GoCux bunu bir gelenek olarak değil, bir kural olarak uygular: yeniden kullanılabilir hiçbir talimat izin yerine geçmez. İş; hedefi, kapsamı ve kabul ölçütleri olan bir iş emriyle tanımlanır ve işin ihtiyaç duyduğu becerileri GoCux seçer; bir becerinin seçilmesi kapsamı asla genişletmez. Dışarıya bir şey göndermekten ajanın kendi talimatlarını yeniden yazmasına kadar sonuç doğuran eylemler bir ekip arkadaşı karar verene kadar bekler ve her adım ekibin okuyabildiği bir kayda düşer. Bunun pratikte nasıl işlediğini ajan becerileri belgeleri ve yönetişim sayfası anlatıyor.

İlk becerinizi yazarken

• Tekrar tekrar anlattığınız ve bittiği anlaşılabilen tek bir görev seçin.
• Önce açıklamayı yazın: ne yapar, ne zaman kullanılır, ne zaman kullanılmaz.
• Gövdede yalnızca adımlar ve kurallar kalsın; uzun referans içeriğini ayrı dosyalara taşıyın.
• Belirlenimci adımları betiklere taşıyın, gizli bilgileri klasörün dışında tutun.
• Beceriyi yüklemesi gereken ve yüklememesi gereken istemlerle test edin.
• Riskli eylemleri dizginleyenin beceri metni değil, ajanın erişimi olduğundan emin olun.
• Beceriyi sürüm denetimine alın ve değişiklikleri kod incelemesi yapar gibi gözden geçirin.