Buat dan distribusikan marketplace plugin

​

Ikhtisar

1. Membuat plugin: bangun satu atau lebih plugin dengan commands, 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

​

Buat file marketplace

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "[email protected]"
  },
  "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

​

Metadata 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": "[email protected]"
  },
  "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 commands 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 commands, 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>/...

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

​

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

​

Validasi dan pengujian

claude plugin validate .

/plugin validate .

/plugin marketplace add ./path/to/marketplace

/plugin install test-plugin@marketplace-name

​

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

​

Operasi Git habis waktu

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