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"
}

{
"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, dan relevance.

Field yang diperlukan

Field plugin opsional

Field metadata standar:

Field konfigurasi komponen:

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.

Setelah Claude Code mengklon atau mengunduh plugin ke mesin lokal, plugin disalin ke cache plugin lokal yang tersimpan di ~/.claude/plugins/cache.

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.

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/. Dalam contoh di atas, ./plugins/my-plugin 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.

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

Plugin yang didistribusikan sebagai paket npm dipasang menggunakan npm install. Ini berfungsi dengan paket apa pun di registry npm publik atau registry pribadi yang dihosting tim Anda.

{
  "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"
  }
}

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.
• ${CLAUDE_PLUGIN_ROOT}: Gunakan variabel ini dalam hooks dan config MCP server untuk mereferensikan file dalam direktori instalasi plugin. Ini diperlukan karena plugin disalin ke lokasi cache saat dipasang. 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

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. Untuk instalasi manual dan pembaruan, 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.

Pembaruan otomatis latar belakang berjalan saat startup tanpa helper kredensial, karena prompt interaktif akan memblokir Claude Code dari startup. Untuk mengaktifkan pembaruan otomatis untuk marketplace pribadi, atur token autentikasi yang sesuai di lingkungan Anda:

Atur token dalam konfigurasi shell Anda (misalnya, .bashrc, .zshrc) atau teruskan saat menjalankan Claude Code:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Uji secara lokal sebelum distribusi

Uji marketplace Anda secara lokal sebelum berbagi:

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

Untuk rangkaian lengkap perintah add (GitHub, URL Git, jalur lokal, URL jarak jauh), lihat Tambahkan marketplace.

Wajibkan marketplace untuk tim Anda

Anda dapat mengonfigurasi repositori Anda sehingga anggota tim secara otomatis diminta untuk memasang marketplace Anda ketika mereka mempercayai folder proyek. 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: direktori seed tidak pernah ditulis. Pembaruan otomatis dinonaktifkan untuk marketplace seed karena git pull akan gagal di filesystem read-only.
• 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.

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

Konfigurasi umum

Nonaktifkan semua penambahan marketplace:

{
  "strictKnownMarketplaces": []
}

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 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.

Daftar izin menggunakan pencocokan tepat untuk sebagian besar jenis sumber. Agar marketplace diizinkan, semua field yang ditentukan harus cocok secara tepat:

• Untuk sumber GitHub: repo diperlukan, dan ref atau path juga harus cocok jika ditentukan dalam daftar izin
• 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 tidak menormalkan URL: garis miring trailing, akhiran .git, atau bentuk ssh:// versus https:// diperlakukan sebagai nilai berbeda. Jika marketplace organisasi Anda dapat diklon oleh lebih dari satu bentuk URL, lebih suka entri hostPattern daripada URL literal sehingga semua bentuk cocok.

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.

Claude Code menyelesaikan versi plugin dari yang pertama dari ini yang diatur:

1. version dalam plugin.json plugin
2. version dalam entri marketplace plugin
3. SHA commit git dari sumber plugin

Untuk jenis sumber berbasis git github, url, git-subdir, dan jalur relatif di dalam marketplace yang dihosting git, Anda dapat menghilangkan version sepenuhnya dan setiap commit baru diperlakukan sebagai versi baru. Ini adalah setup paling sederhana untuk plugin internal atau yang sedang dikembangkan secara aktif.

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 menetapkan dua marketplace ke grup pengguna berbeda melalui pengaturan yang dikelola.

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 yang sesuai melalui pengaturan yang dikelola. 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 sintaks JSON marketplace Anda:

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

Plugin marketplace list

Daftar semua marketplace yang dikonfigurasi.

claude plugin marketplace list [options]

Opsi:

Dengan --json, setiap entri mencakup name, source, 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.

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.

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. Untuk memeriksa frontmatter skill, agent, dan command, jalankan perintah terhadap setiap direktori plugin
• 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.

Untuk memvalidasi plugin.json plugin individual dan file skill, agent, command, dan hook-nya, jalankan perintah terhadap direktori plugin itu sendiri, misalnya claude plugin validate ./plugins/my-plugin. Kesalahan umum:

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: nama plugin berisi huruf besar, spasi, atau karakter khusus. Ubah nama menjadi huruf kecil, digit, dan tanda hubung saja (misalnya, my-plugin). Claude Code menerima bentuk lain, tetapi sinkronisasi marketplace claude.ai menolaknya.

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 dengan benar: git config --global credential.helper
• Coba klon repositori secara manual untuk memverifikasi kredensial Anda berfungsi

Untuk pembaruan otomatis latar belakang:

• Atur token yang sesuai di lingkungan Anda: echo $GITHUB_TOKEN
• Periksa bahwa token memiliki izin yang diperlukan (akses baca ke repositori)
• Untuk GitHub, pastikan token memiliki scope repo untuk repositori pribadi
• Untuk GitLab, pastikan token memiliki setidaknya scope read_repository
• Verifikasi token belum kedaluwarsa

Pembaruan marketplace gagal di lingkungan offline

Gejala: Marketplace git pull gagal dan Claude Code menghapus cache yang ada, menyebabkan plugin menjadi tidak tersedia.

Penyebab: Secara default, ketika git pull gagal, Claude Code menghapus klon yang sudah usang dan mencoba mengklon ulang. Di lingkungan offline atau airgapped, mengklon ulang gagal dengan cara yang sama, meninggalkan direktori marketplace kosong.

Solusi: Atur CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 untuk menyimpan cache yang ada ketika pull gagal alih-alih menghapusnya:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

Dengan variabel ini diatur, Claude Code mempertahankan klon marketplace yang sudah usang pada kegagalan git pull dan terus menggunakan status terakhir yang diketahui baik. 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" atau "Git pull timed out after 120s".

Penyebab: Claude Code menggunakan timeout 120 detik untuk semua operasi git, termasuk mengklon repositori plugin dan menarik pembaruan marketplace. 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 kesalahan "path not found".

Penyebab: Marketplace berbasis URL hanya mengunduh file marketplace.json itu sendiri. Mereka tidak mengunduh file plugin dari server. Jalur relatif dalam entri marketplace mereferensikan file di server jarak jauh yang tidak diunduh.

Solusi:

• Gunakan sumber eksternal: Ubah entri plugin untuk menggunakan sumber GitHub, npm, atau URL git alih-alih 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: Plugin disalin ke direktori cache daripada digunakan di tempat. Jalur yang mereferensikan file di luar direktori plugin (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