finestructure-ai/claude-plugin'in içi: yedi dosyada bir Claude Code eklentisi

Deponun tamamı yedi dosya

Klonlayın, dosya ağacı tek ekrana sığıyor:

.claude-plugin/
  plugin.json        686 B
  marketplace.json   507 B
commands/
  deploy.md          3.3 KB
  fs-domain.md       905 B
  fs-status.md       741 B
skills/
  fine-structure/
    SKILL.md         4.0 KB
LICENSE              MIT
README.md            2.3 KB

package.json yok, kilit dosyası yok, CI yok, dist yok. Hiçbir şey derlenmiyor ya da paketlenmiyor ve bu deponun derlemesi başarısız olabilecek bir sürümü yok. Bir araç zinciri gerektirdiğini varsaydığınız için eklenti yazmayı erteliyorsanız, düzeltme şu: biçim, bir dizin kuralı artı iki JSON dosyası, gerisi düz yazı.

plugin.json bir işaretçidir, program değil

Manifest, alışıldık kimlik alanlarını taşıyor (name, sürüm 0.1.0, description, author, homepage, repository, license, keywords) ve ardından bütün ilginç işi yapan tek bir blok geliyor:

"mcpServers": {
  "finestructure": {
    "type": "http",
    "url": "https://finestructure.ai/api/mcp"
  }
}

İki anahtar. command yok, args yok, env yok. Bunu çoğu MCP yapılandırmasının aldığı biçimle karşılaştırın: yerel bir süreç (npx, uvx, bir ikili dosyanın yolu), bir argüman listesi ve API anahtarını tutan bir env haritası. Bunun yerine streamable HTTP uç noktası bildirmek sunucuyu kullanıcının makinesinden çıkarıyor; 105 aracın (skill dosyasının verdiği sayı) 686 baytlık bir manifestin arkasında durmasının nedeni de bu. Kullanıcının Node ya da Python sürümüyle ilgili hiçbir şey kurulumu bozamaz ve sunucu tarafındaki değişiklikler yeni bir eklenti sürümü çıkmadan ulaşır. Bedeli yeniden üretilebilirlik: araç yüzeyini istemci tarafında sabitleyemezsiniz.

marketplace.json depoyu kendi dağıtım kanalına çeviriyor

Claude Code eklentileri bir paket kayıt defterinden değil marketplace'lerden kurar ve bir marketplace, eklentileri kaynak yoluyla birlikte listeleyen bir JSON dosyasından ibarettir. .claude-plugin içindeki ikinci dosya tam olarak bunu yapıyor ve tek eklenti girdisinde "source": "./" yazıyor. Depo aynı anda hem eklentinin kendisi hem de onu sunan marketplace, dolayısıyla yayımlamak herkese açık bir git push demek:

/plugin marketplace add finestructure-ai/claude-plugin
/plugin install finestructure@finestructure

İkinci satırdaki iki özdeş belirteç, marketplace adındaki eklenti adıdır; ikisi de finestructure diye adlandırıldığı için çakışıyorlar. Bu düzeni kopyalarsanız onlara farklı adlar verin. Kurulum yönergeleri netleşir ve sonradan ikinci bir eklenti ekleyecek yeriniz kalır.

Komutlar, frontmatter taşıyan istem şablonlarıdır

commands/ dizinindeki her dosya, YAML frontmatter artı düz yazıdır. deploy.md bir description ve bir argument-hint bildiriyor, yani kullanıcının seçicide gördüğü iki dizeyi, ardından numaralı bir karar ağacı seriyor: proje kökünde app_id tutan bir .finestructure.json var mı diye bak, yoksa list_apps'i çağır ve ad eşleşmesi ara, o da yoksa bunu ilk dağıtım say ve uygulama adı olarak $ARGUMENTS kullan. fs-status.md 741 bayt ve bir CLI alt komutunun işini görüyor: uygulamayı çöz, get_app_status, get_app_links ve get_errors'ı çağır, özetle. fs-domain.md ise sırasıyla add_custom_domain, get_domain_verification, check_domain_verification, get_domain_ssl_status ve set_primary_domain adımlarından geçiyor.

Tasarımın püf noktası şu: bu dosyaların hiçbiri hiçbir şeyi çağırmıyor. Araçları adlandırıyor, bir sıra sabitliyor ve bir adım başarısız olduğunda ne yapılacağını anlatıyorlar. Yürütme, model MCP araçlarını çağırdığında gerçekleşiyor. Eğik çizgi komutu, sürüm denetimine işlenmiş bir istemdir; dolayısıyla birini gözden geçirmek mantığın doğru olup olmadığını değil, yönergenin belirsiz olup olmadığını sormaktır.

En iyi satırlar olumsuz olanlar. deploy.md, kullanıcı açıkça istemedikçe silme araçlarını yasaklıyor. fs-domain.md, DNS yayılmasının dakikalar ile saatler sürdüğünü belirtiyor ve doğrulama döngüsüne girmek yerine daha sonra yeniden denemeyi önermeyi söylüyor. Bu, cümlelerle yazılmış bir yeniden deneme politikası ve korkuluk setidir; saf eklentilerin atladığı şey de tam olarak budur.

skill ile command: çekme ile itme

skills/fine-structure/SKILL.md iki frontmatter alanı taşıyor, name ve description, ve description bir özetten çok tetikleme koşulu gibi okunuyor: kullanıcı bir uygulama dağıtmak, oluşturmak veya güncellemek, bir alan adı bağlamak, veri ya da gizli anahtar yönetmek istediğinde kullanılsın. Bu ifade bilinçli. Bir komut, onu bir insan yazdığı için çalışır. Bir skill ise model açıklamayı olan bitenle eşleştirdiği için çalışır.

İçerik ayrımı da bunu izliyor. SKILL.md bir görev listesi değil, zihinsel bir model: burada uygulama nedir (JSX sayfaları, paylaşılan bileşenler, varlık şemaları, keyfi sunucu kodu yok), varlıklar nedir, hangi işlemler kredi harcar. Sonra araç zincirleri hâlinde iş akışları: get_app_files, read_app_file, write_app_file, validate_app ve publish_app sırası, çok dosyalı düzenlemeler için değişiklik kümeleriyle birlikte. Sonra da bayt başına en ağır basan kısım, yani hata anlambilimi: kimlik doğrulama hataları yeniden bağlanmak, kredi hataları bakiye yüklemek demektir ve ikisi de yeniden denenebilir değildir. Bu bilgiden yoksun bir ajan, yeniden denenmemesi gereken bir hatayı döngü içinde yeniden dener ve sayaçla çalışan bir platformda bu döngünün bir fiyatı vardır.

Kendi eklentiniz için kural buradan temiz biçimde çıkıyor. Bir komut dosyası ürününüzün ne olduğunu anlatıyorsa, o paragrafın yeri skill'dir. Komutlar yordam olarak kalır.

Manifestte hiç sır olmamasının nedeni OAuth

Uç nokta, dinamik istemci kaydıyla OAuth 2.1 üzerinden kimlik doğruluyor; bu yüzden ilk araç çağrısı tarayıcıda bir onay sayfası açıyor ve belirteç depoya değil, Claude Code'un kimlik bilgisi deposuna iniyor. Çatallamak yapı gereği güvenli, iptal her makineye ulaşması gereken bir yapılandırma düzenlemesi değil sunucu tarafında bir işlem ve kimseden uzun ömürlü bir anahtarı, herkese açık bir diff'e tek bir dikkatsiz commit uzaklıktaki dosyaya yapıştırması istenmiyor.

Kendi eklentiniz için nelerin kopyalanacağı

Kabaca kurulum sırasına göre somut ipuçları:

• name, version ve description tutan bir .claude-plugin/plugin.json ile başlayın. Geri kalan her şey isteğe bağlı.
• Barındırılan bir MCP uç noktası işletiyorsanız, yerel bir komut yerine bir url ile "type": "http" bildirin. Bu, kullanıcının çalışma zamanını destek yüzeyinizden siler.
• Tek eklentiniz olduğu sürece marketplace.json'ı aynı depoda "source": "./" ile yayınlayın ve ona eklentiden farklı bir ad verin.
• Her komuta frontmatter içinde bir description ve bir argument-hint verin; bunları bu ne yapar ve arkasına ne yazarım sorularının yanıtı gibi yazın.
• Konumsal bir sözdizimi icat etmek yerine $ARGUMENTS kullanın. Ayrıştırıcı yok, yalnızca yerine koyma var.
• Komut gövdelerini, araçları açıkça adlandıran karar ağaçları olarak yazın. "Yapılandırma dosyası varsa app_id'yi oku, yoksa list_apps'i çağır" cümlesi, niyet anlatan bir paragraftan daha iyi dayanır.
• Hata anlambilimini yazıya dökün: hangi hatalar kesin, hangileri yeniden denenebilir, yeniden denemek yerine ne söylenmeli.
• Yıkıcı araçlarınızı düz yazıda adlandırın ve istenmedikçe yasaklayın.
• Alan modelini SKILL.md içinde, yordamı komutta tutun. İkisi arasındaki yineleme kötü bir işarettir.
• Kimseyi main'e yönlendirmeden önce /plugin marketplace add ile yerel bir yola ya da kendi çatalınıza karşı test edin.

Pürüzlü kenarlar

Dürüstçe üç tane, hiçbiri ölümcül değil. Her şey İngilizce ve biçim bunu düzeltmek için bir kanca sunmuyor: frontmatter'da locale anahtarı yok, dolayısıyla yerelleştirme ya komut dosyalarını çoğaltmak ya da uyumsuzluğu kabul etmek anlamına geliyor.

API anahtarı istemeyen hikâyenin bir yıldızı var. SKILL.md, medya üretim araçlarının OAuth bağlantısının dışında kaldığını ve platformun Studio'sunda oluşturulup bearer başlığıyla gönderilen, medya kapsamlarına sahip statik bir MCP belirteci gerektirdiğini kabul ediyor. Eklenti bunu iyi yönetiyor, modele duvara toslayarak yeniden denemek yerine eksikliği açıklamasını söylüyor; yine de bu, satış noktası tek bir yola sahip olmak olan bir tasarıma cıvatalanmış ikinci bir kimlik doğrulama yolu.

Bir de sürüm 0.1.0; changelog, test ve CI yok. Markdown için bu savunulabilir, gerçi bir pre-commit hook'undaki JSON şema denetimi, kurulumları gerçekten bozan tek hata sınıfını, yani bozuk manifesti yakalardı. Dizin başvurusu bu satırlar yazılırken inceleme aşamasında, o yüzden şimdilik depo referansıyla kuruluyor.

Önce üç komut dosyasını, sonra SKILL.md'yi, sonra iki JSON dosyasını okuyun. Bu sırayla biçim kendini açıklıyor: markdown neyin hangi sırayla olması gerektiğine karar veriyor, MCP sunucusu gerçekte neyin çalıştığına karar veriyor, manifest de ikisi arasındaki ince dikiş.