Plugin'ler

Bu bölüm yeniden kullanılabilir Claude uzantıları oluşturan ileri düzey kullanıcılar içindir. Çoğu okuyucu, ekibe veya topluluğa Claude yapılandırmaları dağıtmıyorsa bu bölümü atlayabilir. Tek başınıza çalışıyorsanız veya kendiniz için yalnızca bir özel agent’a ihtiyacınız varsa, .claude/agents/ dosyalarını kullanmaya devam edin.

Ekibiniz için harika bir hook, özel agent ve MCP yapılandırma seti oluşturdunuz. Şimdi bunları dosyaları manuel olarak kopyalamak veya doğru dizin yapısını çözmek zorunda kalmaması gereken 20 başka geliştiriciyle paylaşmanız gerekiyor. Plugin’ler her şeyi tek bir dağıtılabilir birim halinde paketler.

Plugin’ler; agent’ları, hook’ları ve MCP sunucularını bir araya getiren paketlenmiş yapılandırmalardır. Şöyle düşünün: MCP araç ekler. Özel agent’lar kişilik ekler. Hook’lar davranış ekler. Plugin’ler üçünü de tek bir dağıtılabilir birimde bir araya getirir. Bir plugin, .claude-plugin/plugin.json bildirimi olan bir dizindir — geri kalan her şey isteğe bağlıdır. İsim alanı sistemi çakışmaları önler, böylece birden fazla plugin birbirine müdahale etmeden bir arada var olabilir.

Hızlı karar: sadece araçlara mı ihtiyacınız var? MCP sunucusu. Sadece bir kişiliğe mi? Agent dosyası. Sadece yaşam döngüsü hook’larına mı? hooks.json. Plugin’ler, bunlardan ikisi veya daha fazlasını tek bir paket olarak bir araya getirmeniz gerektiğinde kullanılır.

Plugin Yapısı

Her plugin tek bir zorunlu dosyayla başlar: .claude-plugin/plugin.json. Dizin düzeninin geri kalanı standart .claude/ proje yapısını yansıtır, ancak plugin kökünde yaşar — .claude-plugin/ içinde değil.

Örnek: bir ‘secure-dev’ plugin’i — sandbox’lanmış agent yapılandırması, dosya sistemi yazmalarını engelleyen PreToolUse hook’u ve yalnızca onaylı API’ler için MCP sunucusu:

secure-dev/
├── .claude-plugin/
│   └── plugin.json          # Zorunlu: bildirim (bu dizindeki TEK dosya)
├── agents/
│   └── sandbox.md           # Araç kısıtlamalı salt okunur agent
├── hooks/
│   └── hooks.json           # Edit/Write'ı engelleyen PreToolUse hook'u
├── .mcp.json                # Yalnızca onaylı API sunucusu
└── skills/
    └── audit/
        └── SKILL.md         # Güvenlik denetimi iş akışı

Bildirim tek zorunlu dosyadır. İşte minimal bir plugin.json:

{
  "name": "my-plugin",
  "description": "A description of what this plugin does",
  "version": "1.0.0",
  "author": { "name": "Your Name" },
  "homepage": "https://github.com/your-org/my-plugin",
  "repository": "https://github.com/your-org/my-plugin",
  "license": "MIT"
}

name alanı isim alanını belirler. "my-plugin" adlı bir plugin, tüm becerilerini /my-plugin:skill-name olarak dışa açar.

Bildirim Alanları

Komutlar ve Beceriler

Hem komutlar hem de beceriler bir plugin’de yaşar, ancak farklı amaçlara hizmet eder ve farklı kuralları takip eder.

Kurulum ve Yönetim

Plugin’leri bir Claude oturumu içinden yönetmek için /plugin eğik çizgi komut ailesini kullanın.

Geliştirme oturumu sırasında plugin dosyalarını düzenledikten sonra, değişikliklerinizi almak için /reload-plugins çalıştırın. CLI, plugin dosyalarını değişiklikler için otomatik olarak izlemez.

İsim Alanları

Plugin becerileri her zaman plugin adıyla önek alır, iki nokta ile ayrılır. Bu, adlandırma çakışmalarını önler — iki plugin çakışma olmadan lint adında bir beceri tanımlayabilir.

İsim alanından vazgeçemezsiniz. Plugin becerileri asla yalın /skill-name olarak kullanılamaz — önek zorunludur.

Bağımsız ve Plugin Karşılaştırması

.claude/skills/ içindeki bağımsız bir beceri ile plugin arasında seçim, beceriye kimin ihtiyaç duyduğuna ve nasıl dağıtılacağına bağlıdır.

Yerel Geliştirme

Geliştirme sırasında, plugin’inizi kurmadan yerel bir dizinden yüklemek için --plugin-dir bayrağını kullanın:

Bayrağı tekrarlayarak aynı anda birden fazla plugin yükleyebilirsiniz:

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

Yerel bir plugin ve pazar yeri plugin’i aynı adı paylaştığında, yerel --plugin-dir versiyonu öncelik kazanır. Ancak, organizasyon ayarlarından gelen yönetilen zorunlu etkin plugin’ler her zaman --plugin-dir’i geçersiz kılar.

Plugin Hook’ları

Plugin’ler, plugin kökündeki hooks/hooks.json dosyasında hook tanımlayabilir. Kritik bir güvenlik kısıtlaması vardır: plugin hook’ları yalnızca http ve prompt işleyici türlerini destekler. command ve agent işleyici türleri, üçüncü taraf plugin’lerden rastgele kod yürütmeyi önlemek için engellenmiştir.

{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "prompt",
          "prompt": "Check if this bash command is safe: $ARGUMENTS",
          "timeout": 15
        }
      ]
    }
  ]
}

Hem plugin hem de proje hook tanımladığında, ikisi de çalışır — proje hook’ları önce yürütülür.

Plugin Önceliği

Yapılandırma Çözümleme Matrisi

Farklı yapılandırma türleri, alt dizinlerde çalışırken farklı kalıtım kurallarına sahiptir:

Monorepo ekipleri için temel çıkarımlar:

• Kök düzeyindeki CLAUDE.md her alt klasör oturumunda vazgeçilemez şekilde görünür. Kök düzeyindeki talimatları genel tutun.
• Kök düzeyindeki .mcp.json sunucularını tüm alt klasör oturumlarıyla paylaşır. İzolasyona ihtiyaç duyan alt klasörlerde --strict-mcp-config kullanın.
• Üst dizin hook’ları ve izin reddi kuralları alt klasör oturumlarına yayılmaz. Her alt klasör kendi güvenlik hook’larını tanımlamalıdır.
• Boş bir alt yapılandırma, üst kalıtımı gölgelemez veya engellemez. CLAUDE.md veya .mcp.json için gölgeleme mekanizması yoktur.