Buat dan distribusikan marketplace plugin

​

Ikhtisar

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.

​

Panduan: buat marketplace lokal

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

​

Buat file marketplace

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

​

Entri plugin

​

Field yang diperlukan

​

Field plugin opsional

​

Plugin sources

​

Jalur relatif

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

​

Repositori GitHub

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

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

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

​

Subdirektori Git

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

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

​

Paket npm

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

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

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

​

Entri plugin lanjutan

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

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

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

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

​

Strict 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)

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

​

Host di layanan git lainnya

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

​

Repositori pribadi

• Atur CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 untuk menyimpan klon yang ada ketika pull latar belakang gagal, alih-alih menghapus dan mengklon ulang. Plugin Anda terus bekerja dari status terakhir yang disinkronkan, dan pembaruan manual dengan /plugin marketplace update masih pull dengan kredensial Anda.
• Konfigurasikan helper kredensial git, misalnya dengan gh auth setup-git untuk GitHub, sehingga fallback pengklonaan ulang dapat mengautentikasi tanpa prompt.

git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

​

Uji secara lokal sebelum distribusi

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

​

Wajibkan marketplace untuk tim Anda

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

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

​

Pra-isi plugin untuk container

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

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

• 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

​

Konfigurasi umum

{
  "strictKnownMarketplaces": []
}

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

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

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

​

Cara pembatasan bekerja

• 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

​

Resolusi versi dan saluran rilis

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

​

Siapkan saluran rilis

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

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

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

​

Sematkan versi dependensi

​

Ubah nama atau hapus plugin

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

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

​

Validasi dan pengujian

claude plugin validate .

/plugin validate .

/plugin marketplace add ./path/to/marketplace

/plugin install test-plugin@marketplace-name

​

Kelola marketplace dari CLI

​

Plugin marketplace add

claude plugin marketplace add <source> [options]

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

claude plugin marketplace add acme-corp/claude-plugins

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

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

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

claude plugin marketplace add ./my-marketplace

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

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

​

Plugin marketplace list

claude plugin marketplace list [options]

​

Plugin marketplace remove

claude plugin marketplace remove <name> [options]

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

​

Plugin marketplace update

claude plugin marketplace update [name]

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

​

Troubleshooting

​

Marketplace tidak memuat

• 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

• 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

• 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

• 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

• 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

• Secara default, penyegaran latar belakang menonaktifkan helper kredensial git untuk pull, sehingga pull tidak dapat diautentikasi melalui HTTPS. Remote SSH dengan kunci yang dimuat di ssh-agent masih diautentikasi. Pull yang gagal memicu re-clone dari awal, yang menggunakan kredensial tersimpan Anda tetapi mungkin time out pada repositori besar
• Atur CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 untuk menyimpan klon yang ada ketika pull latar belakang gagal
• Konfigurasikan helper kredensial git, misalnya gh auth setup-git, sehingga fallback re-clone dapat diautentikasi
• Jika re-clone time out pada repositori besar, tingkatkan batas dengan CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS
• Konfigurasikan rewrite URL git yang dibatasi pada repositori marketplace sehingga pull latar belakang diautentikasi secara langsung
• Atau perbarui marketplace pribadi secara manual dengan /plugin marketplace update <name>, yang menggunakan kredensial Anda

​

Pembaruan marketplace gagal di lingkungan offline

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

​

Operasi Git time out

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 minutes

​

Plugin dengan jalur relatif gagal di marketplace berbasis URL

• 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

​

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