Referensi Marketplace

Referensi lengkap untuk field marketplace.json, entri plugin, dan objek sumber plugin dan marketplace, dengan tempat masing-masing valid.

marketplace.json adalah file yang mendefinisikan marketplace plugin. File ini berisi nama marketplace, pemiliknya, dan satu entri per plugin. Sumber plugin setiap entri mengatakan di mana Claude Code mengambil plugin tersebut.

Sumber marketplace adalah objek terpisah yang mengatakan di mana Claude Code mengambil file marketplace itu sendiri. Anda menulis satu di pengaturan, atau Claude Code membangunnya ketika Anda menjalankan claude plugin marketplace add.

Referensi ini untuk pengelola marketplace yang membutuhkan nama atau nilai field yang tepat, dan untuk administrator yang perlu mengetahui nilai source mana yang valid dalam extraKnownMarketplaces, strictKnownMarketplaces, dan blockedMarketplaces.

Temukan bagian untuk apa yang Anda tulis atau baca:

• File marketplace: Field tingkat atas dan Entri plugin
• source entri: Sumber plugin
• Objek source di pengaturan: Sumber marketplace
• Output dari claude plugin validate <path>: Pesan validasi, yang memetakan setiap pesan ke field yang disebutnya

File marketplace

Simpan file marketplace di .claude-plugin/marketplace.json di direktori marketplace Anda. Jika Anda menyimpan file di tempat lain di repositori, pengguna harus mendeklarasikan marketplace di extraKnownMarketplaces dengan path diatur pada sumbernya, karena claude plugin marketplace add tidak memiliki opsi untuk itu.

Direktori yang berisi .claude-plugin/ disebut akar marketplace, dan setiap sumber plugin relatif diselesaikan darinya, bukan dari .claude-plugin/.

Setiap pengguna mendaftarkan satu marketplace per name, jadi pengguna tidak dapat memiliki dua marketplace dengan nama yang sama terdaftar sekaligus.

Claude Code mengabaikan kunci tingkat atas yang tidak dikenal atau kunci entri plugin daripada menolaknya, jadi typo dimuat diam-diam. claude plugin validate melaporkan setiap kunci yang tidak dikenal sebagai peringatan.

Nama yang dicadangkan

Anda tidak dapat memberikan marketplace Anda salah satu nama berikut:

• Nama marketplace resmi: claude-code-marketplace, claude-code-plugins, claude-plugins-official, anthropic-marketplace, anthropic-plugins, agent-skills, anthropic-agent-skills, life-sciences, knowledge-work-plugins, claude-for-legal, claude-for-financial-services, financial-services-plugins, first-party-plugins, dan claude-tag-plugins. Dicadangkan kecuali marketplace berasal dari github atau git sumber marketplace di bawah github.com/anthropics/.
• Nama marketplace komunitas: claude-community, claude-plugins-community, dan healthcare. Dicadangkan di bawah aturan yang sama dengan nama resmi.
• Nama direktori plugin: anthropic-plugin-directory dan claude-plugin-directory. Dicadangkan di bawah aturan yang sama dengan nama resmi.
• Nama yang menyamar sebagai marketplace resmi: nama seperti official-claude-plugins atau claude-plugins-v2, dan nama apa pun yang berisi karakter non-ASCII. Kesalahannya adalah Marketplace name impersonates an official Anthropic/Claude marketplace. Karakter kontrol atau pemformatan bidirectional dalam nama juga melaporkan Marketplace name cannot contain control or bidirectional-formatting characters.
• Ejaan lain dari nama yang dicadangkan: nama yang berbeda dari nama yang dicadangkan hanya dengan titik di akhir, atau dengan simbol selain garis bawah sebagai pengganti tanda hubung, jadi claude.code.plugins dihitung sebagai claude-code-plugins. claude plugin validate menerima nama seperti itu; menambahkan marketplace gagal dengan is another spelling of "<reserved>", a reserved marketplace name, dan marketplace yang sudah terdaftar di bawah satu berhenti dimuat. Pemeriksaan ini memerlukan Claude Code v2.1.280 atau lebih baru.
• Nama yang Claude Code gunakan untuk plugin yang tidak berasal dari marketplace: inline untuk plugin yang dimuat dengan --plugin-dir, builtin untuk plugin bawaan, skills-dir untuk plugin yang dimuat otomatis dari .claude/skills/, dan synced untuk plugin yang disinkronkan dari akun claude.ai Anda. claude-plugin-test juga dicadangkan. skills-dir juga muncul sebagai {"source": "skills-dir"} dalam strictKnownMarketplaces dan blockedMarketplaces, dijelaskan di bawah Nilai sumber yang valid hanya dalam daftar kebijakan.
• npm, pip, uv, cargo, github, dan gh: dicadangkan dalam huruf apa pun. Pemeriksaan ini memerlukan Claude Code v2.1.275 atau lebih baru.
• Nama yang dimulai dengan claudeai-: dicadangkan untuk marketplace yang dihosting di claude.ai. claude plugin marketplace add menolak marketplace lain apa pun yang menggunakannya dengan Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai.

Field tingkat atas

Tabel mencantumkan setiap kunci yang Claude Code baca dari marketplace.json. name, owner, dan plugins diperlukan.

Entri plugin

Setiap objek dalam array plugins tingkat atas dari marketplace.json menamai plugin dan mengatakan di mana mengambilnya. name dan source diperlukan.

Entri juga menerima setiap field plugin.json, seperti description, version, author, commands, dan hooks. Untuk kapan field tersebut berlaku, lihat Bagaimana entri menggabungkan dengan plugin.json.

Tabel mencantumkan field entri sendiri dan field manifest yang maknanya berubah dalam entri.

Bagaimana entri menggabungkan dengan plugin.json

Field entri berlaku berbeda untuk plugin yang diambil yang memiliki .claude-plugin/plugin.json sendiri dan untuk yang tidak:

• Tidak ada plugin.json: entri adalah manifest terlepas dari strict. Setiap field manifest dalam entri berlaku, termasuk mcpServers, lspServers, userConfig, dan channels.
• plugin.json hadir: plugin.json adalah manifest. Mode ketat memutuskan apakah enam field komponen entri, commands, agents, skills, hooks, outputStyles, dan themes, digabungkan dengannya atau ditolak sebagai konflik. Entri mcpServers, lspServers, userConfig, dan channels tidak berlaku. Deklarasikan mereka di plugin.json.

Hooks dalam entri

Tulis entri hooks sebagai objek inline yang memetakan nama acara hook ke array matcher. Jika Anda menulis jalur file atau array sebagai gantinya, claude plugin validate melewatinya. Hook tersebut tidak pernah berjalan, dan Claude Code melaporkan kesalahan not yet supported in a marketplace entry untuk plugin. Letakkan hook berbasis file di hooks/hooks.json plugin sendiri atau plugin.json.

Field tampilan

Baik entri maupun plugin.json plugin sendiri dapat menetapkan field tampilan displayName, description, author, homepage, repository, license, dan keywords. Pengguna melihat nilai-nilai ini dalam daftar dan detail plugin, sebelum dan sesudah pemasangan:

• Untuk field yang Anda tetapkan pada entri, pengguna melihat nilai entri, bahkan ketika plugin.json menetapkan yang berbeda.
• Untuk field yang entri biarkan tidak diatur, pengguna melihat nilai plugin.json.

Sebelum pemasangan, Claude Code hanya dapat membaca plugin.json untuk entri dengan sumber jalur relatif, yang file pluginnya berada di dalam marketplace itu sendiri. Untuk entri dengan tipe sumber apa pun, pengguna hanya melihat field entri sendiri sampai mereka memasang plugin.

Mode ketat

strict memutuskan apa yang terjadi ketika plugin yang diambil memiliki plugin.json sendiri dan entri juga mendeklarasikan salah satu field komponen: commands, agents, skills, hooks, outputStyles, atau themes. Dengan strict: true, default, Claude Code menambahkan field komponen entri ke plugin.json, kecuali hooks, yang matcher-nya menggantikan manifest per acara. Dengan strict: false, entri yang mendeklarasikan field komponen apa pun adalah konflik, dan plugin gagal dimuat. Tabel menunjukkan setiap kombinasi strict, plugin.json, dan field komponen entri.

Sumber plugin

source entri plugin mengatakan di mana Claude Code mengambil satu plugin itu. Ini adalah string jalur relatif atau objek yang source key-nya sendiri menamai tipenya, jadi entri terlihat seperti "source": { "source": "github", "repo": "your-org/formatter" }.

Tabel mencantumkan setiap tipe sumber plugin dan field-nya.

Nama url dan github juga tipe sumber marketplace, di mana url berarti tautan langsung ke file marketplace.json daripada repositori git. git hanya ada sebagai sumber marketplace, dan npm ada sebagai keduanya. git-subdir, archive, dan command hanya ada sebagai sumber plugin.

Gunakan jalur relatif untuk plugin di subdirektori repositori marketplace itu sendiri. Gunakan git-subdir untuk subdirektori repositori lain.

Sumber github, url, dan git-subdir berbagi field ref dan sha:

• ref: cabang atau tag. Default ke cabang default repositori.
• sha: SHA commit 40-karakter lowercase penuh. Ketika Anda menetapkan baik ref maupun sha, Claude Code melakukan checkout sha. Di sebagian besar host git, termasuk GitHub, GitLab, dan Bitbucket, ini berarti pemasangan berhasil bahkan jika cabang atau tag yang dinamai oleh ref telah dihapus upstream, selama commit masih dapat dijangkau dari repositori. Beberapa server, seperti AWS CodeCommit, tidak mendukung pengambilan commit menurut SHA. Di server tersebut ref masih harus ada dan commit yang disematkan harus dapat dijangkau darinya.

Untuk cara setiap tipe diambil, di-cache, dan diversi, lihat Referensi pemuatan plugin.

Sumber plugin jalur relatif

Jalur diselesaikan dari akar marketplace. ./plugins/formatter adalah <root>/plugins/formatter meskipun file marketplace berada di <root>/.claude-plugin/.

Jalur yang berisi .. gagal validasi. Di macOS dan Linux, Claude Code menolak jalur entri yang berisi garis miring terbalik di mana pun setelah ./ awal, jadi tulis jalur dengan garis miring maju.

{ "name": "formatter", "source": "./plugins/formatter" }

Jalur relatif diselesaikan hanya ketika Claude Code memiliki file marketplace, jadi periksa tipe sumber marketplace:

• github, git, file, dan directory: Claude Code memiliki file marketplace.
• url: Claude Code hanya mengambil marketplace.json, jadi jalur relatif tidak dapat diselesaikan. Berikan setiap plugin sumber objek sebagai gantinya, seperti github atau git-subdir.
• settings: jalur relatif ditolak sepenuhnya.

Nama bare di bawah pluginRoot

Nama bare adalah nama direktori tunggal tanpa /, seperti "formatter". Untuk menulis nama bare daripada jalur ./, atur metadata.pluginRoot ke direktori yang mereka selesaikan di bawahnya. Dengan "pluginRoot": "./plugins", "source": "formatter" diselesaikan ke ./plugins/formatter. Memerlukan Claude Code v2.1.239 atau lebih baru.

metadata.pluginRoot memiliki batasan ini:

• Itu sendiri harus jalur relatif di dalam marketplace.
• Itu tidak berpengaruh pada sumber yang sudah dimulai dengan ./.
• Sumber yang berisi /, seperti team-a/formatter, bukan nama bare dan masih memerlukan awalan ./, bahkan ketika metadata.pluginRoot diatur.

Sumber plugin github

repo mengambil owner/repo. ref dan sha opsional.

{
  "name": "formatter",
  "source": {
    "source": "github",
    "repo": "your-org/formatter",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Sumber plugin url

url adalah URL git lengkap: https://, http://, file://, atau git@. Akhiran .git tidak diperlukan, jadi URL Azure DevOps dan AWS CodeCommit berfungsi seperti yang ditulis. Tipe ini tidak mengambil shorthand owner/repo.

{
  "name": "formatter",
  "source": {
    "source": "url",
    "url": "https://gitlab.example.com/your-group/formatter.git",
    "ref": "main"
  }
}

Sumber plugin git-subdir

url menerima URL git lengkap atau shorthand GitHub owner/repo. path adalah subdirektori yang menyimpan plugin, dan Claude Code hanya mengunduh subdirektori itu.

{
  "name": "formatter",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/your-org/monorepo.git",
    "path": "tools/formatter"
  }
}

Sumber plugin npm

Sumber npm mengambil field ini:

• package: nama paket, atau nama scoped seperti @your-org/formatter
• version: versi atau rentang
• registry: URL registry untuk paket yang bukan di registry default

Claude Code mengambil paket dengan klien npm Anda. Skrip install paket, seperti preinstall atau postinstall, tidak pernah berjalan, dan dependensinya tidak dipasang selama pengambilan. Jika paket memiliki lockfile yang didukung di samping package.json-nya, Claude Code memasang dependensi paket Node.js tersebut dalam langkah terpisah, juga dengan skrip dinonaktifkan.

{
  "name": "formatter",
  "source": {
    "source": "npm",
    "package": "@your-org/formatter",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

Sumber plugin archive

url harus menggunakan https:// dan tidak dapat menunjuk ke host loopback, link-local, atau cloud-metadata.

Akar plugin mungkin berada di atas zip atau satu direktori ke bawah.

sha256 adalah digest arsip sebagai 64 karakter hex, huruf besar atau kecil. Ketika Anda menetapkannya, Claude Code menolak unduhan yang tidak cocok.

{
  "name": "formatter",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/formatter-2.0.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

Sumber plugin command

Gunakan sumber command ketika alat yang dipasang di mesin pengguna menghasilkan direktori plugin, seperti IDE yang merender pluginnya untuk toolchain yang dipilih pengguna. Claude Code menjalankan perintah ketika pengguna memasang atau memperbarui plugin, dan lagi sekali per sesi, jadi pengguna mendapatkan output alat yang berubah tanpa memasang ulang.

Sumber command mengambil field ini:

• command: perintah shell yang mencetak jalur absolut direktori plugin sebagai satu baris dan keluar 0. Claude Code menunjukkan seluruh string kepada pengguna untuk ditinjau sebelum menjalankannya. Tulis sebagai ASCII yang dapat dicetak, paling banyak 500 karakter, tanpa run empat atau lebih spasi.
• timeout: bilangan bulat detik dari 1 hingga 600. Default ke 60.
• mode: copy, default, atau link. Lihat Mode copy dan mode link.

{
  "name": "formatter",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path",
    "timeout": 120
  }
}

Untuk cara pengguna menerima perintah, lihat Pasang dari shell Anda. Untuk apa yang pengguna lihat setelah Anda mengubahnya, lihat Ubah perintah sumber command. Administrator mematikan sumber command dengan disableCommandPluginSources.

Apa yang harus dilakukan perintah

Tulis perintah untuk memenuhi persyaratan ini:

• Shell dan direktori kerja: Claude Code menjalankan perintah melalui sh, atau melalui cmd.exe di Windows, dari direktori home pengguna. Berikan jalur absolut atau perintah di PATH.
• Output: cetak tepat satu baris di stdout, jalur absolut direktori plugin, dan keluar 0 dalam timeout detik.
• Isi direktori: direktori menyimpan plugin lengkap pada saat perintah keluar. Jalur dapat berbeda dari satu run ke run berikutnya.

Output yang gagal install atau update

Install atau update gagal ketika perintah keluar non-zero, berjalan lebih lama dari timeout, atau mencetak apa pun selain satu jalur absolut. Itu juga gagal ketika direktori yang dicetak adalah salah satu dari ini:

• Tidak ada konten plugin: direktori yang dicetak tidak memiliki konten plugin di tingkat atasnya, seperti direktori .claude-plugin/ atau direktori skills/, commands/, agents/, atau hooks/.
• Direktori sesi sendiri: direktori yang dicetak adalah yang Claude Code dimulai, atau salah satu induknya.
• Jalur jaringan: di Windows, jalur yang dicetak adalah jalur UNC.
• Terlalu besar untuk disalin: dalam mode copy, direktori lebih besar dari 256 MiB atau memiliki lebih dari 20.000 entri.

Mode copy dan mode link

mode memutuskan apakah Claude Code menyalin direktori yang dicetak atau menggunakannya di tempat:

• copy: Claude Code menyalin direktori ke cache plugin dan menurunkan versi plugin dari hash file yang disalin. Alat Anda dapat menghapus atau menulis ulang direktori setelah perintah keluar. Re-run yang menghasilkan file identik dihitung sebagai up to date.
• link: Claude Code mengisi entri cache plugin dengan tautan ke setiap entri tingkat atas direktori yang dicetak dan memuat file di tempat. Tidak ada yang disalin, konten file tidak di-hash, dan batas ukuran tidak berlaku. Gunakan untuk direktori terlalu besar untuk disalin, seperti ekspor SDK yang dirender.

Plugin mode link memiliki persyaratan ini:

• Simpan direktori di tempat: Claude Code memuat plugin melalui tautan di setiap startup, jadi direktori yang dicetak harus tetap di mana itu selama plugin tetap dipasang.
• Cetak jalur berbeda untuk menandakan konten baru: versi berasal dari jalur nyata direktori yang dicetak dan entri tingkat atasnya, bukan dari file di dalamnya.
• Simpan symlink tingkat atas di dalam direktori: install gagal jika entri tingkat atas adalah symlink yang menunjuk di luar direktori yang dicetak.
• Sertakan node_modules: Claude Code melewati install dependensi paket Node.js untuk plugin mode link, jadi cetak direktori yang sudah berisi paket yang dibutuhkan plugin.
• Sesi dimulai di dalam direktori: sesi yang dimulai di direktori yang dicetak atau di mana pun di bawahnya tidak memuat plugin.
• Bukan di Windows: Claude Code menolak untuk memasang plugin mode link di Windows. Deklarasikan "mode": "copy" di sana.

Sumber marketplace

Sumber marketplace mengatakan di mana Claude Code mengambil marketplace.json dari. CLI membangun satu untuk Anda ketika Anda menambahkan marketplace, dan Anda menulis satu sendiri di pengaturan:

• claude plugin marketplace add: Claude Code membangun sumber dari string yang Anda lewatkan.
• extraKnownMarketplaces: Anda menulis sumber sendiri sebagai objek source.
• strictKnownMarketplaces dan blockedMarketplaces: administrator menulis sumber dalam dua daftar kebijakan ini. strictKnownMarketplaces adalah allowlist dan blockedMarketplaces adalah blocklist.

Nama tipe url, git, dan github berarti sesuatu yang berbeda dalam sumber marketplace daripada dalam sumber plugin:

Tabel mencantumkan setiap tipe sumber marketplace dengan field-nya, input claude plugin marketplace add yang menghasilkannya, dan apa yang dilakukannya di masing-masing dari tiga kunci pengaturan.

Field menurut tipe

Tabel mencantumkan setiap field sumber marketplace yang memiliki default, batasan, atau makna khusus untuk tipenya.

Nilai sumber yang valid hanya dalam daftar kebijakan

hostPattern, pathPattern, skills-dir, dan bentuk owner/* dari repo hanya valid dalam dua daftar kebijakan, strictKnownMarketplaces dan blockedMarketplaces:

• hostPattern dan pathPattern: ekspresi reguler yang Claude Code uji terhadap sumber sebelum mengambil darinya.
• skills-dir: bukan sumber. Jika Anda menetapkan strictKnownMarketplaces sama sekali, plugin direktori skills berhenti dimuat sampai Anda menambahkan {"source": "skills-dir"} ke daftar itu.
• owner/*: sebagai nilai repo github, cocok dengan setiap repositori di bawah pemilik GitHub yang tepat. Memerlukan Claude Code v2.1.223 atau lebih baru.

Untuk urutan kecocokan, semantik ref yang tepat, dan resep, lihat Kelola plugin untuk organisasi Anda.

Objek sumber di pengaturan

Nilai extraKnownMarketplaces adalah peta dari nama marketplace ke objek dengan source. Entri ini mendaftarkan marketplace dari repositori git di cabang main-nya:

{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/your-org/your-marketplace.git",
        "ref": "main"
      }
    }
  }
}

strictKnownMarketplaces dan blockedMarketplaces adalah array objek sumber. Allowlist ini mengakui satu pemilik GitHub dan satu host internal:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "your-org/*" },
    { "source": "hostPattern", "hostPattern": "^git\\.example\\.com$" }
  ]
}

Pesan validasi

claude plugin validate <path> mengambil akar marketplace atau file marketplace itu sendiri. Itu mencetak kesalahan dan peringatan. Untuk kode keluar dan --strict, lihat plugin validate.

Pesan menamai entri plugin menurut indeksnya, ditulis sebagai plugins.1.source atau plugins[1].source.

Pesan yang diawali dengan indeks entri dan plugin.json →, seperti plugins[2] plugin.json →, adalah tentang file plugin itu sendiri. claude plugin validate melaporkan kesalahan mencantumkan pesan tersebut dengan perbaikannya.

Peringatan yang menyebutkan nama flag Claude Desktop menandai nama yang Claude Code terima tetapi Claude Desktop tolak, karena aturan nama Claude Desktop lebih ketat.

Tabel memetakan pesan tingkat marketplace ke field yang masing-masing tentang.

Invalid input pada sumber

Invalid input pada source berarti objek tidak cocok dengan tipe sumber apa pun. Periksa penyebab ini:

• Jalur relatif yang tidak dimulai dengan ./, selain "." atau nama bare di bawah metadata.pluginRoot
• package npm yang berisi ..
• Tipe source yang bukan salah satu dari sumber plugin
• Tipe yang dikenal dengan field yang diperlukan hilang atau tipe yang salah, seperti github tanpa repo

Kegagalan yang validasi tidak tangkap

claude plugin validate tidak melaporkan setiap kegagalan. Entri hooks yang ditulis sebagai jalur file atau array melewati validasi, dan kesalahan muncul hanya ketika plugin dimuat, seperti Hooks dalam entri menjelaskan. Kesalahan pengambilan source juga muncul hanya setelah install, bukan dalam validasi.

claude plugin list menunjukkan plugin yang gagal dimuat dengan kesalahannya, dan Troubleshoot plugins mencakup string waktu muat.

Langkah berikutnya

• Buat marketplace: bangun marketplace dari field ini dan pasang darinya secara lokal
• Host dan kelola marketplace: di mana menempatkan file dan cara pengguna menerima perubahan
• Referensi manifest plugin: field plugin.json yang dapat ditimpa entri
• Kelola plugin untuk organisasi Anda: resep allowlist dan blocklist yang menggunakan nilai sumber ini