Ajan yeteneği (agent skill) nedir ve nasıl çalışır?

Ajan yeteneğinin gerçekte ne olduğu

Ajan yeteneği, içerisinde SKILL.md adlı bir dosya barındıran disk üzerindeki bir klasördür. Bu dosya; bir isim, kısa bir açıklama ve düz metin (markdown) formatında yazılmış yönergeler içerir. Ajan, açıklamayı başlangıçta yükler ve yönergeleri yalnızca isteğiniz bu açıklamayla eşleştiğinde okur. Yeteneklerle ilgili neredeyse her şey bu iki cümleden türetilir.

Klasör, tek bir dosyadan fazlasını içerebilir. Agent Skills spesifikasyonu üç isteğe bağlı dizin tanımlar: ajanın çalıştırdığı kodlar için scripts/, ihtiyaç duyduğunda okuduğu belgeler için references/ ve şablonlar ile veriler için assets/. Bunların hiçbiri zorunlu değildir. Yalnızca bir SKILL.md içeren bir klasör, tam bir yetenek olarak kabul edilir.

restore-drill/
  SKILL.md
  references/retention-policy.md
  scripts/verify_snapshot.sh

Açıklama kısmı, insanların hafife aldığı bölümdür. Ajanın, yeteneği açıp açmamaya karar vermeden önce gördüğü tek metin budur; bu nedenle yeteneğin ne işe yaradığını ve ne zaman kullanılması gerektiğini, insanların gerçekten yazacağı kelimelerle ifade etmelidir.

Bir yeteneğin kullanılana kadar neredeyse hiçbir maliyetinin olmaması

Bu argüman, formatın neden anlaşılmaya değer olduğunu açıklar ve özelliklerle değil, bağlamla ilgilidir. Yükleme işlemi, spesifikasyonun aşamalı açıklama (progressive disclosure) olarak adlandırdığı evrelerde gerçekleşir.

Başlangıçta ajan, yüklü her yeteneğin name ve description kısımlarını yükler, başka hiçbir şeyi yüklemez. Agent Skills spesifikasyonu, bunu yetenek başına yaklaşık 100 token olarak belirler (Ağustos 2026 itibarıyla yayınlanan kılavuz). Bir düzine yetenek yüklerseniz, yaklaşık bir uzun paragraf kadar bağlam harcamış olursunuz.

Bir istek, bir açıklamayla eşleştiğinde ajan, ilgili SKILL.md dosyasının içeriğini okur. Spesifikasyon, içeriğin 5.000 token altında, dosyanın ise 500 satırın altında tutulmasını önerir. references/ ve scripts/ içindeki dosyalar bu noktada hala hiçbir maliyet oluşturmaz. Bir referans dosyası, yalnızca talimatlar ajanı ona yönlendirdiğinde yüklenir. Paketlenmiş bir betik ise farklı çalışır: ajan onu shell üzerinden çalıştırır, bu nedenle betiğin kaynak kodu bağlam penceresine girmez, yalnızca çıktısı girer.

Şimdi bunu, insanların ilk başvurduğu yöntem olan devasa bir istem (prompt) ile karşılaştırın. Bir sistem istemindeki veya her zaman açık olan talimat dosyasındaki her satır, görev gerektirse de gerektirmese de her istekte ve her oturumda ödenir; ayrıca asıl soruyla dikkat çekmek için rekabet eder. On bin tokenlık sabit talimatlar, saatin kaç olduğunu sormak için bile ödediğiniz bir faturadır. Bir düzine yetenek, bekleme durumunda yaklaşık 1.200 token harcar ve yalnızca ihtiyaç duyulan görev için genişler. Yeteneklerin tüm olayı budur ve küçük bir kütüphanenin uzun bir istemden daha iyi olmasının nedeni de budur.

Bir uyarı noktası insanları yanıltabilir. Bir yetenek yüklendiğinde, içeriği oturumun geri kalanı boyunca bağlamda kalır; bu nedenle uzun bir SKILL.md, tek seferlik değil, tekrarlayan bir maliyettir. Detayları references/ içine taşımak bir düzenleme değildir. Bu, mekanizmanın tasarlandığı gibi çalışmasıdır.

Ajan yeteneği (skill) bir araç çağrısı (tool call) değildir

Araç veya fonksiyon çağrısı olarak da bilinen yapı, modelin tetikleyebileceği bir işlemdir. Çalışma ortamı (harness), modele bir şema gönderir: bir isim, bir açıklama ve argümanların yapısı. Model bir çağrı üretir, kodunuz bunu çalıştırır ve sonuç bir mesaj olarak geri döner. Araçlar eylem gerçekleştirir.

Bir yetenek (skill) ise kendi başına hiçbir şey çalıştırmaz. Ajan yeteneği okur ve ardından halihazırda sahip olduğu araçları kullanarak harekete geçer. Model, bir araca argüman gönderdiği gibi bir yeteneğe argüman gönderemez. Bir yeteneğin yapabileceği şey, modele hangi araçları, hangi sırayla kullanacağını ve sonrasında neleri kontrol etmesi gerektiğini söylemektir.

Kısacası: bir araç ajana yeni bir kabiliyet kazandırır, bir yetenek ise ajana zaten sahip olduğu bir kabiliyet hakkında muhakeme yetisi sağlar. Eğer bir adımın her seferinde kesin ve doğrulanmış bir sonuç üretmesi gerekiyorsa, bir araca veya betiğe (script) ihtiyacınız vardır. Eğer bir adımın tutarlı bir şekilde aynı düşünce sürecini uygulaması gerekiyorsa, bir yeteneğe ihtiyacınız vardır.

Bir agent becerisi (skill) bir MCP sunucusu değildir

MCP (model context protocol), bir agent'ı dış bir sisteme bağlamak için kullanılan bir protokoldür. Bir MCP sunucusu; çalışan, bu protokolü konuşan ve agent'a araçlar sunan bir süreçtir (process). Genellikle yapılandırma, kimlik bilgileri ve yerel bir komut ya da ağ uç noktası gerektirir. Bir beceri (skill) ise içinde markdown dosyası bulunan bir klasördür. Burada herhangi bir süreç, port veya protokol yoktur.

Bağlam maliyeti de aynı şekilde farklılık gösterir. Bir MCP sunucusunun sunduğu her araç; bir isim, açıklama ve argüman şeması taşır ve varsayılan olarak bunlar, kullanılsın ya da kullanılmasın, tüm oturum boyunca istek içerisinde yer alır. Bazı istemciler araç şemalarını talep üzerine getirmeye başlamış olsa da, bunları önceden yüklemek hala standart durumdur. Bekleme halindeki bir beceri ise sadece bir satırlık metinden ibarettir.

Bu ikisi birbirini tamamlayıcı niteliktedir ve en güçlü kurulumlar her ikisini de çalıştırır. MCP sunucusu erişimi sağlar. Beceri ise prosedürü sunar: ekibinizin gerçek iş akışı için bu araçlardan hangisinin, hangi sırayla çağrılacağı ve iyi bir sonucun neye benzediği. Kendi sunucunuzu barındırıyorsanız, VPS üzerinde MCP sunucuları çalıştırma rehberi bu konunun o tarafını kapsamaktadır.

Ajan yeteneği, sistem istemi veya AGENTS.md dosyası değildir

Her ikisi de markdown formatında talimatlar içerdiğinden bu karışıklık anlaşılabilirdir. Aralarındaki fark, yüklenme zamanlarıdır. AGENTS.md, CLAUDE.md ve sistem istemi her zaman etkindir. Bir yetenek ise talep üzerine devreye girer.

Bunu test etmek için tek bir soru yeterlidir: Bu paragrafı görmezden gelmek, bununla ilgisi olmayan bir görevde hata yaratır mı? Kurumsal stil, derleme komutu ve dal adlandırma kuralı her görev için geçerlidir; bu nedenle her zaman yüklenmelerinin amaçlandığı, her zaman açık olan dosyada yer alırlar. Ayda iki kez çalıştırdığınız sürüm kontrol listesi her görev için geçerli değildir, bu yüzden bir yetenek dosyasına aittir. Her zaman açık olan dosyanızdaki bir bölüm numaralandırılmış bir prosedüre dönüştüğünde, bu onu taşımanız gerektiğinin işaretidir.

Bu dosyaların doğru şekilde uygulanması gereken kendi kuralları vardır. Kullandığımız iki dosya için AGENTS.md dosyasında nelerin, insan dosyasında nelerin yer alması gerektiği ve kod tabanının yapısını açıklayan bir design.md bölümlerine bakınız.

Minimal bir yetenek yapısı

Claude Code içerisinde kişisel yetenekler ~/.claude/skills/<name>/SKILL.md dizininde tutulur ve tüm projeleriniz için geçerli olur. Proje bazlı yetenekler ise .claude/skills/<name>/SKILL.md dizininde yer alır ve git ile commit edilir; böylece o depoda çalışan her kişi ve her ajan bu yeteneklere sahip olur. GitHub Copilot ve VS Code ise çalışma alanı yeteneklerini bunun yerine .github/skills/ dizininden okur. İçerideki dosya aynı dosyadır.

mkdir -p ~/.claude/skills/restore-drill

---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---

# Restore drill

1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.

If `restic snapshots` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

Bu, eksiksiz bir yetenektir. Dizin adı, yazdığınız komut haline gelir; dolayısıyla bu örnekte komut /restore-drill olur. Claude Code içerisinde /skills menüsü, yüklü olanları listeler; dosyanın algılandığını doğrulamanın en hızlı yolu budur. Eğer bu menüde görünmüyorsa bir isimlendirme hatası vardır: dosya mutlaka SKILL.md olarak adlandırılmalı ve dizin adı küçük harfler, rakamlar ve tek tire işaretlerinden oluşmalıdır. Aynı işlem adımlarının bir ajanın tekrar çalıştırabileceği bir prosedür olarak yazılması, bir VPS üzerinde zamanlanmış restic yedeklemeleri için doğal bir tamamlayıcıdır; zira yedeklemenin çalışması ile yedekten geri dönülmesi aynı şey değildir.

Bir beceri ne zaman betik olmalıdır

Her seferinde tek bir doğru cevabı olan her adım bir betik olmalı; beceri ise sadece bu betiğin ne zaman çalıştırılacağını ve çıktısının nasıl okunacağını belirten birkaç satıra indirgenmelidir. Bunun iki nedeni vardır ve her ikisi de pratiktir.

Birincisi, bir betiğin kaynak kodu bağlam penceresine asla girmez. 300 satırlık bir ayrıştırıcı (parser) size sadece çıktısına mal olurken, aynı mantığın markdown talimatları olarak yazılması, beceri her yüklendiğinde tüm uzunluğu kadar maliyet oluşturur.

İkincisi, bir betik iki kez aynı cevabı verir. Her çalıştırmada aynı günlük ayrıştırma kuralını yeniden türetmesi istenen bir model, kötü bir gününde bunu biraz farklı yapabilir ve siz iki sayı birbiriyle uyuşmayana kadar bunu fark etmezsiniz.

Bu yüzden işi türüne göre ayırın. "CSV dosyasını ayrıştır ve toplamın kalemlerle eşleşmediği her satırı yazdır" bir betiktir. "Betiğin yazdırdığı satırlara bak ve hangilerinin veri girişi hatası gibi göründüğünü açıkla" ise bir beceri talimatıdır. Yargıyı markdown içinde, determinizmi ise kod içinde tutmak, bir ajanın siz izlemeden çalıştırabileceği bir döngü oluşturmak ile aynı disiplindir.

Beceri tetikleyicim neden hiç çalışmıyor?

Bunun nedeni, description kısmının becerinin ne yaptığını açıklaması ancak ne zaman kullanılacağını belirtmemesidir. Ajanın, isteğinizi eşleştirmek için elindeki tek veri bu tek satırdır. "Veritabanı işlerine yardımcı olur" ifadesi hiçbir şeyle özel olarak eşleşmez. "Staging veritabanında şema migrasyonu çalıştırır. Kullanıcı bir tabloyu taşımayı, sütun eklemeyi veya şemayı değiştirmeyi istediğinde kullanın" ifadesi ise bir kişinin gerçekte yazdığı kelimeleri içerdiği için tetiklenir.

Bunun zıttı olan hata ise sürekli tetiklenen beceridir. "Bu depodaki tüm kod değişiklikleri için kullanın" gibi bir açıklama her şeyle eşleşir; bu nedenle gövde her görevde yüklenir ve oturumun geri kalanında bağlamda kalır. Açıklamayı, amaçladığınız durumla sınırlandırın. Claude Code içerisinde ayrıca frontmatter kısmında disable-model-invocation: true ayarını yapabilirsiniz; bu, otomatik yüklemeyi durdurur ve beceriyi adını yazdığınızda kullanılabilir tutar.

Üçüncü hata ise bir aracı kopyalayan beceridir. Ajana, MCP sunucusunun zaten sunduğu bir API'yi curl etmesini söyleyen veya arama aracı varken dosyalarda grep yapmasını isteyen talimatlar, size daha yavaş bir yol ve birbiriyle çelişebilecek iki farklı talimat seti sunar. Kopyayı silin ve bunun yerine amacı tanımlayın.

Hangi hataya sahip olduğunuzu tahmin etmeyin. Aynı istemi yeni bir oturumda iki kez çalıştırın; birinde beceri açık, diğerinde kapalı olsun, ardından yanıtları karşılaştırın. Yeni oturum önemlidir çünkü beceriyi yazdığınız oturum zaten becerinin söylediği her şeyi içerir; bu da yazılı sürümdeki boşlukları gizler. Anthropic'in skill-creator eklentisi, Claude Code içinde bu karşılaştırmayı otomatikleştirir; buna beceriyi tetiklemesi ve tetiklememesi gereken istemlerin oluşturulması ve her birinin ne sıklıkla tetiklendiğinin ölçülmesi de dahildir.

Bu tek bir satıcının formatı mı yoksa bir standart mı?

Anthropic, formatı 2025 yılının sonlarında yayınladı ve ardından agentskills.io üzerinde barındırılan açık bir standart olarak kullanıma sundu. Ağustos 2026 itibarıyla bu şartname; gerekli name ve description alanlarını, isteğe bağlı license, compatibility, metadata ve allowed-tools alanlarını, üç isteğe bağlı dizini ve aşamalı yükleme davranışını tanımlamaktadır. Ayrıca bir referans doğrulayıcı ile birlikte gelir, böylece skills-ref validate ./my-skill bir klasörü paylaşmadan önce şartnameye uygunluğunu denetler.

İstemci listesi asıl göstergedir. Aynı klasör; Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands ve opencode gibi araçlar tarafından okunabilmektedir. Microsoft, kendi yeteneklerini bu formatta github.com/microsoft/skills adresinde yayınlamakta ve bir görevi bir kez yaparken sizi izleyen, bunu bir niyet ve sıralı adımlar olarak yeniden oluşturan ve sonucu bir yetenek olarak kaydeden Skill Recorder adlı bir masaüstü aracı sunmaktadır. Çıktı formatı başka birinin şartnamesine ait olan bir kaydedici geliştiren satıcı, formatın artık tek bir ürünün özelliği olmaktan çıktığının iyi bir işaretidir.

İlk olarak ne yazılmalı

Bir kütüphane planlamayın. Aynı talimatları üçüncü kez bir sohbete yapıştırdığınızı fark edene kadar bekleyin, ardından bu metni bir SKILL.md içine taşıyın ve yapıştırdığınız metni silin. Hissedilen tekrarlar, saklamaya değer bir becerinin tek güvenilir tetikleyicisidir. Bir arama prosedürü iyi bir ilk adımdır ve kendi SearXNG örneğinizle desteklenen bir arama becerisi bunun biçimini gösterir.

İki alışkanlık kütüphaneyi sağlıklı tutar. Yazmadığınız her beceriyi, betikler dahil, yüklemeden önce okuyun; çünkü bir beceri, temsilcinizin takip edeceği talimatlar ve çalıştırabileceği kodlardan oluşur: ona yabancı bir kaynaktan yazılım yüklüyormuş gibi davranın. Ayrıca kimlik bilgilerini klasörün dışında tutun, çünkü bir beceri commit edilen ve paylaşılan bir metin dosyasıdır. Sırları temsilcilerinizden uzak tutmak, bu değerlerin nerede bulunması gerektiğini açıklar ve bu yıl temsilcileri öğrenmek için yol haritası, becerileri kurulumun geri kalanıyla birlikte sıraya koyar.

FAQ

Agent yeteneği (skill) ile MCP sunucusu arasındaki fark nedir?

MCP (model context protocol) sunucusu, bir protokol üzerinden aracıya (agent) araçlar sunan çalışan bir süreçtir; bu nedenle yapılandırma ve kimlik bilgileri gerektirir ve araç tanımları, kullanılsalar da kullanılmasalar da oturum boyunca bağlamı (context) işgal eder. Agent yeteneği ise SKILL.md dosyasını barındıran bir klasördür; herhangi bir süreç veya protokol içermez ve aracı onu okumaya karar verene kadar yaklaşık 100 token maliyeti vardır. Bir aracıya sisteme erişim yetkisi vermek için MCP sunucusu kullanın. Bu erişimi verimli kullanması için aracıya izlemesi gereken prosedürü öğretmek için ise yetenek (skill) kullanın. Birçok kurulum her ikisini de birlikte çalıştırır.

Agent yetenekleri yalnızca Claude Code ile mi çalışır?

Hayır. Anthropic bu formatı geliştirmiş ve ardından agentskills.io adresinde açık bir standart olarak yayınlamıştır; aynı klasör yapısı Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands ve diğer istemciler tarafından da okunabilir. Farklılık, her istemcinin nereyi taradığı ve hangi ek ön bilgi (frontmatter) alanlarını anladığı noktasında ortaya çıkar. Claude Code ~/.claude/skills/ ve .claude/skills/ dosyalarını okurken, GitHub Copilot ve VS Code depo içerisindeki .github/skills/ dosyasını okur. SKILL.md dosyasının kendisi ise hiçbir değişiklik yapılmadan bu araçlar arasında taşınabilir.

Performans düşüşü yaşamadan kaç tane yetenek yükleyebilirim?

Buradaki kısıtlayıcı faktör sayıdan ziyade başlangıç bütçesidir. Yüklenen her yetenek, yayınlanan teknik kılavuza göre yaklaşık 100 token değerinde olan adını ve açıklamasını sisteme dahil eder; dolayısıyla otuz yetenek, henüz hiçbiri kullanılmadan önce yaklaşık 3.000 token maliyet oluşturur. İlk olarak hız değil, eşleştirme performansı düşer: birbirinin kapsamına giren açıklamalara sahip çok sayıda yetenek, modelin doğru olanı seçmesini zorlaştırır. Birbiriyle çakışmayan açıklamalar yazın ve artık kullanmadığınız yetenekleri silin.

Bu talimat bir yetenek dosyasında mı yoksa AGENTS.md içinde mi yer almalı?

Talimatın depodaki her görev için geçerli olup olmadığını sorgulayın. Derleme komutları, kurum içi stil rehberleri ve isimlendirme kuralları tüm görevler için geçerlidir; bu nedenle her zaman aktif olan dosyada bulunmaları gerekir, çünkü her seferinde yüklenmeleri amaçlanmıştır. Sürüm kontrol listesi veya geri yükleme tatbikatı gibi ara sıra çalıştırdığınız bir prosedür ise yetenek olarak tanımlanmalıdır; böylece bu işleme ihtiyaç duymayan görevlerde herhangi bir maliyet oluşturmaz. AGENTS.md dosyasının numaralandırılmış adımlara dönüşerek büyüyen bir bölümü, genellikle yetenek dosyasına taşınmayı bekleyen bir yapıdır.