Claude Skills Nedir? SKILL.md ile Tekrarlanabilir Ajan İş Akışları (2026 Rehberi)

Bir ajan kuruyorsunuz: müşteri e-postalarını sınıflandırıp ticketlara dönüştüren, her biri için doğru departmana yönlendirme yapan ve düşük öncelikli olanları otomatik kapatan. Ajan çalışıyor. Güzel. Üç ay sonra aynı ajanın gelen kutusunu periyodik olarak tarayıp özet rapor çıkarmasını istiyorsunuz. Mevcut system prompt’u mı değiştiriyorsunuz? Yeni bir ajan mı yazıyorsunuz? Yoksa “sadece şunu da ekle” diye birikim mi yaratıyorsunuz?

İşte tam bu noktada Anthropic’in Ekim 2025’te Claude Code ile birlikte yayınladığı Skills sistemi anlam kazanıyor. Ajan ne yapabileceğini tek bir dev prompt’a doldurmak yerine, yeteneklerini bağımsız, yeniden kullanılabilir ve ihtiyaç anında yüklenen birimler hâline getiriyor.

Bu rehberde Skill’in teknik tanımından başlayıp gerçek bir PDF özetleyici walkthrough ile bitireceğiz. Sonda bir de MCP ve raw agent prompt’tan farkını netleştireceğiz, çünkü bu üç kavram arama sonuçlarında birbirinin yerini sık sık alıyor.

Claude Skills: ajan yeteneklerini modüler, ihtiyaç anında yüklenen birimler hâline getirir.

Skill Nedir? Tek Cümlelik Tanım

Bir Claude Skill, bir klasör içine konan SKILL.md dosyasıdır, ve o dosyanın iki katmanlı yapısı ile Claude ihtiyaç duyduğu anda ilgili talimatları tam olarak yükler.

Bu kadar. Ekstra SDK’ya, ayrı bir servise ya da derleme adımına ihtiyaç yok. Skills sistemi doğrudan Claude Code’un çalışma dizinini tarar ve skills/ (ya da .claude/skills/) altındaki her alt klasörün içindeki SKILL.md dosyasını bulur.

Klasör yapısı şöyle görünür:

project/
├── .claude/
│   └── skills/
│       ├── pdf-ozetleyici/
│       │   └── SKILL.md
│       ├── pr-reviewer/
│       │   └── SKILL.md
│       └── haftalik-rapor/
│           └── SKILL.md
└── src/
    └── ...

Her SKILL.md dosyası iki bölüm içerir: frontmatter içindeki description alanı ve altındaki markdown body. Bu ayrım tesadüf değil, Skills sisteminin kalbidir.

Progressive Disclosure Mimarisi

Skills’in zekice yanı, her Skill’in tam içeriğini başlangıçta context’e yüklememesidir.

Claude Code başladığında skills/ altındaki tüm klasörleri tarar ve her SKILL.md’nin yalnızca description alanını okur. Bu kısa tanım listesi model context’ine girer. Geri kalan tüm içerik, talimatlar, örnekler, edge-case’ler, araç çağrı sıralamaları, henüz yüklü değildir.

[Model Context]
Mevcut Skills:
- pdf-ozetleyici: PDF dosyalarını 3 bölümde özetler: özet, ...
- pr-reviewer: Açık PR'ları code review perspektifinden analiz eder...
- haftalik-rapor: Haftalık aktivite özeti oluşturur, Pazartesi sabahları...

Kullanıcı bir görev verdiğinde ya da ajan bir karar noktasına geldiğinde, Claude bu liste içinden alaka düzeyine göre ilgili Skill’i seçer. Seçilen Skill’in tam SKILL.md body’si o anda context’e eklenir ve talimatlar uygulanır.

Bu mimari iki kritik avantaj sağlar:

Context verimliliği. On tane Skill tanımladınız ama görev yalnızca birini gerektiriyor. Yalnızca o birinin talimatları context’e giriyor. Gereksiz token yakmazsınız, modelin dikkatini dağıtmazsınız.

Bağımsız güncelleme. pdf-ozetleyici/SKILL.md’yi güncellemek diğer Skill’lere dokunmaz. Skill’leri ayrı dosyalarda tuttuğunuz için Git geçmişi de temiz kalır, kim ne zaman neyi neden değiştirdi açıkça görünür.

description Alanının Kritikliği

Tüm sistem şu kısıma dayanıyor:

---
name: pdf-ozetleyici
description: >
  PDF dosyalarını özetlemek, içerik analizi yapmak veya belgeden
  bilgi çıkarmak gerektiğinde bu skill'i kullan. Trigger koşulları:
  kullanıcı ".pdf" uzantılı dosya verdiğinde, "belgeden özetle",
  "raporu analiz et", "makaleden çıkarım yap" gibi ifadeler kullandığında.
---

description alanı, Claude’un trigger kararı verdiği tek veridir. Model bu metni okuyarak “bu görev için bu Skill gerekiyor mu?” diye değerlendirme yapar. Dolayısıyla iyi bir description:

• Ne zaman tetikleneceğini açıkça söyler. “PDF işleme” demek yeterli değil. “PDF dosyası verildiğinde veya kullanıcı belge analizi istediğinde” çok daha güvenilir bir trigger.
• Görev sınırlarını çizer. Skill’in ne yapmadığını da belirtmek, benzer Skill’ler arasındaki çakışmayı önler.
• Kısa ama spesifik olur. 2-4 cümle ideal. Çok kısa olursa model trigger koşulunu ıskalıyor; çok uzun olursa her Skill’in description’ı birbirine karışıyor.

Kötü description:

description: PDF dosyaları için skill.

Bu tanımla model hangi görevde bu Skill’i kullanacağını tahmin etmek zorunda kalır. Beş Skill’den ikisi “PDF ile ilgili” görünüyorsa model ikisi arasında tutarsız seçimler yapabilir.

İyi description:

description: >
  Kullanıcı bir PDF dosyası paylaştığında veya "belgeden özetle",
  "raporu analiz et", "makaledeki bulguları çıkar" gibi ifadeler
  kullandığında tetikle. Bu skill üç aşamalı bir özet çerçevesi uygular:
  yönetici özeti, ana bulgular, kritik çıkarımlar.
  Kodlama, test veya sistem yönetimi görevleri için kullanma.

Örnek: PDF Özetleyici Skill (Tam Walkthrough)

Somut bir Skill yazalım. Araştırmacılar ve danışmanlar için PDF raporlarını standart bir formatta özetleyen bir Skill. Dosya yolunu .claude/skills/pdf-ozetleyici/SKILL.md olarak oluşturuyoruz:

---
name: pdf-ozetleyici
description: >
  Kullanıcı bir PDF dosyası gönderdiğinde veya "belgeyi özetle",
  "raporu analiz et", "makaledeki sonuçları çıkar", "bu PDF'ten ne anlıyorsun"
  gibi ifadeler kullandığında tetikle. Araştırma raporları, akademik makaleler,
  iş dökümanları ve teknik belgeler için geçerlidir.
  Kod yazma, test çalıştırma veya dosya sistemi işlemleri için bu skill'i kullanma.
---

# PDF Özetleyici

Kullanıcının verdiği PDF belgesini aşağıdaki üç aşamalı çerçevede analiz et.

## Adım 1: Belgeyi Oku

`Read` aracını kullan ve belgeyi tam olarak oku. PDF binary ise önce `bash` ile
`pdftotext` çağır:

```bash
pdftotext "{dosya_yolu}" - 

Metin çıkaramazsan kullanıcıya haber ver ve alternatif format iste.

Adım 2: Üç Katmanlı Özet Çerçevesi

Belgeyi okuduktan sonra şu formatta yanıt ver:

Yönetici Özeti (2-3 cümle)

Belgenin ana argümanı veya temel bulgusu. Okuyucu yalnızca bu kısmı okusa yeterli olacak şekilde.

Ana Bulgular (madde madde, max 7 madde)

• Her madde tek bir somut bulgu, karar veya öneride bulunur.
• Belirsiz ifadelerden kaçın (“bazı sonuçlar…” yerine sayı ve oran kullan).
• Kaynak sayfa/bölüm numarasını parantez içinde ver: (s. 12)

Kritik Çıkarımlar (2-4 madde)

Bu belgeden ne yapılmalı? Okuyucunun harekete geçebileceği somut öneriler. Eylem fiiliyle başlayan cümleler yaz: “Güncelle”, “Değerlendir”, “İncele”.

Adım 3: Kapsam Notu

Özetin sonuna şu satırı ekle:

Bu özet N sayfalık belgeden üretildi. Tam metin için orijinal dosyayı inceleyin.

Stil Kuralları

• Türkçe yaz. Teknik terimler için parantez içinde orijinal terimi ver.
• Yorum katma; yalnızca belgede olan bilgiyi aktar.
• Tablo varsa metne uygun şekilde düz listeye çevir.
• Önemli uyarı veya kısıtlama notu belgede geçiyorsa Kritik Çıkarımlar’a ekle.

Bu Skill'i çalıştırmak için kullanıcı şunu yazabilir:

“analysis_report_q1_2026.pdf dosyasını özetle”

Claude, `description`'dan doğru Skill'i seçer, `SKILL.md` body'sini context'e yükler, `pdftotext`'i çalıştırır, metni okur ve üç katmanlı formatta yanıt üretir. Siz tek satır araç kodu yazmadınız, yalnızca bir markdown dosyası yazdınız.

### Skills'i Genişletmek: Yan Dosyalar

Skill klasörü yalnızca `SKILL.md` içermek zorunda değil. İlgili şablonları, yardımcı scriptleri ya da referans dokümanlarını da aynı klasöre koyabilirsiniz:

.claude/skills/pdf-ozetleyici/ ├── SKILL.md ├── ozet-sablonu.md ← Skill içinden Read ile çağrılabilir └── ornek-cikti.md ← Few-shot örneği

`SKILL.md` body içinde `Read("{skill_klasoru}/ozet-sablonu.md")` ile bu dosyaya erişebilirsiniz. Bu sayede şablon değiştiğinde `SKILL.md`'ye dokunmanız gerekmez.

## MCP ve Agent'ten Farkı

Skills, MCP ve agent kavramları aynı cümlelerde sık sık geçiyor. Üçünün de farklı seviyelerde çalıştığını görmek kafa karışıklığını gideriyor:

| | **Claude Skill** | **MCP Sunucusu** | **Agent Prompt** |
|---|---|---|---|
| **Ne sağlar?** | Davranış talimatları | Araç / veri bağlantısı | Rol ve genel yönelim |
| **Tetiklenme** | Görev alaka düzeyine göre dinamik | Açık tool çağrısıyla | Her zaman aktif |
| **Yükleme zamanı** | İhtiyaç anında (progressive) | Bağlantı kurulduğunda | Oturum başında |
| **Depolama** | `SKILL.md` dosyası | Ayrı süreç / server | System prompt'un içi |
| **Güncelleme** | Dosyayı düzenle, yeniden başlatma gerekmez | Sunucu kodunu değiştir | Prompt'u yeniden yaz |

Pratik ayrım şöyle düşünebilirsiniz:

**MCP**, Claude'a yeni araçlar verir, "Slack'e mesaj at", "Postgres'e sorgu gönder". Araca erişim bir process üzerinden gelir, Skills'in bilgi alanı dışında. [MCP'nin nasıl çalıştığını](/blog/mcp-nedir-model-context-protocol-rehberi/) daha önce detaylı işledik.

**Agent prompt**, Claude'a kimlik ve genel çerçeve verir, "sen kıdemli bir kod inceleme uzmanısın, her zaman güvenlik açıklarını önce raporla". Bu talimatlar daima aktif, daima context'te.

**Skill**, belirli bir görev türü için adım adım bir iş akışı verir, "bu görevi şu sırayla, bu çerçevede, şu formatta tamamla". Yalnızca ilgili görev geldiğinde devreye girer. Bu modülerlik, [otonom ajan](/blog/sifirdan-ai-agent-yapimi/) kuruyorsanız sistemi bakımı kolay parçalara ayırmanın en temiz yoludur.

İkisi aynı anda kullanılabilir: MCP sunucusu size araç sağlar, Skill o araçları nasıl kullanacağınızı tarif eder.

## Ne Zaman Skill Yazmalısınız?

Birkaç pratik heuristic:

**Evet, Skill yazın, eğer:**
- Aynı görev türü haftada birden fazla tekrarlanıyorsa
- Talimatlar 5 cümleden uzunsa ve başka görevleri etkilemiyorsa
- Farklı projelerde aynı iş akışına ihtiyaç duyuyorsanız (Skill klasörünü kopyalarsınız)
- A/B testi yapmak istiyorsanız, iki farklı Skill, aynı trigger koşulu, sonuçları karşılaştırırsınız

**Hayır, Skill gerekmez, eğer:**
- Görev tek seferlik ya da çok bağlam-spesifikse
- Talimat zaten kısa bir system prompt paragrafına sığıyorsa
- İş akışı çok sık değişiyorsa (sık güncelleme avantajı anlamsızlaşır)

## Sonuç: Modülerlik Karmaşıklığı Yönetir

Skill sistemi özünde bir disiplin aracı. "Her şeyi tek büyük prompt'a yaz" yaklaşımının kaçınılmaz sonucu olan karmaşa ve güncelleme korkusunun panzehiri.

Küçük başlayın: bir Skill, iyi bir `description`, net bir çerçeve. İlk Skill çalışınca ikincisini eklemek son derece doğal geliyor. Altı ay sonra bakıyorsunuz: her iş akışı kendi dosyasında, Git geçmişi anlamlı, yeni ekip üyesi ilk günden skills klasörüne bakıp ajanın ne yapabildiğini anlıyor.

`SKILL.md` yazmak için gereken tek ön koşul, işi iyi tarif edebilmek. Sonrası Claude'a.

## Sonraki adım

Skills'i hangi katmanda kullanacağına karar vermek için şu rehberler bağlamı tamamlıyor:

- [AI Agent Framework Karşılaştırma: LangGraph, CrewAI, AutoGen](/blog/ai-agent-framework-karsilastirma-langgraph-crewai-autogen/) — Skills'i Claude dışındaki framework'lerle nasıl konumlandırırsın.