Claude Code Skill, Subagent ve Hook Nedir?

Claude Code’u bir süredir kullanıyorsanız üç terimi mutlaka görmüşsünüzdür: skill, subagent ve hook. Üçü de “Claude Code’u özelleştirmek” başlığı altında geçiyor ve ilk bakışta hepsi aynı işi yapıyormuş gibi duruyor.

Yapmıyorlar. Her birinin çözdüğü problem farklı, yanlış olanı seçmek ya gereksiz karmaşa ya da hiç çalışmayan bir kurulum demek 🛠️

Kısa Cevap

Slash Komutları Artık Skill Oldu

Önce en önemli değişiklik, çünkü eski rehberlerin çoğu bunu içermiyor: özel slash komutları skill’lere birleştirildi.

.claude/commands/deploy.md dosyası ile .claude/skills/deploy/SKILL.md klasörü aynı şeyi yapar, ikisi de /deploy komutunu oluşturur. Eski dosyalarınız çalışmaya devam ediyor, bozulmadı.

Skill’in fazladan getirdikleri:

• Yardımcı dosyalar için bir klasör (şablonlar, betikler, referans metinler)
• Komutu kimin çağırabileceğini kontrol etme
• Claude’un ilgili olduğunda skill’i kendiliğinden yükleyebilmesi

İkisi aynı ismi taşıyorsa skill kazanır.

Skill Nedir, Nasıl Yazılır?

Skill, içinde bir SKILL.md dosyası olan bir klasör. Talimatları yazarsınız, Claude bunu araç setine ekler.

Ne zaman yazmalısınız? Aynı talimatları, kontrol listesini veya çok adımlı prosedürü sohbete tekrar tekrar yapıştırıyorsanız. Ya da CLAUDE.md dosyanızdaki bir bölüm artık bir “bilgi” olmaktan çıkıp bir “prosedür” haline geldiyse.

Dosya Nereye Konur?

Komutun ismi klasör adından gelir. .claude/skills/deploy-staging/SKILL.md dosyası /deploy-staging komutunu oluşturur.

Proje skill’lerini sürüm kontrolüne dahil edin, böylece ekibiniz de kullanıp geliştirebilir.

Örnek Skill

---
name: deploy
description: Uygulamayı production ortamına dağıtır
disable-model-invocation: true
---

$ARGUMENTS ortamına dağıt:

1. Test paketini çalıştır
2. Uygulamayı derle
3. Dağıtım hedefine push et
4. Dağıtımın başarılı olduğunu doğrula

İşinize yarayacak alanlar:

Argüman Geçirme

$ARGUMENTS yer tutucusu, skill adından sonra yazdığınız her şeyle değiştirilir:

---
name: fix-issue
description: Bir GitHub issue'sunu düzeltir
disable-model-invocation: true
---

$ARGUMENTS numaralı GitHub issue'sunu kodlama standartlarımıza uygun düzelt.

/fix-issue 123 yazınca Claude “123 numaralı GitHub issue’sunu…” metnini alır.

Claude Kendiliğinden Çalıştırmasın

Varsayılan olarak hem siz hem Claude her skill’i çağırabilir. Bu her zaman istediğiniz şey değil.

disable-model-invocation: true koyduğunuzda skill’i yalnızca siz çağırabilirsiniz. /deploy, /commit, /send-slack-message gibi yan etkisi olan işlerde şart. Claude’un “kod hazır görünüyor” diye kendiliğinden dağıtım yapmasını istemezsiniz.

Tersi de var: user-invocable: false koyarsanız skill menüde görünmez, sadece Claude kullanır. Eski bir sistemin nasıl çalıştığını anlatan bir bilgi notu için mantıklı, çünkü kullanıcının onu komut olarak çağırması anlamsız.

Subagent Nedir, Ne Zaman Kullanılır?

Subagent, kendi bağlam penceresinde çalışan ayrı bir yardımcı. Kendi sistem promptu ve kendi araç izinleri var.

Ne işe yarar? Bir yan görev ana sohbetinizi bir daha bakmayacağınız arama sonuçları, loglar veya dosya içerikleriyle dolduracaksa, subagent o işi kendi bağlamında yapar ve sadece özeti geri döner.

Sağladıkları:

• Bağlam korur: Gürültü ana sohbetin dışında kalır
• Kısıt dayatır: Hangi araçları kullanabileceğini siz belirlersiniz
• Maliyet düşürür: İşi Haiku gibi hızlı ve ucuz bir modele yönlendirirsiniz

Örnek Subagent

Dosya .claude/agents/ klasörüne konur:

---
name: code-reviewer
description: Kod kalitesi ve iyi pratikler için inceleme yapar
tools: Read, Glob, Grep
model: sonnet
---

Sen bir kod inceleyicisin. Çağrıldığında kodu analiz et ve kalite,
güvenlik ve iyi pratikler konusunda somut geri bildirim ver.

Frontmatter yapılandırmayı, gövde ise sistem promptunu tanımlar.

Subagent mı, Ana Sohbet mi?

Ana sohbette kalın eğer:

• İş sık sık gidip gelme veya kademeli iyileştirme gerektiriyorsa
• Planlama, uygulama ve test aşamaları aynı bağlamı paylaşıyorsa
• Hızlı ve küçük bir değişiklik yapıyorsanız

Subagent açın eğer:

• İş uzun çıktı üretiyor ve o çıktıya bir daha bakmayacaksanız
• Araç erişimini kısıtlamak istiyorsanız
• İş kendi kendine yeterli ve bir özet döndürebiliyorsa

Hook Nedir, Ne İşe Yarar?

Hook’lar, Claude Code’da bir şey olduğunda çalışan betikler. Farkı şu: promptlar modelin yorumuna kalıyor, hook’lar kod çalıştırıyor ve halüsinasyon göremiyor.

Bir kuralın kesinlikle uygulanmasını istiyorsanız prompt’a yazmayın, hook yazın.

En çok kullanılan olaylar:

Örnek: Yıkıcı Komutu Engelleme

Hook’lar .claude/settings.json dosyasında tanımlanır:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

Betiğin kendisi:

#!/bin/bash
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  echo "Yıkıcı komut engellendi" >&2
  exit 2
fi

exit 0

Kural basit: çıkış kodu 2 demek “engelle” demek. stderr’e yazdığınız metin Claude’a hata mesajı olarak gider. Çıkış kodu 0 ise her şey normal devam eder.

Hangisi Ne Zaman?

Sık Yapılan Hatalar

1. Her şeyi CLAUDE.md‘ye yığmak. Orası her oturumda tamamen yükleniyor. Bir bölüm prosedüre dönüştüyse skill’e taşıyın.

2. Yan etkili komutları korumasız bırakmak. /deploy gibi bir skill’e disable-model-invocation: true koymazsanız Claude uygun gördüğü bir anda çalıştırabilir.

3. Subagent’ın sohbeti bildiğini sanmak. Bilmiyor. Görev tarifini eksiksiz yazın.

4. PostToolUse ile engellemeye çalışmak. Araç çoktan çalıştı. PreToolUse gerekiyor.

5. Her iş için subagent açmak. Gidip gelme gerektiren işler ana sohbette daha hızlı biter, subagent sıfırdan başlıyor.

Sıkça Sorulan Sorular (SSS)

Claude Code skill nedir? Skill, içinde SKILL.md dosyası bulunan bir klasördür. İçine talimatlarınızı yazarsınız ve Claude bunu araç setine ekler. CLAUDE.md içeriğinin aksine skill’in gövdesi yalnızca kullanıldığında bağlama yüklenir, bu yüzden uzun referans metinleri neredeyse maliyetsiz olur.

Claude Code slash komutları kaldırıldı mı? Kaldırılmadı, skill’lere birleştirildi. .claude/commands/deploy.md dosyası ile .claude/skills/deploy/SKILL.md klasörü aynı şekilde /deploy komutunu oluşturur. Eski dosyalarınız çalışmaya devam eder, ikisi aynı ismi taşırsa skill öncelik kazanır.

Skill ile subagent arasındaki fark nedir? Skill ana sohbetin bağlamında çalışır ve oraya talimat ekler. Subagent ise kendi bağlam penceresinde, kendi sistem promptu ve araç izinleriyle çalışır, işi bitirince sadece özeti döner. Uzun çıktı üreten işler için subagent, tekrar eden prosedürler için skill kullanılır.

Claude Code hook nedir? Hook, Claude Code’da belirli bir olay gerçekleştiğinde çalışan bir betiktir. Promptların aksine kod çalıştırır ve halüsinasyon göremez, bu yüzden kesinlikle uygulanması gereken kurallar için kullanılır. .claude/settings.json dosyasında tanımlanır.

Hook bir komutu nasıl engeller? Betiğin çıkış kodu 2 döndürmesi “engelle” anlamına gelir ve stderr’e yazdığınız metin Claude’a hata mesajı olarak gider. Engelleme yalnızca PreToolUse gibi işlem öncesi çalışan olaylarda mümkündür, PostToolUse engelleyemez çünkü araç çoktan çalışmıştır.

Claude’un bir skill’i kendiliğinden çalıştırmasını nasıl engellerim? SKILL.md dosyasının frontmatter kısmına disable-model-invocation: true ekleyin. Bu durumda skill’i yalnızca siz komutla çağırabilirsiniz. Dağıtım, commit veya mesaj gönderme gibi yan etkili işlemler için önerilir.

Skill dosyaları nereye konur? Kişisel skill’ler ~/.claude/skills/<isim>/SKILL.md yoluna, projeye özel skill’ler .claude/skills/<isim>/SKILL.md yoluna konur. Komutun ismi klasör adından gelir, yani deploy-staging klasörü /deploy-staging komutunu oluşturur.

Subagent ana sohbeti görebiliyor mu? Hayır. Subagent yalnızca kendi sistem promptunu ve çalışma dizini gibi temel bilgileri alır, ana sohbette konuşulanları görmez. Bu yüzden ona verilen görev tarifinin kendi başına anlaşılır olması gerekir.

Özet

Üçü birbirinin alternatifi değil, birbirini tamamlıyor:

• Skill tekrar eden prosedürü dosyaya alır, bağlam maliyetini düşürür
• Subagent gürültülü işi ana sohbetten çıkarır, araç erişimini kısıtlar
• Hook kuralı modelin insafına bırakmaz, kodla dayatır

En sık kurulan kombinasyon: prosedürü skill yaparsınız, ağır keşif kısmını subagent‘a atarsınız, geri dönülmez adımları da bir hook ile korursunuz.

Claude Code’un altındaki modellerin düşünme davranışı için extended thinking ve adaptive thinking yazısına, araç ekleme tarafı için MCP rehberine bakabilirsiniz 👀