Python Agent Skills: Üç Yöntem, Tek Provider Senaryosu

Geçen hafta Logosoft’ta bir müşterinin İK ekibiyle oturduk. Adam resmen patladı: “Biz her (söylemesi ayıp) yeni servis için ayrı bir bot mu yazacağız ya?” Onboarding için bir asistan, izin bakiyesi için başka bir şey, yan haklar için üçüncü bir bot (bu konuda ikircikliyim). Açık konuşayım, klasik kurumsal kâbus. Halbuki Microsoft’un Agent Framework tarafında işler çoktan değişmeye başlamıştı, biz de o sırada biraz geriden geliyorduk.

Skill’i şöyle düşünün: tool, modele “ne yapabilirsin” diye söyler. Skill işe “nasıl yapacağını” söyler. İkisi farklı katman, ikisi birden lazım. Biri kapıyı açıyor, öteki içeri nasıl gireceğini tarif ediyor; küçük fark gibi duruyor ama işin aslı tam da orada.

Senaryo: İK self-servis agent’ı, üç ayrı kaynaktan beslensin

Adım adım gidelim. Şöyle bir tablo düşünün; geçen ay benzerini bir telekom müşterisinde gördük, ortam biraz karışıktı ama işin mantığı netti:

• Onboarding rehberi — sizin repo’da duran, dosya bazlı bir skill. Markdown var, script var.
• Yan haklar (benefits) skill’i — şirketin iç paket index’inden gelen, hazır bir Python paketi. Sınıf bazlı çalışıyor.
• İzin bakiyesi skill’i — ortada resmî paket yok ama uygulamanızda zaten bir iç API client’ı var. Inline yazıyorsunuz, bridge gibi.

Güzel tarafı şu: bunların hiçbiri ötekinin ne yaptığını umursamıyor. Yeni bir skill ekliyorsunuz, eskisi yerinde duruyor; eskiyi siliyorsunuz, yenisi de kendi yolunda gidiyor. Bana kalırsa kurumsal tarafta aranan şey bu, yani gevşek bağlı parçalar ve tek merkezden orkestrasyon. Evet, tam da bu.

Bir dakika — bununla bitmedi.

Adım 1: Dosya bazlı skill — klasik başlangıç

Repo içinde şöyle sade bir klasör yapısı yeterli oluyor:

skills/
└── onboarding-guide/
├── SKILL.md
├── scripts/
│ └── check-provisioning.py
└── references/
└── onboarding-checklist.md

Kendi deneyimimden konuşuyorum, SKILL.md’nın başında frontmatter var, sonra açıklama geliyor, ardından talimatlar sıralanıyor. Model bu dosyayı okuyor; kullanıcı “yeni başladım, ne yapmalıyım?” dediğinde bu skill devreye giriyor. Script çalıştırması gerekiyorsa da siz script_runner‘ı provider’a verdiğiniz için izin alarak çalıştırıyor (evet, doğru duydunuz). Basit görünüyor, ama iş görüyor.

Bu yöntem ne zaman iyi? Bak şimdi, iki durumda baya işe yarıyor: (1) içerik sık değişiyorsa ve teknik olmayan ekipler de düzenleyecekse (Markdown burada rahat), (2) her şeyi repo üzerinden version control ile takıp etmek istiyorsanız. Hatta İK ekibi bile pull request açabiliyor; biraz şaşırtıcı geliyor ama oluyor.

Adım 2: Sınıf bazlı skill — paketleyip dağıtmanın daha temiz yolu

Peki neden ikinci bir modele geçelim? Şundan: diyelim platform ekibi yan haklar için bir skill yazdı. Bunu pip paketi olarak dağıtmak istiyor. Markdown dosyalarıyla uğraşmak istemiyorlar. Çalışma anında dinamik hesaplama gerekiyor (kullanıcının lokasyonu değişiyor, plan listesi değişiyor, detaylar uzayıp gidiyor). İşin aslı biraz da bu.

Sınıf bazlı skill’in görüntüsü kabaca şöyle oluyor:

from agent_framework import Skill, skill_method
class BenefitsEnrollmentSkill(Skill):
name = "benefits-enrollment"
description = "Çalışanları yıllık yan haklar kaydında yönlendirir."
@skill_method
async def get_available_plans(self, employee_id: str) -> dict:
# iç servisle konuş, plan listesini döndür
return await self._client.fetch_plans(employee_id)
def get_instructions(self) -> str:
return """
1. Çalışanın mevcut planını sor.
2. get_available_plans çağır.
3. Karşılaştırma tablosu sun.
"""

Eh, Neden değerli? Çünkü artık skill bir Python sınıfı. Yani test yazabiliyorsunuz (evet, unit test tarafı rahatlıyor), constructor’dan dependency injection yapabiliyorsunuz ve başka bir paketin parçası hâline getirebiliyorsunuz. pip install company-hr-skills deyip geçiyorsunuz; sonra biri gelip “bu niye böyle” diye sormuyor değil tabii ama kurumsalda çoğu zaman düzgün paketleme fark yaratıyor.

Tam da burada küçük bir not düşeyim: az önce “daha temiz yol” dedim ama aslında çoğu zaman şart değil; eğer ekip küçükse ve mantık çok basitse dosya bazlı yapı da gayet yeterli olabilir. Neyse uzatmayalım.

Adım 3: Inline kod skill — hızlı köprü

Diyelim resmî izin bakiyesi paketi henüz yok ama kullanıcılar sürekli soruyor. Siz de “ben bekleyemem” diyorsunuz; uygulamada zaten HRClient var ve önü kullanabiliyorsunuz. O zaman 10 dakikada inline bir skill yazıp işi toparlıyorsunuz:

from agent_framework import skill
@skill(
name="time-off-balance",
description="Çalışanın kalan izin bakiyesini gösterir."
)
async def time_off_balance(employee_id: str) -> str:
balance = await hr_client.get_balance(employee_id)
return f"Kalan izin: {balance.days} gün"

Bitti sayılır. Resmî paket birkaç sprint sonra gelince bu fonksiyonu kaldırırsınız, yerine paketteki sınıfı koyarsınız; geri kalan akış aynı kalır. Çok parlak görünmüyor belki ama açıl durumda baya kurtarıcı oluyor.

Ve işler burada ilginçleşiyor.

Şunu söyleyeyim, E sonra? Bence buradaki esas fikir şu: üç farklı kaynak tipini aynı agent çatısı altında toplayabiliyorsunuz ve her biri kendi hızında yaşayabiliyor (şaşırtıcı ama gerçek). Bir yanda repo’da yaşayan Markdown tabanlı içerik var, diğer yanda paketlenmiş Python sınıfları var, en sonda da geçici köprü gibi duran inline fonksiyonlar var; hepsi aynı orkestrasyona bağlanıyor ama birbirinin ayağına basmıyor.

Multi-source composition: Üçünü tek provider’da birleştirmek

Bütün mesele tam burada dönüyor. Bu üç kaynağı tek bir SkillsProvider altında nasıl topluyorsunuz, peki? Kısa cevap var; uzun cevap da var, ve açık konuşayım, ikinci kısım genelde daha çok iş görüyor.

from agent_framework import (
SkillsProvider,
FileSkillSource,
ClassSkillSource,
InlineSkillSource,
)
provider = SkillsProvider(
sources=[
FileSkillSource(path="./skills"),
ClassSkillSource(skills=[BenefitsEnrollmentSkill()]),
InlineSkillSource(skills=[time_off_balance]),
],
script_runner=my_script_runner,
)
agent = Agent(
chat_client=FoundryChatClient(...),
skills_provider=provider,
)

Provider arka planda discovery, filtering ve deduplication yapıyor. Yani aynı isimli iki skill varsa ortalık karışmasın diye sızı uyarıyor, filtre de koyabiliyorsunuz (mesela sadece “hr-” ile başlayanları yükle), keşif sırasında bozuk skill’leri de es geçebiliyor. Şey, kağıt üstünde basit duruyor ama pratikte baya rahatlatıyor.

Vallahi, Ben ilk denediğimde küçük bir hata aldım aslında. FileSkillSource‘a verdiğim yol relative idi. Docker container içinde çalışınca SKILL.md not found diye patladı. Çözüm basit: mutlak yol verin ya da Path(__file__).parent ile çözün. Belgelerde köşede yazıyor ama insan ilk seferde okumuyor tabii; sonra bir bakıyorsunuz, hata mesajı size ders vermiş oluyor.

Hangi yöntem ne zaman? — Pratik karar tablosu

Evet. NL2SQL Gerçekten İşe Yarıyor mu? SQL MCP Server Notları yazımızda bu konuya da değinmiştik.

İşte tam da bu noktada devreye giriyor.

Neyse uzatmayalım, tabloyu görünce çoğu kişi “tamam işte bu” diyor ama asıl mesele şu: içerik kim tarafından yönetilecek, ne kadar sık değişecek. Sonradan bunu Git üzerinde nasıl taşıyacaksınız? Bunlar net değilse yöntem seçimi de biraz sallantıda kalıyor.

Daha açık söyleyeyim, peki neden? Çünkü teknik olarak doğru olan seçenekle operasyonel olarak rahat olan seçenek her zaman aynı olmuyor. Bazen file-based gayet temiz ilerliyor, bazen class-based daha düzgün oturuyor, bazen de hızlıca inline yazıp geçmek gerekiyor; yani tek reçete yok.

Bi saniye — Tam da öyle.

Açık konuşayım, ben karar verirken önce “bunu kim okuyacak?” diye bakıyorum. Eğer konuya teknik olmayan biri dokunacaksa Markdown tarafı ciddi avantaj sağlıyor. Ama iş paketlemeye, test etmeye. Sonra başka projelerde tekrar kullanmaya gelince class-based çözüm bir anda daha mantıklı hâle geliyor. Daha fazla bilgi için Motorun Ötesi: Oyun Yapımında 10 Açık Kaynak Cevher yazımıza bakabilirsiniz.

Bazı durumlarda da olay sadece hız oluyor. Şey gibi düşünün: kısa süreli bir köprü kuruyorsunuz, POC çıkarıyorsunuz ve ortada uzun vadeli bakım yükü yok. İşte orada inline yaklaşım idare ediyor. Sonra büyürse zaten yeniden ele almak gerekiyor.

Bunu yaşayan biri olarak söyleyeyim, Eğer Git akışı önemliyse tabloyu fazla zorlamayın derim. File-based içerikte diff okumak kolay oluyor; PR incelemesi sırasında “bu cümle niye değişmiş?” sorusunun cevabı daha hızlı bulunuyor. Class tarafında da ölür elbet, ama içerik ağırlıklı işler için file-based biraz daha rahat hissettiriyor.

Kısacası seçim şu üç şeye dayaniyor: kullanım kolaylığı, bakım yükü ve değişim sıklığı. Bunlardan biri bile uçuyorsa yanlış tarafa kaymış olabilirsiniz. Siz ne dersiniz?

Bence kritik nokta şu: dinamik davranış istiyorsanız statik dosyaya fazla güvenmeyin. Az önce file-based’i övdüm ama burada dürüst olayım, runtime’da sık değişen bir şey için markdown bazen yetersiz kalıyor. O durumda class ya da inline daha doğru yere düşüyor. Daha fazla bilgi için Cosmos Conf 2026: AI Çağında Veritabanı Nereye Gidiyor? yazımıza bakabilirsiniz.

Bence, Kabaca tablo bu kadar. Ama pratikte karar verirken küçük bir detay bile yönü değiştirebiliyor; mesela ekip alışkanlığı ya da deploy şekli bile bazen yöntemden daha belirleyici oluyor.

Türkiye’deki kurumlar açısından değerlendirme

Şunu fark ettim: Şimdi bir saniye, kurumsal taraftaki tabloya yakından bakalım. Türkiye’de, özellikle finans ve telekom tarafında, aynı filmi defalarca izliyoruz; AI projeleri pilotta fena gitmiyor, sonra “production’a alalım” denince bir anda herkes birbirine bakıyor (bizzat test ettim). Çünkü her ekip kendi botunu yazmış, kendi prompt’unu kurmuş, kendi tool set’ını toplamış; tek bir asistan fikri var ama içeride on ayrı ada gibi duruyor (ki bu çoğu kişinin gözünden kaçıyor)

Multi-source composition tam bu noktada devreye giriyor. Ben müşterilere genelde şöyle anlatıyorum: her domain ekibi kendi skill paketini kendi pipeline’ında üretsin, ortak agent runtime da bunları birleştirsin. İK kendi paketini çıkarır, finans kendi işini görür, satış başka bir şey yazar; hepsi tek bir self-service agent altında toplanır. Kimse kimsenin koduna dokunmaz. Güzel tarafı da bu zaten.

Enterprise vs startup: Hangisi sızı anlatıyor?

Şöyle bir ayrım yapayım, çünkü ikisi aynı kafada ilerlemiyor, hiç etmiyor.

Startup veya küçük ekipseniz: Doğrudan inline ve file-based ile başlayın. Hatta skill’leri bir skills/ klasöründe toplamak baya iş görüyor. Class-based yapıya geçmek için acele etmeyin. Önce iş değerini ölçün, sonra refactor edersiniz; yani lafı gevelemeden, ürün konuşsun. Görmüşüm bunu, 5 kişilik ekip “doğru yapalım” diye 3 hafta mimarı tartışıyor, sonra ortada çıkan şey yok. Evet. Bu konuyla ilgili .NET 11 Process API: Deadlock’suz Süreç Yönetimi Geldi yazımıza da göz atmanızı tavsiye ederim.

Kurumsal yapıdaysanız (100+ geliştirici): Hemen class-based + private package feed tarafına geçin. Çünkü dosya bazlı skill’ler 50’yi geçince idare etmez hâle geliyor, açık konuşayım. Kim hangi skill’i yazdı, hangi versiyonda duruyor, hangi takım sahipleniyor — bunlar net olmazsa işler çabuk karışıyor (özellikle birden fazla ekip aynı repo’ya abanıyorsa). Ayrıca CI/CD’ye lint ve test ekleyin skill paketleri için; küçük gibi duruyor ama sonradan baş ağrısı olmuyor değil. Bu konuya genel bir bakış için Visual Studio Agent Skills: Copilot’a Takimi Öğretmek yazıma da bir göz atın, oradaki team-level skill yönetimi mantığı birebir geçerli. Kısacası, peki neden? Çünkü ölçek büyüyünce düzen, biraz da mecburiyet oluyor.

Maliyet tarafı — kimse konuşmuyor ama önemli

Açık konuşayım: skill’ler maliyeti düşürür, ama işin üçünü kaçırırsanız tam tersi de ölür. Niye? Çünkü her skill, prompt’a context olarak ekleniyor; yani 30 tane skill yüklediğiniz bir agent, her istekte bunların açıklamasını modele taşıyor. Token sayısı sessizce şişiyor.

Bir hesap yapayım, kabaca gidelim. GPT-4o üzerinden konuşuyorum, çünkü Azure tarafında en sık gördüğüm model bu; her skill açıklaması ortalama 200 token olsa, 30 skill = 6000 token sadece liste kısmı eder. Günde 10.000 istek atan bir agent için bu da ayda 60 milyon token yapar, yaklaşık 150 dolar civarı bir yük çıkarır (TL bazında bakınca da ayda 5.000 TL’ye yakın gizli maliyet), fena değil gibi duruyor ama sürekli çalışınca can sıkıyor.

Peki çözüm? SkillsProvider‘da filtering kullanın. Konuya göre dinamik skill yükleyin; “tüm skill’leri her zaman yükle” demek yerine, ilk turda hangi domain’in alakalı olduğunu tespit edip sadece o domain’in skill’lerini açın. Bu pattern’i Model Router Eval’leri: Sahada Doğru Modeli Bulmak yazımdaki yaklaşımla birleştirirseniz hem maliyet düşer hem doğruluk artar, yani ikili kombo gibi çalışır.

İlk adım olarak ne yapın?

Denemek istiyorsanız, ben olsam sıralamayı şöyle kurarım: önce küçükten başlarım, sonra iş büyür. Hani bir anda (söylemesi ayıp) her şeyi karıştırmayın derler ya, burada da aynı durum var; pip install agent-framework ile giriş yapın (Python 3.10+), sonra ufak bir file-based skill yazın, SKILL.md olsun, yanina bir script koyun, bir de referans ekleyin, çalıştırın. Ne dönüyor bakın.

Eh, Sonra biraz elinizi kirletin. Aynı agent’a @skill dekoratörüyle inline bir fonksiyon ekleyin; mix dediğimiz şey tam olarak burada belli oluyor, çünkü bir yanda dosyadan gelen yapı var, öbür yanda kodun içine gömülü mantık duruyor (ilk bakışta dağınık gibi gelebilir ama çoğu zaman idare eder). Evet.

İşler oturunca bence en kararlı skill’ınızı class-based formata taşıyın; test de yazın, yoksa sonra “bu niye bozuldu” diye uğraşırsınız. Az önce dosya tabanlı dedim ama aslında bazı senaryolarda class-based yaklaşım daha temiz kalıyor; özellikle davranış büyüyorsa bu geçiş baya iş görüyor. Peki neden?

Araya gireyim: En son da multi-source provider kurulumuyla üçünü birleştirin; işte o noktada sistem daha gerçekçi hâle geliyor, çünkü tek kaynağa yaslanmak yerine farklı parçaları aynı akışta kullanmış oluyorsunuz (ama burada biraz dikkat lazım, her şey düzgün bağlandı sanmayın). Bu aşamada production-ready hissi gelir, fakat açık konuşayım, asıl mesele hâlâ gözden kaçan kenar durumları yakalamak. Maalesef.

Bir uyarı da bırakayım: güvenlik tarafını sakın hafife almayın (ki bu çoğu kişinin gözünden kaçıyor). Script çalıştırma izinleri, agent’ın hangi dosyalara erişebileceği, hangi network çağrılarını yapabileceği — bunlar ayrı ayrı düşünülmeli. “çalıştı mı tamamdır” kafası burada pek yürümüyor. Bu konuda FIDES ile Prompt Injection: Agent Framework’te Yeni Kalkan yazıma bakmanızı tavsiye ederim, prompt injection riskleri ciddi. Tam da öyle.

Bunu biraz açayım.

Eksik bulduğum taraflar

Sadece övgü yazmayayım. Şu an Python tarafında benim hâlâ canımı sıkan birkaç şey var, hani küçük değil bunlar; bir skill başka bir skill’i nasıl çağıracak, state nasıl paylaşılacak, bu işin akışı nereden geçecek gibi sorular dokümantasyonda biraz havada kalıyor,.NET tarafı işe açık konuşayım, bu konuda daha derli toplu duruyor.

İkincisi, observability. Hangi skill ne sıklıkta çağrılıyor? Hangileri sessizce kenarda bekliyor? Token tüketimi nasıl dağılıyor, kim ne kadar yiyor? Bunları görmek için şu an kendi telemetry’nizi yazmanız gerekiyor, yani hazır gelen bir ekran yok; işin aslı bu kısımda biraz boşluk hissettim, önümüzdeki sürümlerde gelir diye umuyorum. Bugün için durum pek iç açıcı değil.

Sıkça Sorulan Sorular

Agent Skills ile tool calling arasında ne fark var?

Tool calling, modele “hani şu fonksiyonu çağırabilirsin” diyor. Skill işe “şu durumda şu adımları izle, bu fonksiyonları nasıl sırayla kullanacaksın” diyor. Yani aslında skill, tool’un üzerinde bir orkestrasyon katmanı. Siz hiç denediniz mi? Bir skill içinde birden çok tool olabiliyor.

File-based ve class-based skill aynı agent’ta çakışırsa ne oluyor?

SkillsProvider deduplication yapıyor, ama önceliği siz belirliyorsunuz. İsim çakışması varsa varsayılan olarak uyarı veriyor ve sonradan eklenen kaynak öncelikli oluyor. Bence production’da kesinlikle açık bir işim politikası belirleyin — mesela “hr-” gibi bir ön ek kullanın. Sonradan çok işinize yarıyor.

Skill’leri private bir Python feed’den dağıtabilir mıyım?

Evet! Sınıf bazlı skill’ler standart Python paketi olarak yazıldığı için Azure Artifacts, JFrog veya GitHub Packages gibi herhangi bir private index’ten dağıtılabiliyor. Açıkçası kurumsal senaryolarda en sağlıklı yöntem de bu zaten.

Inline skill’i production’da kullanmak güvenli mi?

Teknik olarak evet, ama best practice değil. Inline skill’ler hızlı bridge ve POC için gayet iyi. Ama production’a alacaksanız class-based formata taşıyıp test coverage eklemenizi öneririm — aksi hâlde teknik borç birikmeye başlıyor.

Skill sayısı arttıkça performans sorun ölür mu?

Olabilir, evet. Her skill’in açıklaması prompt’a context olarak gidiyor, yani token tüketimi artıyor. Tecrübeme göre 20 skill’i geçtiyseniz dinamik filtering şart oluyor. Konu bazlı segmentasyon ve lazy loading ile bunu yönetmek mümkün.

Kaynaklar ve İleri Okuma

Microsoft DevBlogs: Agent Skills for Python — Orijinal Duyuru

Kısacası, kendi deneyimimden konuşuyorum, Microsoft Agent Framework Resmî Dokümantasyonu

Size bir şey söyleyeyim, Agent Framework GitHub Repository (örnekler ve kod)

Aşkın KILIÇYazar

20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.

AZ-305AZ-104AZ-500AZ-400DP-203AI-102

İlgili Yazılar

Los Angeles’ta Sürücüsüz Mikrobuslar: Volkswagen’in Sessiz Hamlesi8 Nis 2026

Bulutlar Arasında Agent Kurmak: ADK, ECS Express ve Gemini10 Nis 2026

Trent AI Sessizce Çıktı: 13 Milyon Dolarlık Güvenlik Hamlesi7 Nis 2026

Google Meet, Slack ve RAG ile Toplantı Hafızası Kurmak11 Nis 2026