Plugin Marketplace Claude Code: Menulis marketplace.json

Saya menerbitkan sebuah marketplace internal, mendorong perbaikan ke sebuah plugin, menyuruh tim memperbarui, lalu melihat tiga orang tetap melaporkan perilaku lama. Tidak ada yang rusak. Saya cuma lupa menaruh version di satu entri dan menyetelnya di entri lain, dan keduanya berperilaku berlawanan — jenis detail yang Anda ketahui dari rekan kerja ketimbang dari stack trace.

Tulisan ini sisi penulisan dari plugin: manifest-nya dan tiap field yang penting, tujuh tipe source dan kapan masing-masing jadi jawaban yang benar, bagaimana versioning sebenarnya menentukan siapa yang menerima pembaruan Anda, renames dan strict mode, memvalidasi sebelum menerbitkan, membawa marketplace-nya ke mesin sebuah tim tanpa menyuruh siapa pun mengetik perintah, serta mengunci marketplace mana yang boleh dipakai sebuah organisasi sama sekali.

Manifest-nya kecil, dan tiga field wajib

Hanya name, owner dan plugins yang wajib, dan tiap entri plugin cuma butuh name dan source. Sisanya — displayName, description, version, author, license, keywords, category — ada supaya entri itu terbaca enak di tab Discover dan supaya Anda bisa mengendalikan pembaruan. Ini file yang realistis, bukan yang minimal:

// .claude-plugin/marketplace.json  — at the repository root
{
  "name": "acme-tools",
  "owner": { "name": "Acme Platform", "email": "[email protected]" },
  "description": "Internal tooling for Acme engineers",
  "metadata": { "pluginRoot": "./plugins" },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "formatter",          // bare name, needs pluginRoot
      "displayName": "Code Formatter",
      "version": "2.1.0",             // bump this on EVERY release
      "author": { "name": "Acme DevTools" },
      "license": "MIT",
      "category": "productivity"
    },
    {
      "name": "deploy-kit",
      "source": {
        "source": "github",
        "repo": "acme-corp/deploy-plugin",
        "ref": "v2.0.0",
        "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
      }
    }
  ],
  "renames": { "formatter": "code-formatter", "legacy-linter": null }
}

Dua detail gampang terlewat. Path relatif diselesaikan dari akar marketplace, bukan dari direktori .claude-plugin yang memuat file-nya. Dan sekumpulan nama marketplace dicadangkan untuk Anthropic — claude-plugins-official, anthropic-plugins, agent-skills dan belasan lainnya — berikut nama yang meniru mereka, jadi pilih sesuatu yang jelas milik Anda.

Tujuh tipe source, dan yang kemungkinan Anda butuhkan

Field source menentukan dari mana plugin-nya diambil, dan pilihannya berkonsekuensi lebih besar dari kelihatannya. Path relatif menaruh semuanya dalam satu repository dan adalah hal paling sederhana yang bekerja. Source github atau url membuat sebuah plugin bisa tinggal di repository-nya sendiri dengan siklus rilisnya sendiri. Sisanya ada untuk situasi khusus.

Memilih tipe source:

Version adalah sakelar pembaruan, dan ia bekerja dua arah

Ini field yang layak dipahami benar, karena kedua mode gagalnya tampak seperti hal lain. Apa yang dilakukan version tergantung apakah Anda menyetelnya dan tipe source apa yang Anda pakai:

• Setel version, dan plugin-nya terkunci ke string itu. Pengguna mendapat pembaruan hanya ketika string-nya berubah — jadi mendorong perbaikan tanpa menaikkannya meninggalkan semua orang di salinan cache.
• Hilangkan version di source git, dan versinya diturunkan dari commit yang terselesaikan. Tiap commit yang Anda dorong jadi pembaruan buat semua orang, termasuk yang Anda maksud sebagai pekerjaan setengah jadi.
• Source command selalu menyertakan hash keluaran perintahnya, dan source archive memakai sha256 kalau Anda menyetelnya, jadi version eksplisit tidak mengunci keduanya.

Renames dan strict mode, supaya Anda boleh berubah pikiran

Mengganti nama plugin biasanya menelantarkan semua orang yang memasang nama lamanya. Objek renames memperbaikinya: petakan nama lama ke nama baru dan Claude Code mengikuti rantainya otomatis, atau petakan ke null untuk menandai plugin itu dihapus. Ia butuh v2.1.193 atau lebih baru, dan biayanya satu baris, jadi tambahkan sejak pertama kali Anda mengganti nama apa pun ketimbang menjanjikan diri akan ingat nanti.

Strict mode menentukan siapa pemilik daftar komponennya. Dibiarkan di bawaannya, true, plugin.json milik plugin itu sendiri adalah otoritasnya dan entri marketplace Anda boleh menambahkan komponen ekstra di atasnya. Setel false dan entri marketplace-nya menjadi seluruh definisinya, yang berbenturan kalau plugin.json juga mendeklarasikan komponen. Pakai false hanya ketika Anda operator yang sengaja mengendalikan apa yang diekspos plugin pihak ketiga.

Validasi sebelum menerbitkan

Ada validator sungguhan, dan ia menangkap error yang selain itu tak terlihat sampai seorang pengguna melapor: sintaks, nama plugin ganda, path source yang melintas keluar repository, file plugin.json lokal yang tidak sah, dan ketidakcocokan versi antara entri dan plugin-nya. Field yang tidak dikenal kembali sebagai peringatan bukan error, dan nama field yang nyaris benar dapat saran — pakai strict kalau Anda mau peringatan menggagalkan run-nya.

# Add a marketplace — GitHub shorthand, a git URL, or a path
claude plugin marketplace add acme-corp/claude-plugins
claude plugin marketplace add acme-corp/[email protected]
claude plugin marketplace add https://gitlab.com/team/plugins.git
claude plugin marketplace add ./my-marketplace --scope project

claude plugin marketplace list [--json]
claude plugin marketplace update [name]
claude plugin marketplace remove <name> [--scope <scope>]

# Validate BEFORE you publish. This is the whole quality gate.
claude plugin validate .
claude plugin validate ./my-plugin --strict   # warnings become errors

# What a user actually runs
/plugin install code-formatter@acme-tools
/plugin install code-formatter@acme-tools --scope project

Menggulirkannya tanpa menyuruh siapa pun mengetik perintah

Jalur yang bisa diskalakan adalah settings, bukan instruksi. Taruh extraKnownMarketplaces di file settings proyek dan marketplace-nya tiba bersama repository-nya begitu foldernya dipercaya; tambahkan enabledPlugins dan plugin-nya tiba bersamanya. Catat satu perubahan v2.1.195 yang layak diantisipasi: menambahkan marketplace lewat jalan ini tidak lagi memasang plugin yang berasal dari source eksternal, jadi seorang anggota melihat perintah install-nya, bukan plugin yang jalan.

// .claude/settings.json — the marketplace arrives with the repo
{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/claude-plugins" },
      "autoUpdate": true          // managed settings only
    }
  },
  "enabledPlugins": { "code-formatter@acme-tools": true }
}

// Managed settings — an allowlist of what may be added at all.
{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/*" },
    { "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
  ]
}
// undefined = no restriction.  []  = total lockdown, official
// marketplace included.

Menentukan apa yang boleh ditambahkan sebuah organisasi

Untuk lingkungan terkelola, strictKnownMarketplaces adalah allowlist marketplace yang boleh ditambahkan pengguna. Biarkan tidak terdefinisi dan tidak ada batasan; setel ke array kosong dan Anda mendapat penguncian total, marketplace resmi termasuk. Entri-nya mencocokkan repository GitHub, termasuk wildcard pemilik, URL persis, atau ekspresi reguler terhadap host atau path filesystem.

Mulai dari satu repository, source path relatif, dan version eksplisit di tiap entri, karena kombinasi itu paling sedikit kejutannya. Jalankan validator-nya di dalam pemeriksaan yang sudah dipunyai repository itu, supaya manifest rusak tidak pernah sampai ke rekan kerja. Dan tulis entri renames pada kali pertama Anda mengganti nama sebuah plugin, bukan kali kedua, ketika seseorang bilang instalasinya hilang.