Jawaban singkat untuk pertanyaan yang paling sering diajukan pembaca tentang topik ini.
Marketplace adalah satu file JSON yang mendistribusikan plugin Claude Code ke tim. Ini source-nya, jebakan versinya, dan jalur rollout-nya.
Matthews Wong
Software Engineer
Ringkasan Utama
Plugin marketplace Claude Code adalah satu file, .claude-plugin/marketplace.json, di akar sebuah repository. Ia butuh name, owner, dan daftar plugin, masing-masing dengan source. Satu keputusan yang paling banyak melahirkan pekerjaan dukungan adalah field version: setel dan naikkan di tiap rilis, atau pengguna Anda diam-diam tetap menjalankan salinan cache.
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.
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": "tools@acme.com" },
"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.
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:
| Source | Kapan ia jawaban yang benar |
|---|---|
| Path relatif | Plugin tinggal di repository yang sama dengan marketplace-nya. Harus diawali titik-garis miring, kecuali Anda menyetel metadata.pluginRoot dan memakai nama direktori polos |
| github atau url | Plugin-nya punya repository sendiri. ref opsional mengunci branch atau tag; sha opsional mengunci commit 40 karakter persis |
| git-subdir | Plugin-nya sebuah direktori di dalam monorepo besar. Sparse clone, jadi Anda tidak menarik seluruhnya |
| npm | Anda memang sudah menerbitkan ke sebuah registry. Menerima package, rentang version opsional, dan URL registry kustom |
| archive atau command | Sebuah zip lewat HTTPS dengan sha256 opsional untuk integritas, atau perintah lokal yang mencetak direktori plugin. Keduanya untuk sistem build, bukan untuk manusia |
Dua batasan menggigit dalam praktik. Marketplace yang didistribusikan sebagai URL marketplace.json polos sama sekali tidak bisa menyelesaikan path relatif, jadi file yang bekerja dari git clone rusak ketika Anda menaruhnya sebagai file biasa — pakai tipe source lain. Dan archive harus HTTPS dari ujung ke ujung, termasuk setiap redirect, dengan batas 256 MiB.
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:
Dua kanal rilis tidak mahal dijalankan: terbitkan plugin yang sama dua kali, di marketplace stable yang dikunci ke branch stable dan marketplace latest yang dikunci ke latest. Yang mau hal baru menambahkan marketplace kedua; sisanya tidak pernah sadar Anda merilis. Itu jauh lebih ringan daripada mencoba menyandikan toleransi risiko ke dalam rentang versi.
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.
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/claude-plugins@v2.0
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 projectJalur 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.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.
Dua tuas kecil layak diketahui. Entri marketplace bisa membawa objek relevance, dan ketika administrator meng-allowlist marketplace-nya lewat managed setting pluginSuggestionMarketplaces, plugin yang cocok disematkan di puncak tab Discover sebagai disarankan untuk direktori ini. Dan defaultEnabled disetel false membuat Anda bisa mengirim plugin yang terpasang tanpa menyalakan dirinya sendiri, yang merupakan default sopan untuk apa pun yang memakan biaya atau memanggil layanan eksternal.
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.
Sumber & bacaan lanjutan