Buat dan distribusikan marketplace plugin

Bangun dan host marketplace plugin untuk mendistribusikan ekstensi Claude Code di seluruh tim dan komunitas.

Sebuah marketplace plugin adalah katalog yang memungkinkan Anda mendistribusikan plugin kepada orang lain. Marketplace menyediakan penemuan terpusat, pelacakan versi, pembaruan otomatis, dan dukungan untuk berbagai jenis sumber, termasuk repositori git dan jalur lokal. Panduan ini menunjukkan cara membuat marketplace Anda sendiri untuk berbagi plugin dengan tim atau komunitas Anda.

Mencari cara memasang plugin dari marketplace yang sudah ada? Lihat Temukan dan pasang plugin yang sudah dibuat.

Ikhtisar

Membuat dan mendistribusikan marketplace melibatkan:

1. Membuat plugin: bangun satu atau lebih plugin dengan skills, agents, hooks, MCP servers, atau LSP servers. Panduan ini mengasumsikan Anda sudah memiliki plugin untuk didistribusikan; lihat Buat plugin untuk detail tentang cara membuat plugin.
2. Membuat file marketplace: tentukan marketplace.json yang mencantumkan plugin Anda dan di mana menemukannya. Lihat Buat file marketplace.
3. Host marketplace: dorong ke GitHub, GitLab, atau host git lainnya. Lihat Host dan distribusikan marketplace.
4. Bagikan dengan pengguna: pengguna menambahkan marketplace Anda dengan /plugin marketplace add dan memasang plugin individual. Lihat Temukan dan pasang plugin.

Setelah marketplace Anda aktif, Anda dapat memperbaruinya dengan mendorong perubahan ke repositori Anda. Pengguna menyegarkan salinan lokal mereka dengan /plugin marketplace update.

Panduan: buat marketplace lokal

Contoh ini membuat marketplace dengan satu plugin: skill quality-review untuk ulasan kode. Anda akan membuat struktur direktori, menambahkan skill, membuat manifest plugin dan katalog marketplace, kemudian memasang dan mengujinya.

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

---
description: Review code for bugs, security, and performance
---

Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements

Be concise and actionable.

{
"name": "quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}

{
"name": "my-plugins",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "quality-review-plugin",
"source": "./plugins/quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews"
}
]
}

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

/quality-review-plugin:quality-review

Untuk mempelajari lebih lanjut tentang apa yang dapat dilakukan plugin, termasuk hooks, agents, MCP servers, dan LSP servers, lihat Plugins.

Buat file marketplace

Buat .claude-plugin/marketplace.json di root repositori Anda. File ini mendefinisikan nama marketplace Anda, informasi pemilik, dan daftar plugin dengan sumbernya.

Setiap entri plugin memerlukan minimal name dan source yang memberitahu Claude Code di mana mengambilnya. Lihat skema lengkap di bawah untuk semua field yang tersedia.

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

Skema marketplace

Field yang diperlukan

Field pemilik

Field opsional

description dan version juga diterima di bawah metadata untuk kompatibilitas mundur.

Entri plugin

Setiap entri plugin dalam array plugins mendeskripsikan plugin dan di mana menemukannya. Anda dapat menyertakan field apa pun dari skema manifest plugin, seperti description, version, author, commands, dan hooks, ditambah field khusus marketplace ini: source, category, tags, strict, relevance, headers, dan headersHelper.

Field yang diperlukan

Field plugin opsional

Field metadata standar:

Baik entri maupun plugin.json plugin sendiri dapat menetapkan field tampilan displayName, description, author, homepage, repository, license, dan keywords. Dalam daftar plugin dan detail, 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 relative-path, yang file pluginnya berada di dalam marketplace itu sendiri. Untuk entri dengan tipe sumber apa pun yang lain, pengguna hanya melihat field entri sendiri sampai mereka memasang plugin.

Field konfigurasi komponen:

Field autentikasi archive:

Atur ini ketika entri memiliki archive source di server yang memerlukan kredensial.

Plugin sources

Plugin sources memberitahu Claude Code di mana mengambil setiap plugin individual yang tercantum di marketplace Anda. Ini diatur dalam field source dari setiap entri plugin di marketplace.json.

Claude Code menyalin setiap plugin yang dipasang ke cache plugin lokal yang tersimpan di ~/.claude/plugins/cache, kecuali plugin dimuat di tempat. Sebuah command source dalam link mode dimuat di tempat, dan begitu juga relative path source dalam marketplace yang ditambahkan dari direktori lokal. Claude Code juga memasang dependensi paket Node.js yang memenuhi syarat dari plugin ke dalam salinan yang di-cache. Lihat Plugin caching and file resolution untuk cara plugin yang dimuat di tempat dari marketplace direktori lokal mengambil edit Anda.

Jenis sumber berbasis git di bawah ini adalah github, url, dan git-subdir. Ketika baik ref maupun sha diatur pada salah satu dari mereka, sha adalah pin yang efektif. Claude Code mengambil dan melakukan checkout pada commit yang disematkan secara langsung.

Pada sebagian besar host git, termasuk GitHub, GitLab, dan Bitbucket, ini berarti instalasi berhasil bahkan jika branch 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 berdasarkan SHA. Di server tersebut ref masih harus ada dan commit yang disematkan harus dapat dijangkau darinya.

Jika Anda mendistribusikan plugin melalui Organization settings > Plugins, hanya beberapa jenis source yang diizinkan. Lihat Distribute through organization settings.

Jalur relatif

Untuk plugin di repositori yang sama, gunakan jalur yang dimulai dengan ./:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

Jalur diselesaikan relatif terhadap root marketplace, yang merupakan direktori yang berisi .claude-plugin/. Sumber ./plugins/my-plugin oleh karena itu menunjuk ke <repo>/plugins/my-plugin, meskipun marketplace.json berada di <repo>/.claude-plugin/marketplace.json. Jangan gunakan ../ untuk mereferensikan jalur di luar root marketplace. Di macOS dan Linux, Claude Code menolak entri jalur dengan backslash di mana pun melampaui ./ awal, jadi tulis pemisah sebagai / di setiap platform.

Bare name adalah nama direktori tunggal tanpa /, seperti "formatter". Untuk menulis bare names alih-alih jalur ./, atur metadata.pluginRoot ke direktori tempat mereka diselesaikan. Dengan "pluginRoot": "./plugins", Claude Code menyelesaikan "source": "formatter" ke ./plugins/formatter. Memerlukan Claude Code v2.1.239 atau lebih baru.

metadata.pluginRoot itu sendiri harus berupa jalur relatif di dalam marketplace. Claude Code mengabaikannya untuk source yang sudah dimulai dengan ./. Source yang berisi /, seperti team-a/formatter, bukan bare name dan masih memerlukan awalan ./, bahkan ketika metadata.pluginRoot diatur.

Repositori GitHub

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

Anda dapat menyematkan ke branch, tag, atau commit tertentu:

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Repositori Git

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

Anda dapat menyematkan ke branch, tag, atau commit tertentu:

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Subdirektori Git

Gunakan git-subdir untuk menunjuk ke plugin yang berada di dalam subdirektori repositori git. Claude Code menggunakan klon parsial dan sparse untuk mengambil hanya subdirektori, meminimalkan bandwidth untuk monorepo besar.

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

Anda dapat menyematkan ke branch, tag, atau commit tertentu:

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Field url juga menerima shorthand GitHub (owner/repo) atau URL SSH (git@github.com:owner/repo.git).

Paket npm

Sumber npm dapat menamai paket apa pun di registry npm publik atau di registry pribadi yang dihosting tim Anda. Claude Code menyelesaikan paket dengan klien npm Anda, mengunduh tarball, dan membukanya ke dalam cache plugin.

Skrip install paket, seperti preinstall atau postinstall, tidak pernah berjalan, dan dependensinya tidak dipasang selama pengambilan.

Jika paket mengirimkan lockfile yang didukung di samping package.json-nya, Claude Code memasang dependensi paket Node.js itu dalam langkah terpisah, juga dengan skrip dinonaktifkan. Jika tidak, publikasikan plugin dengan semua yang dibutuhkannya sudah dibangun. Server MCP yang memerlukan paket lain dapat diluncurkan melalui npx, yang memasangnya pada run pertama.

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

Untuk menyematkan ke versi tertentu, tambahkan field version:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

Untuk memasang dari registry pribadi atau internal, tambahkan field registry:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

Zip archives

Gunakan archive untuk mendistribusikan plugin sebagai file zip yang Claude Code unduh melalui HTTPS, sehingga instalasi berfungsi tanpa git atau npm di mesin pengguna. Hosting file di server file statis apa pun atau repositori artefak, seperti bucket S3, repositori generik Artifactory, atau nginx. Memerlukan Claude Code v2.1.224 atau lebih baru. Pada versi v2.1.120 hingga v2.1.223, memasang plugin gagal dengan This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.; pada versi yang lebih lama, marketplace yang berisi entri archive gagal dimuat sepenuhnya.

Entri ini memasang plugin dari file zip di server artefak:

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"
  }
}

Ketika Anda membuat zip, Anda dapat melakukan zip pada konten plugin secara langsung atau melakukan zip pada folder plugin itu sendiri. Claude Code mencari .claude-plugin/ di bagian atas arsip, kemudian di dalam folder tingkat atas tunggal, jadi kedua tata letak memasang:

my-plugin.zip          my-plugin.zip
├── .claude-plugin/    └── my-plugin/
│   └── plugin.json        ├── .claude-plugin/
└── commands/              │   └── plugin.json
                           └── commands/

Claude Code tidak mencari lebih dalam dari satu folder, jadi plugin yang bersarang lebih jauh gagal memasang. Claude Code menolak arsip yang lebih besar dari 256 MiB.

Untuk menyematkan file yang tepat, tambahkan field sha256 dengan digest arsip:

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

Jika file yang diunduh tidak cocok dengan pin, Claude Code menolak instalasi dan melaporkan Plugin archive integrity check failed.

Sumber arsip menerima field ini:

Digest sha256 juga berfungsi sebagai versi plugin ketika baik plugin.json maupun entri marketplace tidak mendeklarasikan satu. Lihat Version management. Jika Anda mendeklarasikan version, string versi itu adalah sinyal pembaruan, jadi setelah mengubah zip dan digestnya, tingkatkan versi juga, atau pengguna menyimpan salinan yang di-cache.

Authenticate archive downloads

Untuk mengautentikasi unduhan arsip, seperti unduhan dari registry pribadi, atur header HTTP yang Claude Code kirim dengannya. Atur headers pada sumber url yang Anda daftarkan marketplace darinya, seperti entri extraKnownMarketplaces. Pada Claude Code v2.1.238 atau lebih baru, Anda dapat mengaturnya pada entri plugin sebagai gantinya, di samping source.

Jika nilai yang akan Anda masukkan di headers berumur pendek, seperti token yang registry Anda cetak atas permintaan, atur perintah headersHelper di tempat yang sama sebagai gantinya. Claude Code menjalankan perintah dan mengirim objek JSON yang dicetak sebagai header tempat itu. Memerlukan Claude Code v2.1.238 atau lebih baru.

Tempat yang Anda pilih menentukan unduhan mana yang mendapatkan header dan kapan Claude Code menjalankan perintah:

Di mana kedua tempat mengatur header dengan nama yang sama, Claude Code mengirim nilai entri. Dalam satu tempat, header yang dicetak perintah menimpa header dengan nama yang sama yang tercantum di headers.

Add a headersHelper to a plugin entry

Entri ini mengatur headersHelper di samping source. Ini juga mengatur "strict": false, yang Claude Code perlukan dari entri marketplace.json yang mengatur headersHelper. Dengan "strict": false, entri marketplace adalah definisi lengkap plugin, jadi pengguna dapat meninjau apa yang berisi plugin sebelum menerima perintah:

{
  "name": "my-plugin",
  "description": "Formatting commands for internal services",
  "strict": false,
  "commands": "./commands",
  "source": {
    "source": "archive",
    "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
  },
  "headersHelper": "/opt/bin/mint-registry-token.sh"
}

Untuk memeriksa entri, jalankan claude plugin install my-plugin@your-marketplace. Claude Code menunjukkan perintah dan URL arsip, dan mengunduh zip setelah Anda menerima.

Sebelum v2.1.238, Claude Code mengunduh arsip entri tanpa headers atau headersHelper-nya, jadi instalasi yang bergantung pada mereka gagal dengan HTTP 401 while downloading plugin archive from, diikuti oleh URL, dengan kode status registry di tempat 401.

Write the headersHelper command

Baik Anda mengatur headersHelper pada sumber url marketplace atau pada entri plugin, tulis perintah untuk memenuhi persyaratan ini:

• Command text: paling banyak 500 karakter ASCII yang dapat dicetak, tanpa run empat atau lebih spasi.
• Output: cetak satu objek JSON dari nama header dan nilai string di stdout, kemudian keluar 0 dalam 10 detik.
• Shell dan working directory: Claude Code menjalankan perintah melalui sh, atau cmd.exe di Windows, dari direktori konfigurasi, ~/.claude atau CLAUDE_CONFIG_DIR. Berikan jalur absolut atau perintah di PATH, karena jalur relatif diselesaikan terhadap direktori itu, bukan proyek pengguna.
• Variables Claude Code removes: dari lingkungan perintah yang diatur dalam entri marketplace.json atau dalam .claude/settings.json atau .claude/settings.local.json proyek, Claude Code menghapus setiap variabel yang namanya berisi kata seperti TOKEN, SECRET, KEY, atau AUTH, termasuk ANTHROPIC_API_KEY. Claude Code tidak menerapkan penghapusan ini pada perintah yang diatur dalam pengaturan pengguna, file --settings, atau pengaturan yang dikelola.
• Variables Claude Code sets: CLAUDE_CODE_MARKETPLACE_URL dan CLAUDE_CODE_MARKETPLACE_NAME untuk perintah sumber url, dan CLAUDE_CODE_PLUGIN_NAME dan CLAUDE_CODE_PLUGIN_ARCHIVE_URL untuk perintah entri. CLAUDE_CODE_MARKETPLACE_NAME tidak diatur pada pengambilan pertama setelah pengguna menambahkan marketplace berdasarkan URL, karena pengambilan itu adalah apa yang menyediakan nama.

Perintah yang mencetak token bearer mencetak objek seperti ini:

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

When Claude Code skips a headersHelper command or drops its output

Claude Code tidak menjalankan perintah headersHelper, atau menjatuhkan header yang berasal dari headers atau dari output perintah, dalam situasi ini:

• Command fails: jika perintah keluar non-zero, berjalan melampaui 10 detik, atau mencetak apa pun selain objek JSON dari nilai string, Claude Code tidak membuat pengambilan atau unduhan yang menjalankan perintah untuk.
• Marketplace URL doesn't start with https://: Claude Code tidak menjalankan perintah sumber url itu dan mengirim hanya header yang tercantum di field headers-nya.
• Redirect leaves the origin: ketika unduhan dialihkan dari origin URL arsip, Claude Code menjatuhkan nilai headers dan output perintah dari sumber url marketplace dan entri plugin.
• Entry sets a routing or identity header: Claude Code menjatuhkan nama perutean permintaan dan identitas klien seperti Host, Cookie, dan X-Forwarded-* dari headers entri dan output perintah, dan menyimpan nama autentikasi seperti Authorization. Claude Code memfilter setiap entri marketplace.json dengan cara ini, dan entri inline settings tergantung file mana yang mendeklarasikannya.
• Command set in an --add-dir directory's settings: Claude Code mengabaikannya, pada sumber url dan pada entri plugin inline sama-sama, dan mengirim hanya headers file itu.
• Managed settings block the command: mengatur disableCommandPluginSources ke true memblokir perintah headersHelper, dan allowManagedHooksOnly juga memblokir mereka kecuali disableCommandPluginSources secara eksplisit false. Di bawah blok mana pun, Claude Code masih menjalankan perintah untuk marketplace yang pengaturan yang dikelola sendiri deklarasikan.

How users accept a headersHelper command

Pengguna menerima perintah entri plugin setiap kali mereka memasang atau memperbarui plugin itu saja, dari tampilan plugin sendiri di /plugin atau dengan claude plugin install atau claude plugin update. Claude Code menunjukkan perintah dan URL arsip, dan menjalankan perintah hanya setelah pengguna menerima.

Dalam shell non-interaktif, teruskan --yes untuk menerimanya. Untuk menerima hanya perintah yang run --json sebelumnya ditampilkan, teruskan --accept-command dengan sha256 yang dilaporkan run.

Claude Code menjalankan hanya perintah yang ditunjukkan, untuk URL arsip yang ditunjukkan. Jika perintah entri atau URL arsip berubah di antara, Claude Code menolak instalasi atau pembaruan. Perubahan dalam string kueri saja tidak dihitung.

Installs and updates that refuse the command instead of asking

Pada operasi apa pun selain instalasi atau pembaruan plugin tunggal, Claude Code tidak menjalankan perintah entri atau mengunduh arsipnya, jadi plugin tetap pada versi yang dipasang atau tetap tidak dipasang. Apa yang dilihat pengguna tergantung pada operasi:

• Installing several plugins at once, from a plugin suggestion, or as another plugin's dependency: Claude Code menolak plugin yang memiliki perintah dan menunjukkan pengguna pada tampilan plugin itu sendiri di /plugin. Plugin lain dalam instalasi massal masih memasang. Plugin yang bergantung pada plugin yang ditolak gagal memasang sampai pengguna memasang plugin yang ditolak itu sendiri.
• Background auto-update, or session start for a plugin whose archive was never downloaded: Claude Code mencantumkan plugin di tab /plugin Errors sehingga pengguna tahu untuk memasang atau memperbarui itu dengan tangan. Pembaruan otomatis yang menemukan entri masih mengiklankan versi yang dipasang mencantumkan tidak ada.

When a marketplace `url` source's command runs

headersHelper sumber url marketplace dideklarasikan dalam file pengaturan, seperti entri extraKnownMarketplaces, daripada dalam katalog yang dipublikasikan marketplace, jadi Claude Code tidak meminta pengguna untuk menerimanya pada setiap instalasi atau pembaruan. File pengaturan yang mendeklarasikannya menentukan kapan Claude Code menjalankannya:

Dalam sesi -p atau SDK, Claude Code tidak dapat menunjukkan dialog persetujuan keamanan. Ini menerapkan pengaturan yang dikirimkan lainnya, tetapi pengambilan marketplace, dan unduhan arsip apa pun yang memerlukan perintah, gagal sampai pengguna telah menyetujui dalam sesi interaktif.

Untuk entri plugin inline dalam salah satu file ini, Claude Code memerlukan kepercayaan folder atau persetujuan pengaturan yang sama seperti untuk perintah tingkat marketplace dalam file itu, dan pengguna juga menerima perintah entri pada setiap instalasi atau pembaruan.

Command sources

Gunakan command ketika alat yang dipasang secara lokal menghasilkan direktori plugin, seperti IDE yang merender plugin untuk toolchain yang saat ini dipilih. Claude Code menjalankan perintah ketika pengguna memasang plugin dan menjalankannya kembali di latar belakang sekali per sesi, jadi pengguna Anda mengambil output alat yang berubah tanpa memasang ulang. Memerlukan Claude Code v2.1.229 atau lebih baru. Pada v2.1.120 hingga v2.1.228, memasang plugin gagal dengan This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again., dan pada versi yang lebih lama seluruh marketplace gagal dimuat.

Entri ini memasang plugin dari direktori apa pun yang dicetak alat:

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

Claude Code menjalankan perintah melalui shell platform, sh di macOS dan Linux atau cmd.exe di Windows, dari direktori home pengguna. Perintah harus mencetak tepat satu baris di stdout dan keluar dengan kode 0. Baris itu adalah jalur absolut dari direktori yang berisi plugin lengkap pada saat perintah keluar, dan jalur dapat berubah antara run.

Claude Code menghentikan perintah yang berjalan lebih lama dari timeout detik, dan instalasi atau pembaruan gagal. Claude Code juga menolak jalur yang dicetak dalam kasus ini, dan instalasi atau pembaruan gagal dengan cara yang sama:

• Direktori tidak memiliki konten plugin di tingkat atasnya, seperti direktori .claude-plugin/ atau direktori skills/, commands/, agents/, atau hooks/
• Direktori adalah yang Claude Code dimulai, atau salah satu induknya
• Di Windows, jalur adalah jalur UNC

Sumber perintah menerima field ini:

Copy mode and link mode

Dengan default "mode": "copy", Claude Code menyalin direktori yang dicetak ke cache plugin yang tersimpan dan menurunkan versi plugin dari hash konten direktori. Alat Anda dapat menghapus atau menulis ulang direktori setelah perintah keluar, dan re-run yang menghasilkan konten identik dihitung sebagai terkini. Claude Code menolak untuk memasang direktori yang lebih besar dari 256 MiB atau berisi lebih dari 20.000 entri.

Atur "mode": "link" untuk direktori plugin besar yang tidak boleh disalin, seperti ekspor SDK yang dirender. Claude Code mengisi entri cache plugin dengan link ke setiap entri tingkat atas dari direktori yang dicetak dan menggunakan file di tempat, jadi tidak ada yang disalin, konten file tidak di-hash, dan batas ukuran tidak berlaku. Instalasi gagal jika entri tingkat atas adalah symlink yang menunjuk di luar direktori yang dicetak. Claude Code juga melewati instalasi dependensi paket Node.js untuk plugin mode link, jadi cetak direktori yang sudah berisi node_modules apa pun yang dibutuhkan plugin.

Simpan direktori yang dicetak di tempat selama plugin tetap dipasang, karena Claude Code memuat plugin melalui link itu di setiap startup. Claude Code menurunkan versi plugin dari jalur nyata direktori yang dicetak dan entri tingkat atasnya, bukan file di dalamnya, jadi cetak jalur berbeda untuk menandakan konten baru. Dalam sesi yang dimulai di direktori yang dicetak atau di mana pun di bawahnya, Claude Code tidak memuat plugin sama sekali.

Claude Code tidak mendukung mode link di Windows dan menolak untuk memasang plugin mode link di sana. Deklarasikan "mode": "copy" sebagai gantinya.

How users accept the command

Claude Code menjalankan perintah Anda di mesin pengguna, jadi mengikat setiap run ke penerimaan eksplisit pengguna:

• Ketika pengguna memasang plugin dari layar detailnya di /plugin, atau memasang atau memperbarui dengan claude plugin install atau claude plugin update di terminal interaktif, Claude Code menunjukkan string perintah yang tepat terlebih dahulu dan mencatat perintah yang diterima untuk instalasi itu. claude plugin update yang dapat dilanjutkan pada penerimaan perintah yang sama menunjukkan tidak ada.
• Dalam shell non-interaktif, seperti skrip provisioning, teruskan --yes ke claude plugin install atau claude plugin update untuk menerima perintah yang dicetak. Untuk menerima hanya perintah yang run --json sebelumnya ditampilkan, teruskan --accept-command dengan sha256 yang dilaporkan run.
• Setiap jalur lain menjalankan hanya perintah yang sudah diterima pengguna. Ini termasuk pembaruan yang dimulai dari /plugin dan run latar belakang yang dijelaskan dalam When Claude Code re-runs the command. Ketika tidak ada yang diterima, Claude Code menolak untuk menjalankan perintah dan memberi tahu pengguna cara meninjau. Claude Code tidak pernah memasang plugin bersumber perintah sebagai dependensi plugin lain, jadi pengguna memasangnya sendiri terlebih dahulu.
• Jika Anda mengubah command entri, atau beralih mode-nya, pengguna menyimpan versi yang sudah mereka miliki dan Claude Code berhenti menjalankan perintah kembali. Dalam sesi interaktif, tab /plugin Errors menunjukkan perintah baru sampai pengguna meninjau dan menerimanya dengan menjalankan claude plugin update <plugin>@<marketplace>.

Administrator dapat memblokir sumber perintah di seluruh organisasi dengan pengaturan yang dikelola disableCommandPluginSources. Jika organisasi mengatur allowManagedHooksOnly, Claude Code memblokir sumber perintah secara default.

When Claude Code re-runs the command

Direktori yang dicetak mencerminkan keadaan alat pada saat perintah berjalan, jadi Claude Code menjalankan perintah lagi pada waktu ini:

• Setiap kali pengguna memasang atau memperbarui plugin
• Sekali per sesi untuk setiap plugin bersumber perintah yang diaktifkan, di latar belakang, segera setelah sesi dimulai. Run ini tidak melalui pembaruan marketplace otomatis, jadi tidak bergantung pada pengaturan pembaruan otomatis marketplace
• Pada startup atau di /reload-plugins, ketika versi yang dipasang plugin yang diaktifkan hilang dari cache plugin

Claude Code melewati dua run latar belakang ketika pengguna mengatur CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. Instalasi dan pembaruan eksplisit masih menjalankan perintah dengan variabel itu diatur.

Ketika output yang di-hash perintah telah berubah, Claude Code memasang hasilnya sebagai versi baru dan memuat ulang dalam sesi interaktif yang berjalan, beralih komponen yang sama yang /reload-plugins beralih. Pengguna melihat notifikasi bahwa plugin dimuat ulang. Jika memuat ulang di tempat akan membatalkan cache prompt sesi, Claude Code malah meminta pengguna untuk menjalankan /reload-plugins, yang memperingatkan tentang biaya cache dan menerapkan ketika dijalankan kembali dengan --force.

Entri plugin lanjutan

Contoh ini menunjukkan entri plugin menggunakan banyak field opsional, termasuk jalur kustom untuk commands, agents, hooks, dan MCP servers:

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

Hal-hal penting untuk diperhatikan:

• commands dan agents: Anda dapat menentukan beberapa direktori atau file individual. Jalur relatif terhadap root plugin dan harus tetap di dalamnya.
  • Claude Code menolak jalur yang diselesaikan di luar direktori plugin, seperti ./../shared.md, dengan error path escapes plugin directory, dan masih memuat plugin tanpa komponen itu
• ${CLAUDE_PLUGIN_ROOT}: gunakan variabel ini dalam perintah hook dan config MCP server untuk mereferensikan file dalam direktori instalasi plugin.
  • Lihat tabel substitusi untuk field config mana yang mensubstitusinya per tipe server
  • Untuk dependensi atau state yang harus bertahan pembaruan plugin, gunakan ${CLAUDE_PLUGIN_DATA} sebagai gantinya
• strict: false: Karena ini diatur ke false, plugin tidak memerlukan plugin.json sendiri. Entri marketplace mendefinisikan semuanya. Lihat Strict mode di bawah.

Secara default, skills plugin dimuat dari direktori skills/ di bawah source-nya. Jalur yang tercantum dalam field skills menambah pemindaian itu:

"skills": ["./skills/", "./extra-skills/"]

Ketika beberapa entri plugin berbagi satu folder skills/ di root marketplace (source: "./"), cantumkan subdirektori spesifik sebagai gantinya sehingga setiap entri hanya memuat skills-nya sendiri:

"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]

Dengan sumber root marketplace, jalur yang tercantum adalah set lengkap untuk entri itu, dan direktori lain di folder skills/ bersama tidak dimuat. Mencantumkan ./skills/ itu sendiri, atau root plugin, menjaga pemindaian penuh. Jika tidak ada jalur yang tercantum ada, pemindaian default berjalan sebagai gantinya.

Strict mode

Field strict mengontrol apakah plugin.json adalah otoritas untuk definisi komponen (skills, agents, hooks, MCP servers, output styles).

Kapan menggunakan setiap mode:

• strict: true: plugin memiliki plugin.json sendiri dan mengelola komponennya sendiri. Entri marketplace dapat menambahkan skills atau hooks tambahan di atas. Ini adalah default dan berfungsi untuk sebagian besar plugin.
• strict: false: operator marketplace menginginkan kontrol penuh. Repo plugin menyediakan file mentah, dan entri marketplace mendefinisikan file mana yang diekspos sebagai skills, agents, hooks, dll. Berguna ketika marketplace merestruktur atau mengkurasi komponen plugin secara berbeda dari yang dimaksudkan penulis plugin.

Host dan distribusikan marketplace

Ketika pengguna menambahkan marketplace yang dihosting di repositori git, atau memasang plugin berbasis git yang tercantum, Claude Code mengklon repositori marketplace atau plugin itu ke mesin mereka. Klon tidak pernah mengunduh konten Git LFS, jadi file yang dilacak LFS tiba sebagai file pointer. Jaga file yang dibutuhkan plugin Anda keluar dari LFS.

Host di GitHub (direkomendasikan)

GitHub adalah cara yang direkomendasikan untuk host dan distribusikan marketplace:

1. Buat repositori: siapkan repositori baru untuk marketplace Anda
2. Tambahkan file marketplace: buat .claude-plugin/marketplace.json dengan definisi plugin Anda
3. Bagikan dengan tim: pengguna menambahkan marketplace Anda dengan /plugin marketplace add owner/repo

Manfaat: kontrol versi bawaan, pelacakan masalah, dan fitur kolaborasi tim.

Host di layanan git lainnya

Layanan hosting git apa pun berfungsi, seperti GitLab, Bitbucket, dan server yang dihosting sendiri. Pengguna menambahkan dengan URL repositori lengkap:

/plugin marketplace add https://gitlab.com/company/plugins.git

Repositori pribadi

Claude Code mendukung pemasangan plugin dari repositori pribadi. Jika Anda mendistribusikan marketplace Anda melalui Organization settings > Plugins sebagai gantinya, kredensial git Anda tidak terlibat: sinkronisasi organisasi membaca repositori marketplace melalui koneksi GitHub atau GitLab organisasi Anda di claude.ai. Lihat Distribusikan melalui pengaturan organisasi untuk sumber plugin mana yang dapat bersifat pribadi.

Perintah yang Anda jalankan

Ketika Anda menjalankan /plugin marketplace add, /plugin install, /plugin update, atau /plugin marketplace update, Claude Code menggunakan helper kredensial git yang ada, jadi akses HTTPS melalui gh auth login, Keychain macOS, atau git-credential-store berfungsi sama seperti di terminal Anda. Akses SSH berfungsi selama host sudah ada di file known_hosts Anda dan kunci dimuat di ssh-agent, karena Claude Code menekan prompt SSH interaktif untuk sidik jari host dan passphrase kunci. Shorthand owner/repo GitHub mengklon melalui SSH secara default; atur CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 untuk mengklonnya melalui HTTPS sebagai gantinya.

Pembaruan otomatis latar belakang

Pemeriksaan refresh latar belakang memeriksa remote marketplace untuk commit baru dengan helper kredensial git yang dikonfigurasi, sama seperti perintah yang Anda jalankan. Untuk remote SSH, kunci yang dimuat di ssh-agent mengautentikasi pemeriksaan. Claude Code menjalankan pemeriksaan secara non-interaktif: ia mematikan prompt terminal git dan program askpass, dan memberitahu helper kredensial untuk tidak meminta. Apakah pemeriksaan dapat mengautentikasi ke repositori pribadi melalui HTTPS tergantung pada helper Anda:

• Helper yang dapat menyediakan kredensial yang disimpan tanpa meminta mengautentikasi pemeriksaan. Git Credential Manager, helper Keychain macOS, dan git-credential-store bekerja dengan cara ini setelah mereka menyimpan kredensial untuk host.
• Helper yang perlu meminta Anda tidak dapat menjawab di latar belakang. Pembaruan gagal diam-diam dan checkout yang ada tetap di tempat, jadi plugin Anda terus bekerja dari status terakhir yang disinkronkan. Jalankan /plugin marketplace update <name> untuk menyegarkan marketplace dengan kredensial Anda.

Ketika pemeriksaan menemukan checkout up to date, Claude Code meninggalkannya apa adanya. Ketika pemeriksaan menemukan commit baru, atau gagal karena tidak dapat menjangkau atau mengautentikasi ke remote, Claude Code mengklon marketplace lagi dan menukar klon baru. Jika klon itu gagal, checkout yang ada tetap di tempat. Pengklonaan ulang dapat time out pada repositori besar.

Dua pengaturan membuat marketplace pribadi berperilaku dapat diprediksi:

• Atur CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 untuk menyimpan checkout yang ada tanpa mencoba pengklonaan ulang ketika pemeriksaan latar belakang tidak dapat menjangkau atau mengautentikasi ke remote. Plugin Anda terus bekerja dari status terakhir yang disinkronkan, dan pembaruan manual dengan /plugin marketplace update masih mengautentikasi dengan kredensial Anda.
• Konfigurasikan helper kredensial git, misalnya dengan gh auth setup-git untuk GitHub, sehingga pemeriksaan latar belakang dan pengklonaan ulang dapat mengautentikasi tanpa meminta.

Menetapkan token penyedia seperti GITHUB_TOKEN di lingkungan Anda tidak dengan sendirinya mengaktifkan autentikasi latar belakang. Token hanya berlaku melalui helper kredensial yang dikonfigurasi, misalnya helper CLI gh, yang membaca GH_TOKEN dan GITHUB_TOKEN.

Distribusikan melalui pengaturan organisasi

Jika Anda mendistribusikan plugin melalui Organization settings > Plugins pada paket Team atau Enterprise, aturan sumber ini berlaku:

• Di github.com dan gitlab.com, repositori marketplace harus bersifat pribadi atau internal. Sinkronisasi organisasi membaca repositori melalui koneksi yang cocok dengan hostnya:
  • github.com: Claude GitHub App
  • Host GitHub Enterprise Server Anda: GitHub Enterprise App organisasi Anda
  • gitlab.com atau instance GitLab yang dikelola sendiri Anda: token akses dalam konfigurasi GitLab organisasi Anda untuk host itu
• Setiap sumber plugin harus bertipe github, url, atau git-subdir, atau jalur relatif yang dimulai dengan ./. Jika Anda membuat daftar plugin berdasarkan nama kosong di bawah metadata.pluginRoot, sinkronisasi organisasi menolaknya sebagai sumber yang tidak didukung, jadi tuliskan jalurnya, seperti ./plugins/deploy-tools.
• Sumber plugin dapat bersifat pribadi dalam tiga kasus:
  • Sumber github.com yang berbagi pemilik repositori marketplace
  • Sumber di host GitHub Enterprise organisasi Anda dengan GHE App yang dipasang di repositori
  • Sumber url atau git-subdir di host GitLab yang sama dengan repositori marketplace. Di gitlab.com, sumber juga harus berada di bawah grup tingkat atas atau namespace pengguna yang sama dengan repositori marketplace.
• Sumber plugin lainnya harus berupa repositori publik di github.com, gitlab.com, atau bitbucket.org, yang diambil sinkronisasi organisasi tanpa kredensial. Sinkronisasi organisasi menolak sumber plugin di host yang tidak dicakup aturan ini.

Lihat Manage plugins for your organization untuk alur kerja admin.

Untuk menyertakan plugin pribadi, tempatkan folder plugin di dalam repositori marketplace dan referensikan dengan jalur relatif. Sinkronisasi organisasi mengemas setiap plugin selama distribusi, jadi pengguna tidak pernah memerlukan akses ke repositori sumber terpisah.

Misalnya, entri plugin marketplace.json ini mereferensikan plugin yang Anda komit di plugins/deploy-tools dalam repositori marketplace:

{
  "name": "deploy-tools",
  "source": "./plugins/deploy-tools"
}

Sinkronkan marketplace yang dihosting GitLab

Untuk menyinkronkan marketplace dari gitlab.com atau instance GitLab yang dikelola sendiri, Owner terlebih dahulu menambahkan konfigurasi GitLab untuk host itu di Organization settings > Claude Code. Konfigurasi GitLab dalam beta publik dan hanya berlaku untuk sinkronisasi marketplace plugin. Menambahkan satu tidak membuat repositori GitLab tersedia di Claude Code di web. Lihat Manage plugins for your organization untuk langkah-langkah setup.

Ketika Anda menambahkan marketplace, masukkan URL HTTPS proyek, seperti https://gitlab.example.com/platform/claude-plugins. Proyek dalam subgrup bersarang berfungsi. Sinkronisasi organisasi membaca cabang default proyek. Jika Anda mengaktifkan Sync automatically, hanya push ke cabang default yang memulai sinkronisasi.

Jaga executable keluar dari direktori bin tingkat atas

Jangan sertakan direktori bin/ tingkat atas dalam plugin apa pun yang Anda distribusikan melalui pengaturan organisasi. claude.ai menolak plugin yang memilikinya, baik plugin tiba melalui sinkronisasi marketplace atau unggahan langsung:

• Sinkronisasi marketplace: sinkronisasi organisasi menolak plugin itu dan menyinkronkan sisa marketplace. Pesan kesalahan dimulai dengan Plugin contains a top-level bin/ directory.
• Unggahan langsung: jika Anda mengunggah plugin di Organization settings > Plugins sebagai gantinya, claude.ai menolak unggahan dengan pesan yang sama.

Jaga executable di direktori lain, seperti scripts/, dan referensikan sebagai ${CLAUDE_PLUGIN_ROOT}/scripts/<name> dari skills, hooks, atau konfigurasi server MCP Anda.

Wajibkan marketplace untuk tim Anda

Anda dapat mengonfigurasi repositori Anda sehingga Claude Code menambahkan marketplace Anda untuk anggota tim sekali mereka mempercayai folder proyek, tanpa prompt terpisah. Tambahkan marketplace Anda ke .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

Anda juga dapat menentukan plugin mana yang harus diaktifkan secara default:

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

Untuk opsi konfigurasi lengkap, lihat Plugin settings.

Pra-isi plugin untuk container

Untuk image container dan lingkungan CI, Anda dapat pra-isi direktori plugin saat waktu build sehingga Claude Code dimulai dengan marketplace dan plugin yang sudah tersedia, tanpa mengklon apa pun saat runtime. Atur variabel lingkungan CLAUDE_CODE_PLUGIN_SEED_DIR untuk menunjuk ke direktori ini.

Untuk melapisi beberapa direktori seed, pisahkan jalur dengan : di Unix atau ; di Windows. Claude Code mencari setiap direktori secara berurutan dan menggunakan seed pertama yang berisi marketplace atau cache plugin yang diberikan.

Direktori seed mencerminkan struktur ~/.claude/plugins:

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

Untuk membangun direktori seed, jalankan Claude Code sekali selama image build, pasang plugin yang Anda butuhkan, kemudian salin direktori ~/.claude/plugins yang dihasilkan ke image Anda dan tunjukkan CLAUDE_CODE_PLUGIN_SEED_DIR ke sana.

Untuk melewati langkah copy, atur CLAUDE_CODE_PLUGIN_CACHE_DIR ke jalur target seed Anda selama build sehingga plugin dipasang langsung ke sana:

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

Kemudian atur CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed di lingkungan runtime container Anda sehingga Claude Code membaca dari seed saat startup.

Saat startup, Claude Code mendaftarkan marketplace yang ditemukan di known_marketplaces.json seed ke dalam konfigurasi utama, dan menggunakan cache plugin yang ditemukan di bawah cache/ di tempat tanpa mengklon ulang. Ini berfungsi dalam mode interaktif dan mode non-interaktif dengan flag -p.

Detail perilaku:

• Read-only: Claude Code tidak pernah menulis ke direktori seed.
• Auto-updates disabled: marketplace seed tidak auto-update.
• Entri seed mengambil prioritas: marketplace yang dideklarasikan dalam seed menimpa entri yang cocok apa pun dalam konfigurasi pengguna di setiap startup. Untuk opt out dari plugin seed, gunakan /plugin disable daripada menghapus marketplace.
• Resolusi jalur: Claude Code menemukan konten marketplace dengan menyelidiki $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ saat runtime, bukan dengan mempercayai jalur yang disimpan di dalam JSON seed. Ini berarti seed berfungsi dengan benar bahkan ketika dipasang di jalur berbeda dari tempat dibangun.
• Mutasi diblokir: menjalankan /plugin marketplace remove atau /plugin marketplace update terhadap marketplace yang dikelola seed gagal dengan panduan untuk meminta administrator Anda memperbarui image seed.
• Komposisi dengan pengaturan: jika extraKnownMarketplaces atau enabledPlugins mendeklarasikan marketplace yang sudah ada di seed, Claude Code menggunakan salinan seed alih-alih mengklon.

Pembatasan marketplace yang dikelola

Untuk organisasi yang memerlukan kontrol ketat atas sumber plugin, administrator dapat membatasi marketplace plugin mana yang diizinkan pengguna untuk tambahkan menggunakan pengaturan strictKnownMarketplaces dalam pengaturan yang dikelola. Untuk juga menolak flag CLI yang sideload plugin, agen, dan server MCP untuk satu kali jalankan, pasangkan dengan disableSideloadFlags. Untuk allowlist marketplace mana yang plugin-nya dapat muncul sebagai saran instalasi kontekstual, atur pluginSuggestionMarketplaces.

strictKnownMarketplaces cocok dengan marketplace tempat plugin berasal, bukan entri di dalamnya, jadi pengguna masih dapat memasang plugin dengan sumber command dari marketplace yang diizinkan. Untuk memblokir sumber command juga, atur disableCommandPluginSources.

Ketika strictKnownMarketplaces dikonfigurasi dalam pengaturan yang dikelola, perilaku pembatasan tergantung pada nilainya:

Konfigurasi umum

Nonaktifkan semua penambahan marketplace, termasuk marketplace Anthropic resmi:

{
  "strictKnownMarketplaces": []
}

Claude Code mengunduh plugin disinkronkan dari claude.ai dari akun Anda daripada dari marketplace, jadi lockdown ini tidak mencakupnya. Untuk menghentikan yang juga, atur syncClaudeAiPlugins ke false dalam pengaturan yang dikelola, atau matikan Skills untuk organisasi Anda di claude.ai.

Izinkan hanya marketplace Anthropic resmi. Pencocokan untuk entri repositori tunggal bersifat tepat, jadi entri ini tidak mencakup varian ref atau path dari repositori yang sama:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "anthropics/claude-plugins-official"
    }
  ]
}

Dengan entri ini, Claude Code menjaga marketplace resmi yang sudah terdaftar tetap tersedia dan, di mesin baru, mendaftarkan marketplace secara otomatis saat pertama kali Anda memulai Claude Code secara interaktif.

Pendaftaran otomatis tidak mencakup setiap mesin. Paling sering melewatkan:

• Lingkungan non-interaktif yang berjalan sebelum peluncuran interaktif pertama mesin.
• Mesin tempat Claude Code sudah berjalan secara interaktif di bawah kebijakan yang memblokir marketplace, seperti lockdown array kosong. Claude Code mencatat upaya yang diblokir dan tidak mencoba lagi setelah kebijakan berubah.

Di mesin ini, tambahkan marketplace ke extraKnownMarketplaces dalam managed-settings.json yang sama sehingga Claude Code mendaftarkannya secara otomatis, atau jalankan claude plugin marketplace add anthropics/claude-plugins-official.

Izinkan marketplace tertentu saja:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}

Izinkan setiap repositori marketplace di bawah organisasi GitHub dengan entri owner-wildcard. Owner wildcards memerlukan Claude Code v2.1.223 atau lebih baru.

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/*"
    }
  ]
}

Izinkan semua marketplace dari server git internal menggunakan pencocokan pola regex pada host. Ini adalah pendekatan yang direkomendasikan untuk GitHub Enterprise Server atau instance GitLab yang dihosting sendiri:

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

Izinkan marketplace berbasis filesystem dari direktori tertentu menggunakan pencocokan pola regex pada jalur:

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

Gunakan ".*" sebagai pathPattern untuk mengizinkan jalur filesystem apa pun sambil tetap mengontrol sumber jaringan dengan hostPattern.

Cara pembatasan bekerja

Pembatasan diperiksa sebelum operasi jaringan atau filesystem apa pun. Pemeriksaan berjalan pada marketplace add dan pada plugin install, update, refresh, dan auto-update. Jika marketplace ditambahkan sebelum kebijakan dikonfigurasi dan sumbernya tidak lagi cocok dengan daftar izin, Claude Code menolak untuk memasang atau memperbarui plugin darinya. Penegakan yang sama berlaku untuk blockedMarketplaces.

Tempat kedua daftar diterapkan tergantung pada tempat Anda menetapkannya:

• Konsol admin claude.ai: Claude Code menerapkan kedua daftar dalam sesi yang membaca pengaturan yang dikelola server. claude.ai juga memeriksanya ketika siapa pun dalam organisasi Anda menambahkan marketplace baru dari repositori git di claude.ai, atau dari Customize di aplikasi Claude Desktop di luar tab Code-nya. Itu mencakup marketplace yang ditambahkan anggota untuk akun mereka sendiri dan yang ditambahkan untuk seluruh organisasi di bawah Organization settings > Plugins. claude.ai menolak repositori yang tidak diakui allowlist atau yang dinamai blocklist. Itu tidak memeriksa ulang marketplace yang ditambahkan di salah satu tempat sebelum Anda menetapkan daftar, dan itu tidak memeriksa plugin yang diunggah.
• File pengaturan yang dikelola, kebijakan tingkat OS, atau sumber yang dikelola lainnya: Claude Code menerapkan kedua daftar tempat itu membaca sumber itu. claude.ai tidak membacanya.

Untuk memblokir setiap repositori marketplace di bawah pemilik GitHub, gunakan bentuk owner-wildcard dalam entri blockedMarketplaces: { "source": "github", "repo": "untrusted-org/*" }. Memerlukan Claude Code v2.1.223 atau lebih baru. Untuk aturan pencocokan, yang berbeda antara blocklist dan allowlist, lihat Owner wildcards.

Ketika pengguna menambahkan URL repositori https:// yang Claude Code klon daripada ambil, seperti URL repositori github.com atau gitlab.com kosong, Claude Code juga memeriksanya terhadap entri url dalam blockedMarketplaces. Claude Code memblokir penambahan jika entri menamai URL yang sama. Dalam perbandingan itu, Claude Code mengabaikan akhiran .git dan ref apa pun yang ditambahkan pengguna setelah #. Memerlukan Claude Code v2.1.232 atau lebih baru. Sebelum v2.1.232, Claude Code mencocokkan entri url hanya terhadap URL yang diambil sebagai file marketplace.json yang dihosting.

Allowlist menggunakan pencocokan tepat untuk sebagian besar jenis sumber, terlepas dari entri github owner-wildcard. Agar marketplace diizinkan, semua field yang ditentukan harus cocok:

• Untuk sumber GitHub: repo diperlukan, baik menamai satu repositori atau menggunakan bentuk owner-wildcard owner/* untuk mencakup setiap repositori di bawah pemilik itu. Untuk cara entri wildcard cocok, termasuk aturan kasus, lihat Owner wildcards. Untuk entri repositori tunggal, ref harus cocok tepat atau tidak ada di kedua sumber marketplace dan entri allowlist, dan aturan yang sama berlaku untuk path
• Untuk sumber URL: URL lengkap harus cocok secara tepat
• Untuk sumber hostPattern: host marketplace dicocokkan dengan pola regex
• Untuk sumber pathPattern: jalur filesystem marketplace dicocokkan dengan pola regex

Pencocokan tepat allowlist memperlakukan URL yang berbeda hanya dengan garis miring trailing, akhiran .git, atau skema ssh:// dan https:// sebagai nilai berbeda. Jika marketplace organisasi Anda dapat diklon oleh lebih dari satu bentuk URL, lebih suka entri hostPattern daripada URL literal sehingga bentuk https://, ssh://, dan user@host:path semuanya cocok.

Marketplace yang dihosting di claude.ai dicocokkan berdasarkan host: entri hostPattern yang cocok dengan claude.ai mengatur, dalam strictKnownMarketplaces dan dalam blockedMarketplaces. Di allowlist, entri seperti itu tidak mengakui unggahan claude.ai pribadi anggota. Memerlukan Claude Code v2.1.273 atau lebih baru.

Karena strictKnownMarketplaces diatur dalam pengaturan yang dikelola, konfigurasi pengguna individual dan proyek tidak dapat mengganti pembatasan ini.

Untuk detail konfigurasi lengkap termasuk semua jenis sumber yang didukung dan perbandingan dengan extraKnownMarketplaces, lihat referensi strictKnownMarketplaces.

Resolusi versi dan saluran rilis

Versi plugin menentukan jalur cache dan deteksi pembaruan: jika versi yang diselesaikan cocok dengan apa yang sudah dimiliki pengguna, /plugin update dan auto-update melewati plugin. Untuk sumber berbasis git, jika Anda menghilangkan version, Claude Code menggunakan SHA commit yang diselesaikan dari sumber, jadi pengguna mendapatkan pembaruan setiap kali commit itu berubah; ini adalah setup paling sederhana untuk plugin internal atau yang sedang dikembangkan secara aktif. Lihat Version management untuk urutan resolusi lengkap, termasuk sumber archive.

Siapkan saluran rilis

Untuk mendukung saluran rilis "stable" dan "latest" untuk plugin Anda, Anda dapat menyiapkan dua marketplace yang menunjuk ke refs atau SHA berbeda dari repo yang sama. Anda kemudian dapat memberikan setiap grup pengguna marketplace-nya sendiri melalui pengaturan yang dikelola dalam salah satu dari dua cara:

• Terapkan pengaturan yang dikelola endpoint terpisah, seperti file pengaturan yang dikelola atau profil MDM, ke perangkat setiap grup. Cara Claude Code menggabungkan sumber yang dikelola mengatakan apakah file per-grup atau profil berlaku di perangkat yang juga memiliki sumber organisasi-lebar.
• Tentukan satu kebijakan gateway aplikasi Claude per grup. Gateway menerapkan kebijakan pertama yang aturan kecocokannya sesuai dengan pengguna, jadi urutkan kebijakan sehingga setiap pengguna mencapai kebijakan grup mereka. extraKnownMarketplaces kebijakan grup menggantikan peta kebijakan catch-all daripada menggabungkan dengannya, jadi daftarkan setiap marketplace yang dibutuhkan grup dalam kebijakan grup, bukan hanya marketplace salurannya.

Pengaturan yang dikelola server dari konsol admin berlaku untuk setiap pengguna dalam organisasi Anda, jadi mereka tidak dapat membawa penugasan per-grup.

Contoh

{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}

{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}

Tetapkan saluran ke grup pengguna

Tetapkan setiap marketplace ke grup pengguna melalui pengaturan yang dikelola endpoint per-grup atau kebijakan gateway yang dijelaskan di bawah Siapkan saluran rilis. Misalnya, grup stabil menerima:

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

Grup early-access menerima latest-tools sebagai gantinya:

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

Sematkan versi dependensi

Plugin dapat membatasi dependensinya ke rentang semver sehingga pembaruan dependensi tidak merusak plugin yang bergantung. Lihat Batasi versi dependensi plugin untuk konvensi git-tag {plugin-name}--v{version}, sintaks rentang, dan bagaimana beberapa batasan pada dependensi yang sama digabungkan.

Ubah nama atau hapus plugin

name plugin adalah pengidentifikasi stabilnya. Pengguna mereferensikannya dalam enabledPlugins, pluginConfigs, dan perintah /plugin install, jadi mengubahnya merusak setiap instalasi yang ada. Untuk mengubah label yang ditampilkan di UI tanpa merusak instalasi, atur displayName dan jaga name tetap tidak berubah.

Jika Anda harus mengubah name plugin, atau Anda menghapus plugin dari array plugins, tambahkan entri renames tingkat atas sehingga pengguna yang ada bermigrasi alih-alih melihat kesalahan plugin-not-found. Migrasi otomatis memerlukan Claude Code v2.1.193 atau lebih baru. Petakan setiap nama lama ke nama barunya, atau ke null jika plugin tidak lagi ada. Contoh berikut mengubah nama formatter menjadi code-formatter dan mencatat bahwa legacy-linter dihapus:

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

Ketika pengguna memulai Claude Code dengan nama lama masih dalam pengaturan mereka, Claude Code mengikuti peta renames:

• Jika entri menunjuk ke nama baru, Claude Code memuat plugin dengan nama barunya dan menampilkan pemberitahuan satu baris seperti Renamed to "code-formatter" in the "acme-tools" marketplace. Kemudian menulis ulang kunci lama ke kunci baru dalam cakupan pengaturan pengguna, proyek, dan lokal untuk kedua enabledPlugins dan pluginConfigs, sehingga pemberitahuan muncul sekali.
• Untuk entri null, Claude Code menghapus kunci lama dan pemberitahuan melaporkan bahwa plugin dihapus dari marketplace.
• Jika plugin yang diubah nama menggunakan sumber jarak jauh seperti github atau npm, Claude Code melaporkan plugin-cache-miss setelah pengubahan nama dan pengguna harus menjalankan /plugin install sekali untuk mengambilnya dengan nama baru.

Perlakukan renames sebagai riwayat append-only: jaga entri lama tetap ada bahkan setelah Anda mengharapkan setiap pengguna untuk bermigrasi. Claude Code mengikuti rantai, jadi jika Anda kemudian mengubah nama code-formatter menjadi formatter-pro, tambahkan entri kedua daripada mengedit yang pertama. Pengguna yang masih memiliki formatter asli yang diaktifkan kemudian diselesaikan melalui kedua entri ke formatter-pro.

Jalankan claude plugin validate . setelah mengedit peta; itu menolak entri apa pun yang rantainya membentuk siklus atau tidak berakhir di null atau nama yang terdaftar dalam plugins.

Versi Claude Code sebelumnya mengabaikan field renames dan melaporkan plugin-not-found untuk nama lama.

Validasi dan pengujian

Uji marketplace Anda sebelum berbagi. Validasi memeriksa struktur file; untuk menguji apakah plugin mengubah apa yang Claude lakukan pada prompt realistis, jalankan suite eval-nya dengan claude plugin eval sebelum Anda menerbitkan versi baru.

Dari direktori marketplace Anda, validasi sintaks JSON:

claude plugin validate .

Atau dari dalam Claude Code:

/plugin validate .

Tambahkan marketplace untuk pengujian:

/plugin marketplace add ./path/to/marketplace

Pasang plugin uji untuk memverifikasi semuanya berfungsi:

/plugin install test-plugin@marketplace-name

Untuk alur kerja pengujian plugin lengkap, lihat Uji plugin Anda secara lokal. Untuk troubleshooting teknis, lihat Plugins reference.

Kelola marketplace dari CLI

Claude Code menyediakan subperintah claude plugin marketplace non-interaktif untuk scripting dan otomasi. Ini setara dengan perintah /plugin marketplace yang tersedia dalam sesi interaktif.

Plugin marketplace add

Tambahkan marketplace dari repositori GitHub, URL git, URL jarak jauh, atau jalur lokal.

claude plugin marketplace add <source> [options]

Argumen:

• <source>: Shorthand GitHub owner/repo, URL git, URL jarak jauh ke file marketplace.json, atau jalur direktori lokal. Untuk menyematkan ke branch atau tag, tambahkan @ref ke shorthand GitHub atau #ref ke URL git

URL harus menyertakan skemanya. Mulai dari Claude Code v2.1.196, host yang diketik tanpa skema, seperti gitlab.example.com/team/plugins, ditolak sebagai shorthand owner/repo yang tidak valid dan kesalahan memberi tahu Anda untuk menambahkan https:// atau menggunakan ./ untuk jalur lokal. Versi sebelumnya salah membacanya sebagai jalur repositori GitHub dan gagal saat clone dengan kesalahan GitHub not-found.

Opsi:

Tambahkan marketplace dari GitHub menggunakan shorthand owner/repo:

claude plugin marketplace add acme-corp/claude-plugins

Sematkan ke branch atau tag tertentu dengan @ref:

claude plugin marketplace add acme-corp/claude-plugins@v2.0

Tambahkan dari URL git di host non-GitHub:

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

Tambahkan dari URL jarak jauh yang melayani file marketplace.json secara langsung:

claude plugin marketplace add https://example.com/marketplace.json

Tambahkan dari direktori lokal untuk pengujian:

claude plugin marketplace add ./my-marketplace

Deklarasikan marketplace di scope proyek sehingga dibagikan dengan tim Anda melalui .claude/settings.json:

claude plugin marketplace add acme-corp/claude-plugins --scope project

Untuk monorepo, batasi checkout ke direktori yang berisi konten plugin:

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

Tambahkan marketplace yang dihosting di claude.ai berdasarkan nama yang dicetak di bagian From claude.ai: dari claude plugin marketplace list:

claude plugin marketplace add --claudeai claudeai-organization-library

Dengan --claudeai, perintah menolak --scope dan --sparse. Marketplace dihosting untuk akun Anda, bukan dideklarasikan dalam file pengaturan, jadi Anda tidak dapat membagikannya melalui .claude/settings.json proyek.

Plugin marketplace list

Daftar semua marketplace yang dikonfigurasi.

claude plugin marketplace list [options]

Opsi:

Dengan --json, setiap entri mencakup name, source, bidang installLocation dengan jalur cache lokal tempat marketplace disimpan, dan bidang khusus sumber: repo untuk sumber GitHub, url untuk sumber git dan URL, dan path untuk sumber lokal. Sumber GitHub dan git juga menyertakan bidang ref ketika marketplace ditambahkan dengan branch atau tag yang disematkan.

Marketplace claude.ai yang ditambahkan tidak memiliki clone lokal, jadi entrinya membawa pengidentifikasi claude.ai-nya, marketplaceId dan organizationUuid, sebagai pengganti installLocation.

Dalam sesi terminal di mana plugin disinkronkan dari akun claude.ai Anda, daftar teks berakhir dengan bagian From claude.ai: yang menamai apa yang claude.ai daftarkan untuk akun Anda di luar marketplace yang telah Anda tambahkan. Untuk menambahkan salah satunya, lihat Tambahkan dari claude.ai. Output --json hanya mencakup marketplace yang dikonfigurasi dan meninggalkan bagian tersebut. Memerlukan Claude Code v2.1.273 atau lebih baru.

Plugin marketplace remove

Hapus marketplace yang dikonfigurasi. Alias rm juga diterima.

claude plugin marketplace remove <name> [options]

Argumen:

• <name>: nama marketplace untuk dihapus, seperti yang ditunjukkan oleh claude plugin marketplace list. Ini adalah name dari marketplace.json, bukan sumber yang Anda teruskan ke add

Opsi:

Plugin marketplace update

Segarkan marketplace dari sumbernya untuk mengambil plugin baru dan perubahan versi. Marketplace yang ditambahkan dengan branch atau tag ref diperbarui ke commit terbaru dari ref tersebut, bukan branch default repositori.

claude plugin marketplace update [name]

Argumen:

• [name]: nama marketplace untuk diperbarui, seperti yang ditunjukkan oleh claude plugin marketplace list. Memperbarui semua marketplace jika dihilangkan

Baik remove maupun update gagal ketika dijalankan terhadap marketplace yang dikelola seed, yang bersifat read-only. Saat memperbarui semua marketplace, entri yang dikelola seed dilewati dan marketplace lainnya masih diperbarui. Untuk mengubah plugin yang disediakan seed, minta administrator Anda memperbarui image seed. Lihat Pra-isi plugin untuk container.

Troubleshooting

Marketplace tidak memuat

Gejala: Tidak dapat menambahkan marketplace atau melihat plugin darinya

Solusi:

• Verifikasi URL marketplace dapat diakses
• Periksa bahwa .claude-plugin/marketplace.json ada di jalur yang ditentukan
• Pastikan sintaks JSON valid menggunakan claude plugin validate . atau /plugin validate . dari direktori marketplace. Untuk memeriksa frontmatter skill, agent, dan command, lihat Validate a plugin or a directory without a manifest
• Untuk repositori pribadi, konfirmasi Anda memiliki izin akses

Kesalahan validasi marketplace

Jalankan claude plugin validate . atau /plugin validate . dari direktori marketplace Anda untuk memeriksa masalah. Ketika ditunjukkan ke direktori marketplace, validator memeriksa marketplace.json untuk kesalahan skema, nama plugin duplikat, dan traversal jalur sumber. Untuk setiap entri yang source-nya adalah jalur lokal, validator juga memvalidasi plugin.json plugin tersebut dan memberikan peringatan ketika version entri tidak cocok dengan yang ada di plugin.json. Masalah yang ditemukan dalam plugin.json plugin diawali dengan indeks entri, dalam bentuk plugins[2] plugin.json →.

Mulai dari Claude Code v2.1.196, pass per-entri juga:

• mencakup plugin yang source-nya adalah .
• berjalan ketika marketplace.json berada di luar direktori .claude-plugin, menyelesaikan sumber terhadap direktori file itu sendiri
• melaporkan masalah setiap entri bahkan ketika bagian lain dari file memiliki kesalahan skema

Versi sebelumnya melewati plugin di root marketplace dan hanya turun dari .claude-plugin/marketplace.json.

Dari direktori marketplace, Claude Code tidak membuka file skill, agent, command, atau hook plugin. Untuk menemukan kesalahan dalam file tersebut, lihat Validate a plugin or a directory without a manifest. Tabel di bawah mencantumkan kesalahan paling umum dari direktori marketplace, dengan penyebab dan perbaikan untuk masing-masing:

Peringatan (non-blocking):

• Marketplace has no plugins defined: tambahkan setidaknya satu plugin ke array plugins
• No marketplace description provided: tambahkan description tingkat atas untuk membantu pengguna memahami marketplace Anda
• Plugin name "x" is not kebab-case: ubah nama menjadi huruf kecil, digit, dan tanda hubung saja (misalnya, my-plugin). Claude Code menerima bentuk lain, tetapi sinkronisasi marketplace claude.ai menolaknya.
• Marketplace name "x" is reserved in Claude Desktop: marketplace dinamai org, org-provisioned, atau unknown, dalam huruf besar atau kecil apa pun. Claude Code menerima nama ini, tetapi sinkronisasi marketplace terkelola Claude Desktop menolak seluruh marketplace. Ubah nama marketplace. Sebelum v2.1.221, claude plugin validate tidak menjalankan pemeriksaan ini.
• Marketplace name "x" is not accepted by Claude Desktop atau Plugin name "x" is not accepted by Claude Desktop: Claude Desktop menerima nama hingga 128 karakter yang terdiri dari huruf, digit, ., _, dan -, dimulai dengan huruf atau digit. Claude Code menerima bentuk lain, tetapi sinkronisasi marketplace terkelola Claude Desktop menolak marketplace yang namanya gagal pemeriksaan dan secara diam-diam menghapus entri plugin yang namanya gagal. Ubah nama marketplace atau plugin. Sebelum v2.1.221, claude plugin validate tidak menjalankan pemeriksaan ini.

Validate a plugin or a directory without a manifest

Untuk menemukan file skill, agent, dan command yang frontmatter-nya tidak parse, jalankan claude plugin validate dan beri nama direktori yang menahannya. Claude Code tidak mencari di luar direktori yang Anda beri nama. Setiap run kecuali satu terhadap plugin yang memiliki plugin.json memerlukan Claude Code v2.1.233 atau lebih baru.

Pick the directory to name

Claude Code memeriksa file berbeda tergantung pada direktori mana yang Anda beri nama. Temukan apa yang ingin Anda periksa di kolom pertama, dan jalankan perintah baris itu:

Check a plugin whose skill is its root `SKILL.md`

Ketika Anda menjalankan claude plugin validate terhadap direktori plugin, Claude Code tidak memeriksa SKILL.md di root plugin. Ketika plugin berada di direktori bernama skills, jalankan perintah dua kali:

• Beri nama direktori skills itu untuk memeriksa root SKILL.md plugin.
• Beri nama direktori plugin untuk memeriksa sisanya.

Ketika plugin berada di bawah nama lain, seperti plugins/, run direktori skills tidak tersedia, dan tidak ada run yang memeriksa root SKILL.md-nya.

Check files behind symlinks

Ketika Anda menjalankan claude plugin validate, Claude Code tidak mengikuti symlink di dalam direktori yang Anda beri nama. Apa yang dilakukannya tergantung pada di mana link berada:

• Direktori skills, agents, atau commands yang tertaut di bawah root plugin atau .claude: Claude Code memperingatkan bahwa tidak ada yang di dalamnya yang dibaca.
• Entri tertaut di dalam direktori skills, agents, atau commands: Claude Code melewatinya dan memperingatkan, per direktori, berapa banyak entri yang dilewatinya yang akan dimuat sesi.
• Direktori skills, agents, atau commands yang Anda beri nama adalah symlink itu sendiri, atau direktori .claude induknya adalah: Claude Code melaporkan kesalahan dan tidak memeriksa apa pun di dalamnya. Beri nama direktori nyata sebagai gantinya.

Dalam dua kasus skill, run berlalu dengan peringatan. Untuk memeriksa file tertaut, jalankan lagi dan beri nama direktori yang menahannya secara langsung:

• Plugin yang direktori skills-nya tertaut ke skill plugin sibling: beri nama direktori plugin sibling.
• Entri skill tertaut dalam ~/.claude/skills atau .claude/skills: Claude Code mengikuti entri dalam sesi. Untuk memeriksanya, beri nama direktori bernama skills yang menahannya folder nyata.

Read the validation results

Run yang bersih berakhir dengan Validation passed.

No manifest found in directory berarti Claude Code tidak menemukan plugin.json atau marketplace.json di sana, dan tidak ada file skill, agent, atau command dalam direktori yang diprobnya di bawahnya. Beri nama direktori skills, agents, atau commands yang menahannya file Anda sebagai gantinya.

Dua dari kesalahan yang dilaporkan Claude Code dari run ini, dengan perbaikan untuk masing-masing:

• YAML frontmatter failed to parse: ...: perbaiki YAML dalam blok frontmatter file skill, agent, atau command. Sampai Anda melakukannya, sesi membaca tidak ada field frontmatter dari file
• Invalid JSON syntax: ... pada hooks/hooks.json: perbaiki sintaks JSON. Sampai Anda melakukannya, sesi memuat plugin tanpa hook dalam file itu. Claude Code melaporkan kesalahan ini hanya dalam run plugin

Dalam run plugin, Claude Code juga memperingatkan tentang CLAUDE.md di root plugin. Untuk jalur yang Anda atur melalui component path fields dalam plugin.json, Claude Code memeriksa bahwa setiap jalur ada tetapi tidak membaca file di sana.

Kegagalan instalasi plugin

Gejala: Marketplace muncul tetapi instalasi plugin gagal

Solusi:

• Verifikasi URL sumber plugin dapat diakses
• Periksa bahwa direktori plugin berisi file yang diperlukan
• Untuk sumber GitHub, pastikan repositori publik atau Anda memiliki akses
• Uji sumber plugin secara manual dengan mengklon/mengunduh
• Jika sumber menentukan baik ref maupun sha, cabang atau tag upstream yang dihapus tidak memblokir instalasi pada sebagian besar host git, termasuk GitHub, GitLab, dan Bitbucket. Pada server yang tidak mendukung pengambilan commit berdasarkan SHA, seperti AWS CodeCommit, ref masih harus ada dan commit yang ditentukan harus dapat dijangkau darinya. Jika instalasi masih gagal, konfirmasi commit yang ditentukan masih ada di repositori

Autentikasi repositori pribadi gagal

Gejala: Kesalahan autentikasi saat memasang plugin dari repositori pribadi

Solusi:

Untuk instalasi manual dan pembaruan:

• Verifikasi Anda diautentikasi dengan penyedia git Anda (misalnya, jalankan gh auth status untuk GitHub)
• Periksa bahwa helper kredensial Anda dikonfigurasi: git config --global credential.helper
• Jalankan git ls-remote <marketplace-url> untuk menguji apakah git dapat diautentikasi sendiri. Jika git meminta nama pengguna atau kata sandi, simpan kredensial terlebih dahulu: untuk GitHub melalui HTTPS, jalankan gh auth setup-git, dan untuk remote SSH, muat kunci Anda ke ssh-agent

Untuk pembaruan otomatis latar belakang:

• Pemeriksaan latar belakang menggunakan helper kredensial git yang dikonfigurasi tetapi tidak pernah meminta, jadi helper Anda harus dapat menjawab dengan kredensial yang disimpan. Remote SSH dengan kunci yang dimuat di ssh-agent juga diautentikasi
• Jika helper Anda perlu meminta Anda, pembaruan latar belakang gagal diam-diam dan klon yang ada tetap di tempat. Masuk ke helper Anda terlebih dahulu sehingga menyimpan kredensial untuk host. Untuk GitHub, jalankan gh auth login, kemudian gh auth setup-git
• Ketika pemeriksaan menemukan commit baru, atau tidak dapat menjangkau atau diautentikasi ke remote, Claude Code me-re-clone marketplace dengan kredensial yang sama. Re-clone mungkin time out pada repositori besar
• Atur CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 untuk menyimpan klon yang ada tanpa mencoba re-clone ketika pemeriksaan latar belakang tidak dapat menjangkau atau diautentikasi ke remote
• Jika re-clone time out pada repositori besar, tingkatkan batas dengan CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS
• Atau perbarui marketplace pribadi secara manual dengan /plugin marketplace update <name>, yang menggunakan kredensial Anda

Sebelum v2.1.280, pemeriksaan latar belakang berjalan tanpa helper kredensial git Anda dan tidak dapat diautentikasi ke repositori pribadi melalui HTTPS.

Pembaruan marketplace gagal di lingkungan offline

Gejala: Di lingkungan offline atau airgapped, penyegaran marketplace latar belakang tidak dapat menjangkau remote dan Claude Code berulang kali mencoba re-clone yang tidak dapat berhasil.

Penyebab: Penyegaran latar belakang memeriksa remote marketplace untuk commit baru, dan ketika pemeriksaan tidak dapat menjangkau remote, Claude Code mencoba mengklon marketplace lagi. Offline, klon gagal dengan cara yang sama dan klon yang ada tetap di tempat. Sebelum v2.1.274, penyegaran menjalankan git pull dalam klon yang ada, memindahkan klon ke samping untuk re-clone ketika pull gagal, dan memulihkannya sesudahnya dengan basis best-effort.

Penyegaran berjalan di latar belakang setelah startup, sehingga tidak menunda startup. Setiap sesi masih mengulangi upaya yang gagal, dan setiap operasi git dapat menunggu timeout 120 detik.

Solusi: Atur CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 untuk melewati upaya re-clone dan terus menggunakan klon yang ada ketika pemeriksaan tidak dapat menjangkau remote:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

Untuk deployment yang sepenuhnya offline di mana repositori tidak akan pernah dapat dijangkau, gunakan CLAUDE_CODE_PLUGIN_SEED_DIR untuk pra-isi direktori plugin saat waktu build sebagai gantinya.

Operasi Git time out

Gejala: Instalasi plugin atau pembaruan marketplace gagal dengan kesalahan timeout seperti Git clone timed out after 120s.

Penyebab: Claude Code menggunakan timeout 120 detik untuk semua operasi git, termasuk mengklon repositori plugin dan me-re-clone marketplace untuk memperbaruinya. Repositori besar atau koneksi jaringan lambat mungkin melebihi batas ini.

Solusi: Tingkatkan timeout menggunakan variabel lingkungan CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS. Nilainya dalam milidetik:

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 minutes

Plugin dengan jalur relatif gagal di marketplace berbasis URL

Gejala: Menambahkan marketplace melalui URL seperti https://example.com/marketplace.json, tetapi plugin dengan sumber jalur relatif seperti "./plugins/my-plugin" gagal dipasang dengan its marketplace entry path does not stay inside the marketplace directory. Plugin yang sudah dipasang gagal dimuat dengan Plugin source path refused. Kedua pesan memiliki entri referensi kesalahan.

Penyebab: Menambahkan marketplace berbasis URL hanya mengunduh file marketplace.json itu sendiri, dan Claude Code tidak mengambil file plugin berdasarkan jalur relatif dari server itu. Jalur relatif dalam entri marketplace mereferensikan file di server jarak jauh yang tidak diunduh.

Solusi:

• Gunakan sumber eksternal: ubah entri plugin ke plugin source apa pun selain jalur relatif:

  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  

• Gunakan marketplace berbasis Git: Host marketplace Anda di repositori Git dan tambahkan dengan URL git. Marketplace berbasis Git mengklon seluruh repositori, membuat jalur relatif berfungsi dengan benar.

File tidak ditemukan setelah instalasi

Gejala: Plugin dipasang tetapi referensi ke file gagal, terutama file di luar direktori plugin

Penyebab: Claude Code menyalin plugin yang dipasang ke direktori cache, kecuali plugin dimuat di tempat. command source dalam link mode dimuat di tempat, begitu juga relative path source dalam marketplace yang ditambahkan dari direktori lokal. Jalur yang mereferensikan file di luar direktori plugin yang disalin (seperti ../shared-utils) tidak akan berfungsi karena file tersebut tidak disalin.

Solusi: Lihat Plugin caching and file resolution untuk solusi termasuk symlink dan restruktur direktori.

Untuk alat debugging tambahan dan masalah umum, lihat Debugging and development tools.

Lihat juga

• Temukan dan pasang plugin yang sudah dibuat - Memasang plugin dari marketplace yang ada
• Plugins - Membuat plugin Anda sendiri
• Plugins reference - Spesifikasi teknis lengkap dan skema
• Plugin settings - Opsi konfigurasi plugin
• strictKnownMarketplaces reference - Pembatasan marketplace yang dikelola