Agent Skills
İhtiyaç anında yüklenen yetenek paketleri
Talimatların, betiklerin ve yardımcı dosyaların bir SKILL.md etrafında paketlendiği, ajanın yalnızca ihtiyaç duyduğunda bağlamına yüklediği yeniden kullanılabilir yetenek klasörleri.
Bir ajana "PDF formu nasıl doldurulur", "şirketimizin release notu formatı", "bu repoda migration nasıl yazılır" gibi onlarca prosedür öğretmek istiyorsun. Hepsini system prompt'a yığarsan her istekte binlerce token harcarsın ve model asıl işe odaklanamaz. Agent Skills bu sorunu kademeli açılım (progressive disclosure) ile çözer.
Skill, en az bir SKILL.md dosyası içeren bir klasördür. Dosyanın
başında YAML frontmatter vardır: name ve description zorunludur.
Altında Markdown talimatlar yer alır; klasörde isteğe bağlı olarak
scripts/, references/, assets/ bulunabilir. Format
agentskills.io'da açık bir standart olarak tanımlanmıştır; Claude
Code ve OpenAI Codex gibi araçlar aynı formatı okur.
Yükleme üç kademelidir:
1. Açılışta yalnızca her skill'in adı ve açıklaması bağlama girer.
2. Görev açıklamayla eşleşince model SKILL.md'nin tamamını okur.
3. Talimat başka bir dosyaya ya da betiğe işaret ediyorsa o da
ancak gerektiğinde okunur veya çalıştırılır.
Farkları netleştirelim: system prompt her istekte hep oradadır; skill ise çağrılana kadar sadece bir satırdır. MCP ajana yeni araçlar ve veri erişimi kazandırır; skill ise mevcut araçlarla bir işin nasıl yapılacağını öğretir. Fine-tuning modelin ağırlıklarını değiştirir; skill tek bir klasörü silerek geri alınabilen, düz metin bir bilgidir.
İyi bir mutfaktaki tarif dosyası gibi. Aşçı bütün tarifleri ezbere bilmez; raftaki klasörlerin sırtındaki etiketleri bilir ("Ekşi maya", "Fermente sos"). Sipariş gelince doğru klasörü çeker, tarifi okur, tarif "hamur oranları için ek tabloya bak" diyorsa o sayfayı açar. Etiket = description, tarif = SKILL.md, ek tablo = referans dosyası.
Bir ekip haftalık sürüm notlarını hep aynı formatta istiyor: başlık
yapısı, kırıcı değişiklikler bölümü, issue linkleri. Her seferinde
bunu ajana anlatmak yerine .claude/skills/release-notes/ klasörüne bir
SKILL.md yazıyorlar ve açıklamaya "kullanıcı sürüm notu, changelog
ya da release isterse kullan" diyorlar.
Claude Code oturumu açıldığında bu skill bağlamda sadece bir satır yer
kaplıyor. Biri "v2.4 için release notu çıkar" dediğinde model skill'i
seçiyor, talimatları okuyor, klasördeki scripts/collect.sh ile commit
listesini topluyor ve şablona uygun metni üretiyor. Aynı klasör
/release-notes komutuyla elle de çağrılabiliyor.
---
name: release-notes
description: Son etiketten bu yana yapılan commit'lerden sürüm notu
üretir. Kullanıcı release notu, changelog ya da sürüm özeti
istediğinde kullan.
---
# Sürüm notu üretimi
1. `scripts/collect.sh` çalıştırarak son etiketten bu yana gelen
commit'leri topla.
2. Commit'leri şu başlıklara ayır: Yeni, Düzeltme, Kırıcı değişiklik.
3. Her maddeye ilgili issue linkini ekle.
4. Biçim için `references/template.md` dosyasını izle.
Kırıcı değişiklik yoksa o başlığı tamamen çıkar.release-notes/
├── SKILL.md # zorunlu: frontmatter + talimatlar
├── scripts/
│ └── collect.sh # gerektiğinde çalıştırılır
└── references/
└── template.md # gerektiğinde okunur- Tekrar eden, adımları belli bir prosedürü ajana kalıcı olarak öğretmek istiyorsan
- System prompt'u şişirmeden çok sayıda uzmanlık alanı eklemek gerektiğinde
- Bilgiyi betik ve şablonlarla birlikte paketleyip ekipte paylaşmak için (repoya commit)
- Aynı yeteneği farklı ajan araçlarında kullanmak istiyorsan (açık standart)
- Her istekte geçerli olması gereken kurallar — onlar system prompt ya da CLAUDE.md/AGENTS.md'ye ait
- Ajanın yeni bir sisteme erişmesi gerekiyorsa — bu MCP sunucusu ya da araç işi
- Kuralın kesinlikle uygulanması gerekiyorsa — skill bir öneridir, garanti için hook kullan
Belirsiz description yazmak
Model skill'i yalnızca açıklamaya bakarak seçer. 'Yardımcı araçlar' gibi bir açıklama hiç tetiklenmez. Ne yaptığını ve hangi durumlarda kullanılacağını ilk cümlede açıkça yaz.
Her şeyi SKILL.md'ye gömmek
Skill seçildiğinde dosyanın tamamı bağlama girer. Uzun tabloları, API referanslarını ayrı dosyalara taşı ki sadece gerektiğinde okunsun; kademeli açılımın bütün faydası bu.
Güvenilmeyen skill kurmak
Skill içindeki betikler ajanın yetkileriyle çalışır ve talimatlar modeli yönlendirir. Başkasının skill'ini kurmadan önce kodunu oku; bu, bilinmeyen bir npm paketi çalıştırmakla aynı risk.