Ajan yeteneği 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ış talimatları içerir. Ajan, açıklamayı başlangıçta yükler ve talimatları yalnızca isteğiniz bu açıklamayla eşleştiğinde okur. Yeteneklerle ilgili diğer hemen hemen her şey bu iki cümleden türetilir.

Klasör, tek bir dosyadan fazlasını barındırabilir. 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. Sadece 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, bir insanın gerçekten yazabileceği kelimelerle ifade etmelidir.

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

Formatın anlaşılmaya değer olmasını sağlayan argüman budur; konu özellikler değil, bağlamdır. Yükleme işlemi, teknik şartnamenin aşamalı açıklama (progressive disclosure) olarak adlandırdığı aşamalar halinde 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 şartnamesi, 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 gövdesini okur. Şartname, gövdenin 5.000 token altında ve dosyanın 500 satır 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ıdır: Ajan onu shell üzerinden çalıştırır, bu nedenle betiğin kaynağı hiçbir zaman bağlam penceresine girmez, sadece çı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 bir talimat dosyasındaki her satır, görev gerektirse de gerektirmese de her istekte ve her oturumda ödenir; ayrıca gerçek soruyla dikkat çekmek için rekabet eder. On bin token'lık sabit talimatlar, saatin kaç olduğunu sormak için bile ödediğiniz bir faturadır. Bir düzine yetenek ise bekleme durumunda yaklaşık 1.200 token maliyetindedir ve yalnızca ihtiyaç duyulan görev için genişler. Yeteneklerin tüm olayı budur ve küçük bir kütüphanenin neden daha uzun bir istemden daha iyi olduğunun açıklamasıdır.

İnsanları yanıltan bir uyarı mevcuttur. Bir yetenek yüklendiğinde, gövdesi 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 çabası değildir. Bu, mekanizmanın tasarlandığı gibi çalışmasıdır.

Ajan yeteneği bir araç çağrısı değildir

Bir araç, function call olarak da adlandırılır ve modelin çağırabildiği bir bileşendir. Harness, modele bir şema gönderir: ad, açıklama ve bağımsız değişkenlerin yapısı. Model bir çağrı üretir, kodunuz bu çağrıyı çalıştırır ve sonuç bir mesaj olarak geri gelir. Araçlar işlem gerçekleştirir. Bu iletişimin her iki tarafı da harness'a, modelin etrafındaki döngüyü çalıştıran programa aittir. Başlangıçta skill açıklamalarınızı okuyan ve ne zaman bir skill açılacağına karar veren de aynı bileşendir.

Bir yetenek (skill) ise kendi başına hiçbir şey çalıştırmaz. Ajan yeteneği okur ve ardından zaten sahip olduğu araçları kullanarak hareket eder. 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ırada kullanacağını ve sonrasında neleri kontrol etmesi gerektiğini söylemektir.

Kısaca özetlemek gerekirse: bir araç ajana yeni bir kabiliyet kazandırır, bir yetenek ise zaten sahip olduğu bir kabiliyet hakkında ona 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 ihtiyacınız vardır. Eğer bir adımın tutarlı bir şekilde aynı düşünce sürecinden geçmesi gerekiyorsa, bir yeteneğe ihtiyacınız vardır. Bir yetenek sadece muhakemeden ibaret olsa bile en çok başvurduğunuz yöntem olabilir; kodlama yapan bir ajanı çalışan en küçük değişikliği yapmaya zorlayan Ponytail örneğinde görüldüğü gibi: bu yetenek yeni bir kabiliyet eklemez, sadece ajanın mevcut kabiliyetlerini kullanma biçimini değiştirir.

Bir agent yeteneği (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 yetenek (skill) ise içinde bir markdown dosyası bulunan bir klasördür. Burada bir süreç, port veya protokol bulunmaz.

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ılsa da kullanılmasa da 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 durumundaki bir yetenek ise sadece bir satır metinden ibarettir.

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

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

Her ikisi de Markdown içindeki talimatlardır; bu nedenle karıştırılmaları normaldir. Fark, yüklenme zamanlarıdır. AGENTS.md, CLAUDE.md ve system prompt her zaman etkindir. Bir skill yalnızca istendiğinde etkinleşir. Claude Code'un output styles seçenekleri her zaman etkin olma düzeyinin en uç noktasındadır; çünkü bunlardan birinin seçilmesi system prompt'un kendisini düzenler. Bu nedenle oturumdaki her yanıtı şekillendirir; hiçbir skill'in etkilemediği yanıtlar da buna dahildir.

Bunu test etmek için tek bir soru yeterlidir: Bu paragrafı görmezden gelmek, konuyla ilgisi olmayan bir görevde hata teşkil eder mi? Kurumsal stil, derleme komutu ve dal adlandırma kuralı her görev için geçerlidir; bu nedenle her zaman etkin olan dosyada yer almalıdırlar, çünkü her seferinde yüklenmeleri amaçlanmıştır. 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 etkin 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 uygulanması gereken kendilerine has kuralları vardır. Kullandığımız iki dosya için AGENTS.md dosyasında neyin, insan dosyasında neyin 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 nasıl görünür

Claude Code içinde kişisel yetenekler ~/.claude/skills/<name>/SKILL.md dizininde yaşar ve tüm projelerinize uygulanır. Proje yetenekleri ise .claude/skills/<name>/SKILL.md dizininde bulunur 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, ç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 şeklindedir. Claude Code içinde /skills menüsü, nelerin yüklü olduğunu listeler; bu, dosyanın algılandığını doğrulamanın en hızlı yoludur. Eğer bu menüde görünmüyorsa, bir isim hatası vardır: dosyanın adı mutlaka SKILL.md olmalı ve dizin adı küçük harfler, rakamlar ve tek tire işaretlerinden oluşmalıdır. Aynı işlem dizisi, ajanınızın yeniden çalıştırabileceği bir prosedür olarak yazıldığında, bir VPS üzerinde zamanlanmış restic yedeklemeleri için doğal bir tamamlayıcıdır; zira yedeklemenin çalışması ile yedeklemenin geri yüklenmesi 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 (context window) asla girmez. 300 satırlık bir ayrıştırıcı (parser) size sadece çıktısına mal olur, ancak aynı mantık markdown talimatları olarak yazıldığında, beceri her yüklendiğinde tüm uzunluğu kadar yer kaplar.

İkincisi, bir betik aynı soruya iki kez aynı cevabı verir. Her çalıştırıldığında aynı günlük (log) 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ı 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.

Yeteneğim neden hiç tetiklenmiyor?

Bunun nedeni, description kısmınızın yeteneğin ne yaptığını açıklaması ancak ne zaman kullanılacağını belirtmemesidir. Ajanın, isteğinizi eşleştirmek için sahip olduğu tek veri o satırdır. "Veritabanı işlemlerine yardımcı olur" ifadesi hiçbir şeyle 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çekten yazdığı kelimeleri içerdiği için tetiklenir.

Bunun tam tersi hata ise sürekli tetiklenen yeteneklerdir. "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ğlam içinde kalır. Açıklamayı, amaçladığınız durumla sınırlandırın. Claude Code içinde, otomatik yüklemeyi durduran ve yeteneği yalnızca adını yazdığınızda kullanılabilir kılan disable-model-invocation: true ayarını da frontmatter içinde belirleyebilirsiniz.

Üçüncü hata ise bir aracı kopyalayan yetenektir. Ajana, MCP sunucusunun zaten sunduğu bir API'yi curl etmesini söyleyen veya sistemde halihazırda bir arama aracı varken dosyalar içinde 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 yetenek açık, diğerinde kapalı olsun, ardından yanıtları karşılaştırın. Yeni oturum önemlidir; çünkü yeteneği yazdığınız oturum zaten yeteneğin söylediği her şeyi içerir ve bu durum yazılı versiyondaki boşlukları gizler. Anthropic'in skill-creator eklentisi, yeteneği tetiklemesi gereken ve tetiklememesi gereken istemleri oluşturmak ve her birinin ne sıklıkla tetiklendiğini ölçmek dahil olmak üzere, bu karşılaştırmayı Claude Code içinde otomatikleştirir.

Bu bir satıcı formatı mı yoksa 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, zorunlu 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 yazan 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, korunmaya değer bir becerinin tek güvenilir tetikleyicisidir. Bir arama prosedürü iyi bir başlangıçtır ve kendi SearXNG örneğinizle desteklenen bir arama becerisi bunun nasıl göründüğünü ortaya koyar.

İki alışkanlık kütüphaneyi sağlıklı tutar. Bir beceriyi yüklemeden önce, betikler dahil olmak üzere, yazmadığınız her beceriyi okuyun; çünkü beceri, temsilcinizin izleyeceği talimatlar ve çalıştırabileceği kodlardan oluşur: ona yabancı birinden yazılım yüklüyormuş gibi davranın. Ayrıca kimlik bilgilerini klasörün dışında tutun, çünkü 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 ile MCP sunucusu arasındaki fark nedir?

Bir MCP (model context protocol) sunucusu, araçları bir protokol üzerinden ajana 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ı işgal eder. Bir agent yeteneği ise, herhangi bir süreç veya protokol içermeyen, SKILL.md dosyasını barındıran bir klasördür ve ajan onu okumaya karar verene kadar yaklaşık 100 token maliyeti vardır. Bir ajana sisteme erişim sağlamak için MCP sunucusu kullanın. Bu erişimi verimli kullanması için ajana prosedürü öğretmek amacıyla ise yetenek 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 Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands ve diğer istemciler tarafından okunabilir. Farklılık, her istemcinin nereye baktığı ve hangi ek ön bilgi (frontmatter) alanlarını anladığıdır. Claude Code ~/.claude/skills/ ve .claude/skills/ dosyalarını okurken, GitHub Copilot ve VS Code depodaki .github/skills/ dosyasını okur. SKILL.md dosyasının kendisi ise aralarında hiçbir değişiklik olmadan taşınabilir.

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

Kısıtlayıcı faktör sayıdan ziyade başlangıç bütçesidir. Yüklenen her yetenek, spesifikasyonun yayınlanan kılavuzuna göre yaklaşık 100 token değerinde olan adını ve açıklamasını sisteme ekler; dolayısıyla otuz yetenek, hiçbiri kullanılmasa bile yaklaşık 3.000 token maliyet oluşturur. İlk önce hız değil, eşleştirme performansı düşer: birbiriyle örtüşen açıklamalara sahip çok sayıda yetenek, modelin doğru olanı seçmesini zorlaştırır. Örtüşmeyen açıklamalar yazın ve artık kullanmadığınız yetenekleri silin.

Bu talimat bir yeteneğe mi yoksa AGENTS.md dosyasına mı eklenmeli?

Talimatın depodaki her görev için geçerli olup olmadığını sorgulayın. Derleme komutları, kurum içi stil ve isimlendirme kuralları hepsine uygulandığı için her zaman açık olan dosyada yer almalıdır; burada 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 yetenek olmalıdır; böylece buna ihtiyaç duymayan görevlerde hiçbir maliyet oluşturmaz. AGENTS.md dosyasının numaralandırılmış adımlara dönüşmüş bir bölümü, genellikle taşınmayı bekleyen bir yetenektir.