Claude Code eklentisi nedir ve nasıl çalışır?

Claude Code eklentisi nedir

Claude Code eklentisi, Claude Code'un tek bir birim olarak yüklediği ve yönettiği bileşenler dizinidir. Bu bileşenler; yetenekler, aracılar, kancalar, MCP sunucuları, LSP sunucuları ve arka plan izleyicileridir. Bir eklentiyi yüklemek, tüm parçalarını tek bir isim altında aynı anda ekler; devre dışı bırakmak ise aynı şekilde kaldırılmalarını sağlar.

Bir eklenti, aracıya daha önce sahip olmadığı hiçbir yetenek kazandırmaz. Eklenti içindeki her parça, .claude/ dizini altında elle yazabileceğiniz öğelerdir. Eklenti bir paketleme katmanıdır; bu parçaları sürümlemenin, on beş kişiye dağıtmanın ve herkesin dosyaları kopyalamasını istemeden daha sonra güncellemenin bir yoludur. Tüm mantık bundan ibarettir ve eklentilerle ilgili kafa karışıklıklarının çoğu, bunların yeni bir yetenek türü olduğunu varsaymaktan kaynaklanır.

.claude-plugin/plugin.json konumundaki isteğe bağlı manifest dosyası eklentiyi isimlendirir ve bu isim bir ad alanı (namespace) haline gelir. commit-commands adlı bir eklentideki yetenek, /commit-commands:commit olarak çağrılır; böylece iki farklı eklenti, birbirini gölgelemeden commit adlı bir yeteneği sunabilir. Eklenti aracıları da @-bahsetme listesinde aynı şekilde plugin-name:agent-name olarak kapsamlandırılır.

Eklenti, yetenek, MCP sunucusu veya kurallar dosyası

Bu dört terim sanki birbirinin rakibiymiş gibi kullanılır. Ancak durum böyle değildir ve aralarındaki sınırın bir kez belirtilmesi faydalıdır.

• Yetenek (skill), görev gerektirdiğinde Claude'un yüklediği tek bir komut birimidir. Bkz: Agent Yeteneğinin gerçekte ne olduğu.
• MCP sunucusu, araçları bir protokol üzerinden aracıya (agent) sunan ayrı bir süreçtir; genellikle kendi çalıştırdığınız bir ağ servisidir.
• CLAUDE.md gibi bir kurallar dosyası, oturum başlangıcında okunan ve her şeye uygulanan proje bağlamıdır.
• Eklenti (plugin), yetenekleri, aracıları, kancaları (hooks) ve MCP sunucusu tanımlarını bir sürüm numarası ve dağıtım kanalıyla birlikte bir arada tutabilen bir kapsayıcıdır.

Dolayısıyla bir eklentinin yanıtladığı soru "aracı ne yapabilir" değildir. Soru, "bunu ekibime nasıl dağıtırım ve gelecek ay nasıl güncellerim" sorusudur. İlk üçü arasında bir seçim yapıyorsanız, yetenekler, MCP sunucuları ve kurallar dosyalarının karşılaştırması bu kararı ayrıntılı olarak ele almaktadır. Eğer ilgilendiğiniz kısım MCP ise, kendi MCP sunucularınızı bir VPS üzerinde çalıştırmak barındırma tarafını kapsamaktadır.

Eklentilerin konumu ve içeriği

Marketplace üzerinden yüklenen bir eklenti, klonlandığı yerden çalıştırılmak yerine ~/.claude/plugins/cache dizinindeki yerel bir önbelleğe kopyalanır. Yüklenen her sürüm kendi dizinine sahip olur. Güncelleme veya kaldırma işlemi yaptığınızda, eski sürüm dizini yetim (orphaned) olarak işaretlenir ve yaklaşık iki hafta sonra silinir; böylece eski sürümü zaten yüklemiş olan bir oturum, işlem ortasında hata vermek yerine çalışmaya devam eder.

Yol her güncellemede değiştiği için, bir eklenti kendi konumunu asla sabit (hardcode) olarak tanımlamamalıdır. Eklenti içindeki kancalar (hooks) ve MCP yapılandırmaları, mevcut yükleme dizinine çözümleyen ${CLAUDE_PLUGIN_ROOT} değişkenini kullanır. Güncelleme sonrasında korunması gereken durum bilgileri, ~/.claude/plugins/data/ altında kararlı bir dizine çözümleyen ${CLAUDE_PLUGIN_DATA} içine kaydedilmelidir.

Yalnızca eklentinin kendi dizini önbelleğe kopyalanır; bu durum, kullanıcıların geç aşamada fark ettiği bir soruna yol açar. Eklenti kök dizininin dışını işaret eden bir yol (örneğin ../shared-utils), yerel yollarla geliştirme yaparken çalışır ancak yükleme sonrasında bozulur, çünkü bu dosyalar hiçbir zaman kopyalanmamıştır.

Dizin yapısı şu şekildedir:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
├── .mcp.json
└── bin/

Yalnızca plugin.json, .claude-plugin/ dizininin içine yerleştirilmelidir. Diğer her şey eklenti kök dizininde bulunur. skills/ veya hooks/ dosyalarının .claude-plugin/ içine konulması, bir eklentinin sorunsuz yüklenip ardından hiçbir işlev göstermemesinin en yaygın nedenidir: Claude Code bu dizinleri kök dizinde arar, bulamaz ve eklentiyi hiçbir bileşen olmadan yükler.

Manifest dosyasının kendisi küçüktür.

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0"
}

Claude Code eklentisi nasıl kurulur

Kurulum iki aşamadan oluşur ve ilk aşama aslında hiçbir şey kurmaz. Öncelikle eklenti kataloğu olan bir marketplace eklersiniz, ardından bu katalogdan tekil eklentileri kurarsınız. Anthropic'in resmi marketplace'i olan claude-plugins-official, Claude Code'u etkileşimli olarak ilk başlattığınızda sizin için kaydedilir. Diğerlerini ise kendiniz eklersiniz.

/plugin marketplace add anthropics/claude-code
/plugin install commit-commands@claude-code-plugins

Deponun anthropics/claude-code, marketplace'in ise claude-code-plugins olarak adlandırıldığına dikkat edin. İsim, depo yolundan değil, depo içindeki katalog dosyasından gelir; bu nedenle bir kurulum komutu girmeden önce marketplace ismini /plugin içindeki Marketplaces sekmesinden okuyun.

Kurulumdan sonra özet satırını okuyun. Plugin is now active., bileşenlerin bu oturumda yüklendiği anlamına gelir. Run /reload-plugins to activate., bileşenlerin yüklenmediğini ve ilgili komutu çalıştırmanız gerektiğini belirtir. Eğer /reload-plugins, konuşmanın yeniden okunacağı konusunda bir uyarı verirse, komutu /reload-plugins --force olarak tekrar çalıştırın. Ardından eklentinin gerçekten orada olduğunu doğrulayın: /plugin, eklentiyi Installed sekmesi altında gösterir; /help, yeteneklerini Custom commands altında listeler ve yüklenemeyen herhangi bir öğe, nedeni ile birlikte Errors sekmesinde görünür.

Kurulum sırasında bir kapsam (scope) istenir ve bu kapsam, eklentiye kimin erişebileceğini belirler. Kullanıcı kapsamı (user scope), her projede sizi kapsar. Proje kapsamı (project scope), eklentiyi deponun .claude/settings.json dosyası içindeki enabledPlugins kısmına yazar; böylece depoyu klonlayan herkese bu eklenti önerilir. Yerel kapsam (local scope) ise sadece bu depoda sizi kapsar.

Bir betik, bir Dockerfile veya etkileşimli panelin bulunmadığı herhangi bir oturum için bunun yerine kabuk (shell) formunu kullanın. --scope parametresini geçmediğiniz sürece eklenti kullanıcı kapsamına kurulur.

claude plugin install commit-commands@claude-code-plugins --scope project
claude plugin list

claude plugin install oturum dışında çalışır; bu nedenle halihazırda açık olan bir oturum, siz /reload-plugins komutunu çalıştırana veya yeni bir oturum başlatana kadar yeni eklentiyi görmeyecektir.

Mevcut eklentileri yönetmek her iki yerde de aynı yöntemle yapılır. /plugin list, kurulu olanları listeler ve --enabled veya --disabled parametrelerini kabul eder. /plugin disable name@marketplace bir eklentiyi kaldırmadan devre dışı bırakır, /plugin enable tekrar etkinleştirir ve /plugin uninstall ise tamamen siler. Eğik çizgi (slash) komut formları, değişikliği uygulamak için eklenti panelini açar; bu yüzden betiklerde claude plugin ... kabuk karşılıklarını kullanmak gerekir.

Bir marketplace'i tüm ekibe sunmak için onu projenin .claude/settings.json dosyasına ekleyin. Üyeler, depo klasörüne güven verdiklerinde eklentiyi kurmaları için uyarılırlar.

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

Kendi eklentinizi geliştirirken marketplace'i tamamen atlayın. claude --plugin-dir ./my-plugin, bir dizini o oturum için yükler; /reload-plugins, yaptığınız değişiklikleri yeniden başlatmaya gerek kalmadan algılar ve claude plugin validate ./my-plugin, manifest dosyasını, yetenek ve aracı ön bilgilerini ve hooks/hooks.json öğesini başkaları görmeden önce denetler.

Claude Code eklentisinin maliyeti nedir?

Mekanizma ücretsizdir. Ağustos 2026 itibarıyla bir pazar yeri eklemek, eklenti kurmak veya bir eklentiyi etkin tutmak için herhangi bir ücret alınmamaktadır. Resmi ve topluluk pazar yerleri herkese açık git depolarıdır ve bir eklenti, metin dosyalarından oluşan bir dizindir.

Bir eklentinin maliyeti token cinsindendir ve abonelik kullanımınız veya API faturanız aslında bu tokenları ölçer. Bir eklentinin bu ikisinden hangisini tüketeceği, aracı en başta nasıl ödediğinize bağlıdır; Claude Code'un her plandaki maliyeti bölümü, abonelik katmanlarını token başına API fiyatlandırmasıyla yan yana açıklar. Bu maliyet üç farklı şekilde ortaya çıkar ve farklı davranışlar sergilerler.

Sabit bağlam maliyeti. Bir eklentinin katkıda bulunduğu içerik, bağlamınızda yer alır ve oturumun her adımında yeniden okunur. Kurulumdan önce, /plugin detay görünümü, token cinsinden bir Context cost tahmini ve ekleyeceğiniz komutları, becerileri, aracıları, kancaları (hooks), MCP ve LSP sunucularını listeleyen bir Will install bölümü gösterir. Her ikisini de inceleyin. Yerel veya özel pazar yerlerinden gelen eklentiler bu veriyi sağlamayabilir; bu durumda tahmini kendiniz yapmanız gerekir. Bir MCP sunucusu içeren eklentiler genellikle en ağır olanlarıdır, çünkü araç tanımları büyüktür; ancak MCP araç aramasını destekleyen modellerde bu tanımlar, bir araca ihtiyaç duyulana kadar ertelenir.

Çağırma maliyeti. Bir eklentinin becerisini çalıştırmak, talimatlarını konuşmaya ekler; bu nedenle beceri gövdesi için yalnızca kullanıldığında ödeme yaparsınız. Ancak gövde kısmı ucuzdur; becerinin aracıya ne yapacağını söylemesi maliyetli olabilir: unlazy becerisinin Depth Tree yöntemi, tokenlarının neredeyse tamamını, aracının bir görevi tamamlandı olarak işaretlemesine izin verilmeden önce zorunlu kıldığı ek geçişler için harcar, kurduğunuz dosya için değil. Bir aracı farklıdır. Bir alt aracı, kendi sistem istemi ve kendi önbelleği ile kendi konuşmasını yürütür ve önbellek isabeti olmadan başlar; bu nedenle iş akışı aracıları tetikleyen bir eklenti, bağlam tahmininin önerdiğinden önemli ölçüde daha maliyetlidir.

Önbellek maliyeti. Bir eklentiyi oturum ortasında etkinleştirmek veya devre dışı bırakmak, bir sonraki isteğin tüm konuşmanızı yeniden işlemesine neden olabilir. Beceriler, komutlar, aracılar, kancalar, LSP sunucuları, izleyiciler ve temalar bunu asla yapmaz: ekledikleri şeyler mevcut geçmişin sonuna eklenir, böylece bir sonraki istek yeni içerik için ödeme yapar ve öncesindeki her şeyi önbellekten okumaya devam eder. İstisna, bir MCP sunucusu sağlayan eklentilerdir. Araçları araç araması ile ertelenirse, önbellek korunur. Eğer istem öneki (prompt prefix) içine yüklenirlerse, bir sonraki istek tüm konuşmayı önbelleğe alınmamış girdi olarak yeniden okur. /reload-plugins uyarısının ve --force geçilene kadar reddetmesinin nedeni tam olarak budur.

Bunu tahmin etmek yerine izleyebilirsiniz. Her API yanıtı cache_read_input_tokens ve cache_creation_input_tokens değerlerini raporlar ve canlı token kullanımını gösteren özel bir durum satırı her ikisini de gözünüzün önüne getirir. Sağlıklı bir oturum, oluşturduğundan çok daha fazlasını okur. Eğer oluşturma oranı her adımda yüksek kalıyorsa, önekinizdeki bir şey her adımda değişiyor demektir. Pencereyi neyin doldurduğuna dair daha geniş bir resim için Claude Code bağlam penceresini yönetme ve token sayılarının gerçekte ne anlama geldiği bölümlerine bakın.

Bir temizlik işlemi kendi maliyetini karşılar. Installed sekmesi, en az iki haftadır kullanmadığınız eklentileri bir Not used recently başlığı altında gruplar ve detay görünümünde bir Last used satırı içerir. Bu eklentiler her oturumda başlangıç süresi ve bağlam açısından size maliyet getirmeye devam eder. Bunları devre dışı bırakın veya kaldırın.

Bir eklenti sizin izinlerinizle çalışır

Anthropic'in kendi belgeleri bu konuda oldukça nettir: eklentiler ve pazar yerleri, makinenizde kullanıcı izinlerinizle rastgele kod çalıştırabilen, yüksek güven gerektiren bileşenlerdir. Bu varsayımsal bir durum değildir. Bir eklentinin kancaları (hooks), araç çağrılarından önce ve sonra dahil olmak üzere oturum olaylarında shell komutları çalıştırır. Eklentinin bin/ dizini, eklenti etkinleştirildiğinde Bash aracının PATH değişkenine eklenir. MCP sunucuları ise eklentinin başlattığı süreçlerdir. Burada hiçbir şey kullanıcı hesabınızdan yalıtılmış (sandboxed) değildir.

Bir dizüstü bilgisayarda bu risk, masaüstü kullanıcınızın erişebildiği alanlarla sınırlıdır. Bir sunucuda ise durum genellikle böyle değildir. Ajanı çalıştıran hesap genellikle SSH anahtarlarını, dağıtım (deploy) belirteçlerini, bir bulut CLI oturumunu ve Docker soketine erişimi elinde tutar; bu nedenle "kullanıcı yetkilerinizle rastgele kod çalıştırmak", doğrudan makinenin ele geçirilmesi anlamına gelir. Eğer Claude Code bir VPS üzerinde çalışıyorsa, herhangi bir şey yüklemeden önce Claude Code'un bir VPS üzerinde güvenli şekilde nasıl çalıştırılacağını okuyun ve harici bir servisle iletişim kuran bir eklenti yüklemeden önce kimlik bilgilerinin bir ajandan nasıl uzak tutulacağını inceleyin. Diğer araçlar da aynı kiralanmış sunucu üzerinde aynı engellere takılır; bu nedenle yüklemeye değer DeepSeek Harness eklentileri, yeni yetenekler eklemekten ziyade harcama limitleri, araç izin kuralları ve enjeksiyon taraması gibi güvenlik odaklıdır.

Bazı koruma mekanizmaları mevcuttur ve hangilerinin ne işe yaradığını bilmek faydalıdır. Proje kapsamlı bir eklenti, sizden ziyade depodan (repository) gelir; bu nedenle yalnızca çalışma alanına güvendiğinizde yüklenir, MCP sunucuları yine de sunucu bazında onay gerektirir, LSP sunucuları bu güveni bekler ve arka plan izleyicileri hiç yüklenmez. Eklenti ile gelen ajanların kanca, MCP sunucusu veya izin modu tanımlamasına izin verilmez. Pazar yeri eklentileri önbelleğe kopyalanırken pazar yeri dışını işaret eden sembolik bağlantılar (symlinks) atlanır; böylece bir eklenti, ana makinedeki rastgele dosyaları çekemez.

Bunların hiçbiri, yüklediğiniz şeyi incelemenin yerini tutmaz. Will install listesini kontrol edin, kaynak kodunu açıp okuyabildiğiniz eklentileri tercih edin, ekibinizin eklentilerini kontrolünüz altındaki bir pazar yeri deposunda tutun ve kendi yazdığınız her şey üzerinde claude plugin validate çalıştırın.

FAQ

Claude Code eklentileri ek ücret gerektirir mi?

Hayır. Eklenti sistemi, pazar yeri ekleme veya eklenti yükleme için herhangi bir ücret alınmaz. Maliyet, diğer tüm bağlamlarda olduğu gibi planınız veya API kullanımınız üzerinden faturalandırılan token tüketimidir. Bir eklenti, her adımda kalıcı bağlam ekler, becerilerinden veya aracılarından biri çağrıldığında daha fazla bağlam ekler ve araçları istem öneki (prompt prefix) içine yüklenen bir MCP sunucusu sağlıyorsa, önbelleğe alınmamış pahalı bir işleme neden olabilir. /plugin detay görünümü, yükleme yapmadan önce bir Context cost tahmini sunar.

Eklenti ile beceri (skill) arasındaki fark nedir?

Beceri, tek bir talimat birimidir. Eklenti ise; becerileri, aracıları, kancaları (hooks), MCP sunucularını, LSP sunucularını ve izleyicileri içeren; bir isme, sürüme ve yüklenebileceği bir pazar yerine sahip bir pakettir. Sadece sizin ve mevcut projeniz için geçerli olan durumlarda .claude/ içinde bağımsız bir beceri yazın. Ponytail, aracıyı çalışan en küçük değişikliğe yönlendirir gibi tek amaçlı bir beceri, bunun en net örneğidir: ekibiniz de isteyene kadar içinde tek bir kural bulunan tek bir dosya yeterlidir. Başkalarının da ihtiyacı olduğunda ve zaman içinde güncellenmesi gerektiğinde onu bir eklentiye dönüştürün. Eklenti becerileri isim uzaylıdır (namespaced), bu nedenle bir eklenti içindeki beceri /skill-name yerine /plugin-name:skill-name olarak çağrılır.

Eklentim yüklendi ancak becerileri görünmüyor. Sorun nedir?

Öncelikle yükleme özetini kontrol edin. Eğer Run /reload-plugins to activate. mesajı göründüyse bileşenler henüz yüklenmemiştir; yeniden yükleme işlemi konuşmanın tekrar okunacağı konusunda uyarı veriyorsa, işlemi /reload-plugins --force olarak yeniden çalıştırın. Yüklendiği halde hiçbir şey görünmüyorsa, /plugin kısmını açın ve Errors sekmesini okuyun. En yaygın yapısal hata; skills/, agents/ veya hooks/ dosyalarını, Claude Code'un onları aramadığı .claude-plugin/ dizininin içine yerleştirmektir. Eklenti becerilerinin isim uzaylı olduğunu unutmayın; bu nedenle /help içindeki Custom commands sekmesinde /plugin-name:skill-name ifadesini arıyor olmalısınız. Son çare olarak rm -rf ~/.claude/plugins/cache komutunu kullanın, yeniden başlatın ve tekrar yükleyin.

Etkileşimli panel olmadan eklenti yükleyebilir miyim?

Evet. --scope project veya --scope local bayraklarını kullanmadığınız sürece kullanıcı kapsamına yükleme yapan claude plugin install name@marketplace kabuk komutunu kullanın. Bu komut; betiklerde, imajlarda ve /plugin panelinin kullanılamadığı etkileşimli olmayan ortamlarda çalışır. Bir oturumun dışında çalıştığı için, halihazırda açık olan bir oturumda eklentinin etkili olması için /reload-plugins komutu gereklidir.

GitHub'da bulduğum bir pazar yerinden eklenti yüklemek güvenli mi?

Buna, o deponun yükleme betiğini kendi kullanıcınızla çalıştırıyormuşsunuz gibi yaklaşın; çünkü yapılan işlem buna oldukça yakındır. Bir eklenti; kancalar aracılığıyla kabuk komutları çalıştırabilir, Bash aracının PATH dizinine çalıştırılabilir dosyalar ekleyebilir ve MCP sunucuları başlatabilir; tüm bunları sizin kullanıcı yetkilerinizle yapar. Anthropic, üçüncü taraf eklenti içeriklerini kontrol etmez veya doğrulamaz. Yalnızca okuyabildiğiniz kaynaklardan yükleme yapın, onaylamadan önce Will install listesini inceleyin ve sunucularda dizüstü bilgisayarlara göre daha katı olun; çünkü sunucudaki hesap genellikle çalınmaya değer anahtarlar ve token'lar barındırır.