Ajan yeteneği (Agent Skill) nedir ve nasıl çalışır?
Ajan yeteneği, SKILL.md dosyası içeren özel bir klasör yapısıdır. Büyük istemler yerine neden daha verimli olduğunu, MCP ile farklarını ve dosya dizinlerini öğrenin.
Ajan yeteneğinin gerçekte ne olduğu
Ajan yeteneği, içerisinde SKILL.md adlı bir dosya bulunan 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ı barındırır. Ajan, açıklamayı başlangıçta yükler; talimatları ise yalnızca isteğiniz bu açıklamayla eşleştiğinde veya yeteneği ismiyle çağırdığınızda okur. Yeteneklerle ilgili diğer hemen hemen 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. Sadece bir SKILL.md dosyası içeren bir klasör, tam bir yetenek olarak kabul edilir.
restore-drill/
SKILL.md
references/retention-policy.md
scripts/verify_snapshot.shAçı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ı
Biçimin 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 aracı, yüklü her yeteneğin name ve description kısımlarını yükler, başka hiçbir şeyi yüklemez. Agent Skills şartnamesi, Ekim 2026 itibarıyla yayınlanan kılavuza göre bunu yetenek başına yaklaşık 100 token olarak belirlemiştir. Bir düzine yetenek yüklerseniz, uzun bir paragrafın bağlamı kadar yer harcamış olursunuz.
Bir istek, bir açıklama ile eşleştiğinde aracı, ilgili SKILL.md dosyasının gövdesini okur. Şartname, gövdenin 5.000 token altında ve dosyanın 500 satırdan kısa tutulmasını önerir. references/ ve scripts/ içindeki dosyalar bu noktada hala hiçbir maliyet oluşturmaz. Bir referans dosyası, yalnızca talimatlar aracıyı ona yönlendirirse yüklenir. Paketlenmiş bir betik ise farklıdır: aracı onu shell üzerinden çalıştırır, bu nedenle betiğin kaynağı hiçbir zaman bağlam penceresine girmez, yalnızca çıktısı girer.
Şimdi bunu, insanların ilk başvurduğu yöntem olan tek bir devasa istem 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 ücretlendirilir; 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, aktivasyon öncesinde yaklaşık 1.200 token maliyet oluşturur ancak yüklenen talimatlar aynı konuşmadaki sonraki görevler için bağlamda kalabilir. Yeteneklerin tüm olayı budur ve küçük bir kütüphanenin daha uzun bir istemden daha iyi olmasının nedeni de budur.
Bir uyarı, insanların gözünden kaçabilir. Claude Code'da bir yetenek yüklendiğinde, gövdesi sonraki turlarda konuşma içinde kalır; bu nedenle uzun bir SKILL.md, tek seferlik değil, tekrarlayan bir maliyettir. Sıkıştırma (compaction), yüklenen yetenek içeriğini kırpabilir veya kaldırabilir. Detayları references/ içine taşımak bir düzenleme çabası değildir. Bu, mekanizmanın tasarlandığı gibi çalışmasıdır.
Bir agent yeteneği (skill), bir araç çağrısı (tool call) değildir
Bir araç, diğer adıyla fonksiyon çağrısı, modelin tetikleyebileceği bir işlemdir. 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. Bu alışverişin her iki tarafı da modelin etrafındaki döngüyü çalıştıran programa, yani harness'a aittir; bu program aynı zamanda başlangıçta yetenek açıklamalarınızı okuyan ve hangisinin ne zaman açılacağına karar veren yapıdır.
Bir yetenek (skill) kendi başına hiçbir şey yürütmez. Agent onu okur, ardından zaten sahip olduğu araçları kullanarak harekete geçer. Claude Code, bir yetenek çağrıldığında argümanları kabul eder ve bunları $ARGUMENTS gibi yer tutucular aracılığıyla talimatlarına yerleştirir. Bir yeteneğin yapabildiği şey, modele hangi araçları, hangi sırayla kullanacağını ve sonrasında neleri kontrol etmesi gerektiğini söylemektir. Bir işi ikinci bir agent'a devretmek bunun en net örneğidir: bir Claude Code oturumu zaten bir diğerine mesaj gönderebilir ve yetenek, bunun ne zaman yapılması gerektiğini ve ne gönderileceğini yazdığınız yerdir.
Kısacası: bir araç, agent'a yeni bir kabiliyet kazandırır; bir yetenek ise çoğunlukla zaten sahip olduğu kabiliyetler hakkında ona muhakeme yetisi sağlar. Bir yetenek yeni bir kabiliyet eklediğinde, bunu agent'ın zaten sahip olduğu kabuk (shell) ile çalıştırdığı paketlenmiş bir betik aracılığıyla yapar. 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 yapısıyla uygulanması gerekiyorsa, bir yeteneğe ihtiyacınız vardır. Bir yetenek sadece muhakemeden ibaret olabilir ve yine de en çok başvurduğunuz şey olabilir; kodlama yapan bir agent'ı çalışan en küçük değişikliği yapmaya zorlayan Ponytail bunun bir örneğidir: yeni bir kabiliyet eklemez, sadece agent'ın mevcut olanları nasıl kullandığını değiştirir. Bu muhakeme diğer yöne de çalışabilir; bir agent'ın işi erken bittiğini beyan etmesini engellemek için bir Derinlik Ağacı (Depth Tree) üzerinde ilerleyen unlazy yeteneği, kısıtlama yerine titizliği hedefleyen aynı yöntemdir.
Bir agent yeteneği MCP sunucusu değildir
MCP (model context protocol), bir agent'ı dış bir sisteme bağlamak için kullanılan bir protokoldür. MCP sunucusu; çalışan, bu protokolü konuşan ve agent'a araçlar sunan bir süreçtir. Genellikle yapılandırma, kimlik bilgileri ve yerel bir komut ya da ağ uç noktası gerektirir. Yetenek (skill) ise içinde bir markdown dosyası bulunan bir klasördür. Herhangi bir süreç, port veya protokol içermez.
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. Bunları önceden yükleyen bir istemcide, bu veriler kullanılsa da kullanılmasa da tüm oturum boyunca istek içerisinde yer alır. Claude Code artık varsayılan olarak bu şekilde çalışmamaktadır: Ekim 2026 itibarıyla araç arama özelliği kutudan çıktığı haliyle etkin durumdadır; bu sayede oturum başlangıcında yalnızca araç isimleri ve sunucu talimatları yüklenir, tam tanımlar ise Claude bunları aradığında gelir. Kullanılmayan bir yetenek ise yalnızca bir satırlık 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ırayla ç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.
Bir 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. Başlangıçta yüklenen sistem istemi ve proje talimatları her zaman etkindir; iç içe geçmiş AGENTS.md ve CLAUDE.md dosyaları ise ajan kendi dizinlerinde çalıştığında yüklenir. Bir yetenek ise isteğe bağlıdır. Claude Code'un çıktı stilleri, her zaman etkin olanların en ucunda yer alır, çünkü birini seçmek sistem isteminin kendisini düzenler, bu nedenle hiçbir yeteneğin dokunmadığı yanıtlar dahil olmak üzere oturumdaki her yanıtı şekillendirir.
Bunun testi tek bir sorudur: Bu paragrafı görmezden gelmek, bununla hiçbir ilgisi olmayan bir görevde yanlış olur muydu? Kurumsal stil, derleme komutu ve dal adlandırma kuralı her görev için geçerlidir, bu nedenle her seferinde yüklenmelerinin amaçlandığı her zaman etkin olan dosyada bulunurlar. Ayda iki kez çalıştırdığınız sürüm kontrol listesi her görev için geçerli değildir, bu nedenle bir yeteneğin parçası olmalıdır. Her zaman etkin olan dosyanızın 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 kendi kuralları vardır. Kullandığımız iki dosya için AGENTS.md dosyasında nelerin, insan dosyasında nelerin yer alması gerektiğine ve kod tabanının yapısını açıklayan bir design.md dosyasına bakabilirsiniz.
Minimal bir yetenek nasıl görünür
Claude Code içerisinde kişisel yetenekler ~/.claude/skills/<name>/SKILL.md dizininde bulunur ve o makinedeki tüm projeleriniz için geçerlidir; ancak Cowork veya bulut oturumlarını kapsamaz. Proje yetenekleri .claude/skills/<name>/SKILL.md dizininde yer alır ve git ile commit edilir; böylece ekibiniz de bunlara erişebilir. Claude projesindeki bulut iş parçacıkları bu yetenekleri yüklemez. GitHub Copilot ve VS Code, proje yeteneklerini .github/skills/ ve .agents/skills/ dosyalarının yanı sıra .claude/skills/ dizininden de 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` reports that it cannot open the config file, stop and report the full error instead of guessing the cause.Bu, eksiksiz bir yetenektir. Dizin adı, yazdığınız komut haline gelir; dolayısıyla bu örnekte komut /restore-drill şeklindedir. Claude Code içerisinde /skills menüsü, nelerin yüklü olduğunu listeler; bu, dosyanın algılandığını doğrulamanın en hızlı yoludur. Eğer dosya bu menüde görünmüyorsa, önce isimleri kontrol edin: dosyanın adı mutlaka SKILL.md olmalıdır ve Agent Skills spesifikasyonu, ismin dizin adıyla eşleşecek şekilde küçük harfler, rakamlar ve tek tire işaretlerinden oluşmasını gerektirir. Aynı işlemin temsilcinizin yeniden çalıştırabileceği bir prosedür olarak yazılmış hali, 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ı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 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şımamı, sütun eklememi veya şemayı değiştirmemi 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 yetenektir. "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 sonraki konuşma turlarında da sohbette kalmaya devam eder. Açıklamayı, amaçladığınız durumla sınırlandırın. Claude Code içerisinde, otomatik yüklemeyi durduran ve ismini yazdığınızda yeteneği erişilebilir kılan disable-model-invocation: true ayarını frontmatter içinde yapılandırabilirsiniz.
Üçüncü hata ise bir aracı kopyalayan yetenektir. Ajana, MCP sunucusunun zaten sunduğu bir API'yi curl etmesini söyleyen veya sistemde bir 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.
Bu üç sorundan hangisine sahip olduğunuzu tahmin etmeye çalışmayın. Aynı komutu yeni bir oturumda iki kez çalıştırın; birinde yetenek açık, diğerinde kapalı olsun, ardından cevapları 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 eksiklikleri gizler. Anthropic'in skill-creator eklentisi, Claude Code içinde bu karşılaştırmayı otomatikleştirir; buna yeteneği tetiklemesi gereken ve tetiklememesi gereken komutların oluşturulması ve her birinin ne sıklıkla tetiklendiğinin ölçülmesi de dahildir. Yetenek yükleniyor ancak ajan yine de söylenenleri yapmıyorsa, sorun açıklama değildir; bu durumda bir ajanın okuduğu talimatları neden görmezden geldiği konusuna bakmalısınız.
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 adresinde barındırılan açık bir standart olarak kullanıma sundu. 22 Ekim 2026 tarihinde Anthropic, Agent Skills'i Linux Foundation bünyesindeki Agentic AI Foundation'a bağışladığını duyurdu. Ekim 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 Skill Recorder adında bir masaüstü aracı sunmaktadır. Bu araç, bir görevi bir kez yapmanızı izler, bunu bir niyet ve sıralı adımlar olarak yeniden yapılandırır ve sonucu bir yetenek (skill) olarak dışa aktarı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. Claude Code'un varsayılan olarak yaptığı gibi istemci bunları ertelemediği sürece, tüm araç tanımları oturum boyunca bağlamı işgal eder. Bir agent yeteneği ise bir SKILL.md dosyası içeren bir klasördür; herhangi bir süreç veya protokol gerektirmez 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 bir şekilde kullanma prosedürünü ajana öğretmek için 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 yapısı 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 metin (frontmatter) alanlarını anladığı noktasında ortaya çıkar. Claude Code ~/.claude/skills/ ve .claude/skills/ dosyalarını okurken, GitHub Copilot ve VS Code depodaki .github/skills/, .claude/skills/ veya .agents/skills/ dosyalarını okur. SKILL.md dosyasının kendisi ise bu istemciler arasında hiçbir değişiklik olmadan taşınabilir.
Performansı düşürmeden önce kaç tane yetenek yükleyebilirim?
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 tutarında bir isim ve açıklama katkısında bulunur; dolayısıyla otuz yetenek, herhangi biri kullanılmadan önce yaklaşık 3.000 token maliyet oluşturur. İlk bozulan şey hız değil, eşleşme kalitesidir: 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ı hepsini kapsadığı için her zaman açık olan dosyaya aittir; 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 ise bir yetenek olmalıdır; böylece aktivasyon öncesinde yalnızca tek satırlık açıklama maliyeti oluşturur. Claude Code'da bir kez yüklendiğinde, talimatları alakasız görevler dahil olmak üzere sonraki aşamalarda da konuşma içerisinde kalmaya devam eder. Numaralandırılmış adımlara dönüşmüş bir AGENTS.md bölümü, genellikle taşınmayı bekleyen bir yetenektir.