Buat dan distribusikan marketplace plugin

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

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
disable-model-invocation: true
---

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

​

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

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

​

Uji secara lokal sebelum distribusi

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

​

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

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

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

​

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>

• <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 dan frontmatter terbentuk dengan baik menggunakan claude plugin validate atau /plugin validate
• Untuk repositori pribadi, konfirmasi Anda memiliki izin akses

​

Kesalahan validasi marketplace

• 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

​

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

• 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

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