Tạo và phân phối plugin marketplace

Một plugin marketplace (chợ plugin) là danh mục cho phép bạn phân phối plugin tới người khác. Marketplace cung cấp discovery tập trung, theo dõi version, tự động cập nhật, và hỗ trợ nhiều loại nguồn (git repository, đường dẫn local…). Trang này hướng dẫn bạn tạo marketplace riêng để chia sẻ plugin cho team hoặc cộng đồng.

Nếu bạn chỉ muốn cài plugin từ marketplace có sẵn, xem Khám phá và cài plugin có sẵn.

Tổng quan

Tạo và phân phối marketplace gồm các bước:

1. Tạo plugin: xây dựng một hoặc nhiều plugin với skill, agent, hook, MCP server, hoặc LSP server.
2. Tạo file marketplace: định nghĩa marketplace.json liệt kê plugin và nguồn của chúng.
3. Host marketplace: push lên GitHub, GitLab, hoặc git host khác.
4. Chia sẻ với user: user thêm marketplace bằng /plugin marketplace add và cài từng plugin.

Sau khi marketplace hoạt động, bạn cập nhật bằng cách push thay đổi lên repository; user refresh bản local bằng /plugin marketplace update.

Walkthrough: tạo marketplace local

Ví dụ này tạo một marketplace với một plugin: skill quality-review cho code review.

1. Tạo cấu trúc thư mục:

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

2. Tạo skill - file SKILL.md:

my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md

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

3. Tạo plugin manifest - file plugin.json trong thư mục .claude-plugin/:

my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json

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

Ghi chú

Đặt version nghĩa là user chỉ nhận update khi bạn đổi giá trị này, nên tăng nó ở mỗi lần release. Nếu bỏ qua version và host marketplace này trên git, mỗi commit tự động tính là một version mới. Xem Version resolution để chọn cách phù hợp.

4. Tạo file marketplace - marketplace.json liệt kê plugin:

my-marketplace/.claude-plugin/marketplace.json

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

5. Thêm và cài: từ thư mục chứa my-marketplace, chạy Claude Code:

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

6. Thử ngay: skill của plugin được namespace theo tên plugin:

/quality-review-plugin:quality-review

Để tìm hiểu thêm về những gì plugin có thể làm (hook, agent, MCP server, LSP server), xem Plugins.

Ghi chú

Cách plugin được cài: khi user cài plugin, Claude Code copy thư mục plugin vào một vị trí cache. Nghĩa là plugin không thể tham chiếu file ngoài thư mục của nó bằng đường dẫn kiểu ../shared-utils, vì các file đó sẽ không được copy theo. Nếu cần chia sẻ file giữa các plugin, dùng symlink.

Tạo file marketplace

Tạo .claude-plugin/marketplace.json ở root repository. File này định nghĩa tên marketplace, thông tin owner, và danh sách plugin kèm nguồn của chúng. Mỗi entry plugin cần tối thiểu name và source.

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

Schema marketplace

Trường bắt buộc

Trường	Kiểu	Mô tả
name	string	Định danh marketplace (kebab-case, không dấu cách). Public-facing - user thấy khi cài plugin (ví dụ /plugin install my-tool@your-marketplace). Mỗi user chỉ đăng ký một marketplace mỗi tên.
owner	object	Thông tin người bảo trì marketplace
plugins	array	Danh sách plugin có sẵn

Chú ý

Các tên marketplace sau được dành riêng cho Anthropic và bên thứ ba không được dùng: claude-code-marketplace, claude-code-plugins, claude-plugins-official, claude-plugins-community, claude-community, anthropic-marketplace, anthropic-plugins, agent-skills, anthropic-agent-skills, knowledge-work-plugins, life-sciences, claude-for-legal, claude-for-financial-services, financial-services-plugins, first-party-plugins, healthcare. Tên bắt chước marketplace chính thức (ví dụ official-claude-plugins) cũng bị chặn. Claude Code kiểm tra lại danh sách tên dành riêng mỗi lần load marketplace, không chỉ khi thêm mới - hãy double-check với version Claude Code bạn đang dùng.

Trường owner

Trường	Kiểu	Bắt buộc	Mô tả
name	string	Có	Tên người/team bảo trì
email	string	Không	Email liên hệ
url	string	Không	Website, GitHub profile, hoặc URL tổ chức

Trường tùy chọn

Trường	Kiểu	Mô tả
$schema	string	URL JSON Schema cho autocomplete/validation ở editor. Claude Code bỏ qua trường này lúc load.
description	string	Mô tả ngắn về marketplace
version	string	Version của manifest marketplace
metadata.pluginRoot	string	Thư mục gốc chèn trước đường dẫn source tương đối của plugin
allowCrossMarketplaceDependenciesOn	array	Các marketplace khác mà plugin trong marketplace này được phép phụ thuộc vào. Xem Constrain plugin dependency versions.
renames	object	Map từ tên plugin cũ sang tên hiện tại (hoặc null nếu đã gỡ). Giúp user hiện tại tự động migrate khi bạn đổi tên/xóa plugin. Yêu cầu Claude Code v2.1.193+.

Entry plugin

Mỗi entry trong mảng plugins mô tả một plugin và nơi tìm nó. Bạn có thể thêm bất kỳ trường nào từ schema plugin manifest (description, version, author, commands, hooks…), cộng thêm các trường riêng của marketplace: source, category, tags, strict, relevance.

Trường bắt buộc

Trường	Kiểu	Mô tả
name	string	Định danh plugin (kebab-case). Public-facing khi cài (/plugin install my-plugin@marketplace).
source	string|object	Nơi lấy plugin (xem Nguồn plugin)

Trường plugin tùy chọn khác

Metadata chuẩn: displayName (tên hiển thị thân thiện, không dùng cho namespacing), description, version, author, homepage, repository, license (SPDX id), keywords, category, tags, strict (mặc định true, xem Strict mode), relevance (tín hiệu gợi ý plugin - xem Recommend plugins for your org), defaultEnabled (mặc định true).

Cấu hình component: skills, commands, agents, hooks, mcpServers, lspServers - có thể là đường dẫn tùy chỉnh hoặc object cấu hình trực tiếp.

Nguồn plugin

Nguồn plugin cho Claude Code biết lấy từng plugin cụ thể ở đâu, khai báo trong trường source của mỗi entry. Sau khi clone/tải, Claude Code copy plugin vào cache local ở ~/.claude/plugins/cache.

Nguồn	Kiểu	Trường	Ghi chú
Đường dẫn tương đối	string ("./my-plugin")	không	Thư mục local trong marketplace repo. Phải bắt đầu bằng ./, resolve theo root marketplace
github	object	repo, ref?, sha?
url	object	url, ref?, sha?	Nguồn git URL
git-subdir	object	url, path, ref?, sha?	Thư mục con trong git repo - clone sparse để tiết kiệm bandwidth cho monorepo
npm	object	package, version?, registry?	Cài qua npm install

Ghi chú

Marketplace source vs plugin source: đây là hai khái niệm khác nhau. Marketplace source là nơi lấy file marketplace.json (đặt khi /plugin marketplace add hoặc trong extraKnownMarketplaces, hỗ trợ ref không hỗ trợ sha). Plugin source là nơi lấy từng plugin cụ thể liệt kê trong marketplace (đặt trong source của entry, hỗ trợ cả ref và sha). Hai loại nguồn này pin độc lập với nhau.

Với các loại nguồn git (github, url, git-subdir), khi cả ref và sha đều được set, sha là giá trị pin thực sự áp dụng. Trên hầu hết git host (GitHub, GitLab, Bitbucket), cài đặt vẫn thành công dù branch/tag ref đã bị xóa ở remote, miễn commit vẫn còn reachable. Một số server (như AWS CodeCommit) không hỗ trợ fetch theo SHA trực tiếp - ref phải vẫn tồn tại.

Đường dẫn tương đối

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

Đường dẫn resolve theo root marketplace (thư mục chứa .claude-plugin/), không dùng ../ để tham chiếu ra ngoài root.

Ghi chú

Đường dẫn tương đối chỉ resolve được khi user thêm marketplace từ nguồn git hoặc thư mục local. Nếu user thêm qua URL trực tiếp tới file marketplace.json, đường dẫn tương đối sẽ không resolve được vì chỉ file đó được tải về. Với phân phối qua URL, dùng nguồn GitHub, npm, hoặc git URL thay thế.

GitHub repository

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

Trường	Kiểu	Mô tả
repo	string	Bắt buộc. Dạng owner/repo
ref	string	Tùy chọn. Branch hoặc tag (mặc định default branch)
sha	string	Tùy chọn. Full 40-ký-tự commit SHA để pin chính xác

Git repository

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

Thư mục con trong git (git-subdir)

Dùng git-subdir để trỏ tới plugin nằm trong thư mục con của một git repo - Claude Code dùng sparse partial clone để chỉ tải thư mục đó, tiết kiệm bandwidth cho monorepo lớn.

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

npm package

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

Strict mode

Trường strict kiểm soát plugin.json có phải là nguồn thẩm quyền (authority) cho định nghĩa component không:

Giá trị	Hành vi
true (mặc định)	plugin.json là authority. Marketplace entry có thể bổ sung thêm component, hai nguồn được merge.
false	Marketplace entry là định nghĩa toàn bộ. Nếu plugin cũng có plugin.json khai báo component, đó là xung đột và plugin sẽ không load được.

Dùng strict: false khi marketplace operator muốn toàn quyền kiểm soát - plugin repo chỉ cung cấp file thô, marketplace entry quyết định file nào trở thành skill/agent/hook.

Host và phân phối marketplace

Host trên GitHub (khuyến nghị)

1. Tạo repository mới cho marketplace.
2. Thêm .claude-plugin/marketplace.json với định nghĩa plugin.
3. Chia sẻ: user thêm bằng /plugin marketplace add owner/repo.

Host trên git service khác

Bất kỳ git hosting nào cũng dùng được (GitLab, Bitbucket, self-hosted). User thêm bằng URL đầy đủ:

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

Repository riêng tư

Claude Code hỗ trợ cài plugin từ repository riêng tư. Khi chạy /plugin marketplace add, /plugin install, /plugin update, Claude Code dùng credential helper git hiện có của bạn (HTTPS qua gh auth login, macOS Keychain, hoặc git-credential-store; SSH cần host đã có trong known_hosts và key đã load vào ssh-agent).

Mặc định, background auto-update tắt credential helper cho git pull, nên không xác thực được với HTTPS (SSH không bị ảnh hưởng). Khi pull nền thất bại, Claude Code fallback bằng re-clone (dùng credential đã lưu, nhưng có thể timeout với repo lớn). Hai cách khắc phục:

• Set CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 để giữ bản clone hiện tại khi pull nền thất bại, thay vì xóa và re-clone.
• Cấu hình git URL rewrite toàn cục để pull nền cũng xác thực được qua HTTPS:

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

Chú ý

Rewrite lưu token dạng plaintext trong gitconfig - dùng token chỉ có quyền đọc, và scope rewrite theo repo/organization cụ thể (rewrite chỉ theo host sẽ áp dụng cho mọi fetch/push tới host đó, kể cả repo khác của bạn).

Test local trước khi phân phối

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

Yêu cầu marketplace bắt buộc cho team

Thêm vào .claude/settings.json để team tự động được nhắc cài marketplace khi trust thư mục dự án:

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

Có thể chỉ định plugin nào enable mặc định:

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

Chuẩn bị sẵn plugin cho container

Với container image và CI, bạn có thể pre-populate thư mục plugin lúc build image để Claude Code khởi động sẵn có marketplace và plugin, không cần clone lúc runtime. Set biến CLAUDE_CODE_PLUGIN_SEED_DIR trỏ tới thư mục này (có thể layer nhiều seed directory, phân cách bằng : trên Unix hoặc ; trên Windows).

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

Để build seed: chạy Claude Code một lần lúc build image, cài các plugin cần, rồi copy ~/.claude/plugins vào image; hoặc set CLAUDE_CODE_PLUGIN_CACHE_DIR trỏ thẳng tới đích lúc build để cài trực tiếp vào đó, khỏi cần copy.

Seed directory là read-only - auto-update bị tắt cho marketplace từ seed. Entry trong seed ghi đè entry trùng khớp trong config của user mỗi lần khởi động; dùng /plugin disable để opt-out một plugin từ seed thay vì gỡ marketplace.

Giới hạn marketplace được quản lý

Với tổ chức cần kiểm soát chặt nguồn plugin, admin có thể giới hạn marketplace user được phép thêm bằng setting strictKnownMarketplaces trong managed settings. Kết hợp với disableSideloadFlags để chặn cả các flag CLI sideload plugin/agent/MCP cho một lần chạy. Dùng pluginSuggestionMarketplaces để allowlist marketplace nào được phép hiện gợi ý cài đặt theo ngữ cảnh.

Giá trị	Hành vi
Không đặt (mặc định)	Không giới hạn - user thêm marketplace bất kỳ
Mảng rỗng []	Khóa hoàn toàn - chặn mọi nguồn marketplace, kể cả marketplace chính thức Anthropic
Danh sách nguồn	User chỉ thêm được marketplace khớp chính xác với allowlist

Ví dụ chỉ cho phép marketplace chính thức Anthropic:

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

Cho phép mọi marketplace từ một git server nội bộ bằng regex trên host (khuyến nghị cho GitHub Enterprise Server hoặc self-hosted GitLab):

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

Ghi chú

strictKnownMarketplaces chỉ giới hạn những gì user được thêm, không tự đăng ký marketplace. Để marketplace được phép có sẵn tự động mà user không cần chạy /plugin marketplace add, kết hợp với extraKnownMarketplaces trong cùng managed-settings.json.

Việc kiểm tra chạy trước mọi thao tác network/filesystem, áp dụng cho cả add, install, update, refresh, và auto-update. Matching là exact match, không normalize URL (dấu / cuối, hậu tố .git, ssh:// vs https:// được coi là khác nhau) - nếu marketplace của bạn có thể clone bằng nhiều dạng URL, ưu tiên dùng hostPattern thay vì URL literal.

Version resolution và release channel

Version plugin quyết định đường dẫn cache và việc phát hiện update: nếu version resolve ra khớp với bản user đang có, /plugin update và auto-update sẽ bỏ qua plugin đó.

Claude Code resolve version theo thứ tự ưu tiên:

1. version trong plugin.json của plugin
2. version trong marketplace entry của plugin
3. Git commit SHA của nguồn plugin

Với các loại nguồn git (github, url, git-subdir, đường dẫn tương đối trong marketplace host trên git), bạn có thể bỏ qua version hoàn toàn và mỗi commit mới được coi là version mới - đơn giản nhất cho plugin nội bộ hoặc đang phát triển tích cực.

Chú ý

Đặt version sẽ pin plugin lại. Nếu plugin.json khai báo "version": "1.0.0", push commit mới mà không đổi string đó sẽ không có tác dụng gì với user hiện tại - Claude Code thấy cùng version và giữ bản cache cũ. Tăng version ở mỗi release, hoặc bỏ qua để dùng commit SHA. Tránh đặt version ở cả plugin.json lẫn marketplace entry cùng lúc - Claude Code luôn ưu tiên giá trị plugin.json mà không cảnh báo.

Để hỗ trợ kênh “stable” và “latest”, set hai marketplace trỏ tới ref/SHA khác nhau của cùng repo, rồi gán chúng cho các nhóm user khác nhau qua managed settings.

Đổi tên hoặc xóa plugin

name của plugin là định danh ổn định - user tham chiếu nó trong enabledPlugins, pluginConfigs, lệnh /plugin install, nên đổi tên sẽ phá vỡ mọi cài đặt hiện có. Muốn đổi nhãn hiển thị mà không phá cài đặt, dùng displayName và giữ nguyên name.

Nếu buộc phải đổi name, hoặc xóa một plugin khỏi mảng plugins, thêm entry renames ở top-level để user hiện tại tự migrate thay vì gặp lỗi plugin-not-found (yêu cầu Claude Code v2.1.193+):

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

Coi renames là lịch sử append-only - giữ nguyên entry cũ ngay cả khi bạn nghĩ mọi user đã migrate. Chạy claude plugin validate . sau khi sửa map này để kiểm tra không có chuỗi rename tạo vòng lặp.

Kiểm tra và test

claude plugin validate .

hoặc trong Claude Code: /plugin validate .. Test marketplace: /plugin marketplace add ./path/to/marketplace rồi /plugin install test-plugin@marketplace-name.

Quản lý marketplace từ CLI

Claude Code cung cấp subcommand claude plugin marketplace non-interactive cho scripting, tương đương lệnh /plugin marketplace trong session tương tác: add <source>, list [--json], remove <name> (alias rm), update [name].

claude plugin marketplace add acme-corp/claude-plugins@v2.0
claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins
claude plugin marketplace list --json
claude plugin marketplace update

Chú ý

Xóa marketplace khỏi scope cuối cùng còn lại cũng gỡ luôn mọi plugin bạn đã cài từ đó. Để refresh marketplace mà không mất plugin đã cài, dùng claude plugin marketplace update thay vì remove rồi add lại.

Khắc phục sự cố

Vấn đề	Nguyên nhân / cách xử lý
Marketplace không load được	Kiểm tra URL truy cập được, .claude-plugin/marketplace.json tồn tại, JSON hợp lệ (claude plugin validate .), quyền truy cập repo riêng tư
Lỗi validation	Chạy claude plugin validate . - báo lỗi schema, tên plugin trùng, path traversal (..), YAML frontmatter sai
Cài plugin thất bại	Kiểm tra source URL truy cập được, repo public/có quyền, thử clone thủ công
Xác thực repo riêng tư thất bại	Kiểm tra gh auth status, git config --global credential.helper, thử git ls-remote <marketplace-url>
Update thất bại ở môi trường offline	Set CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 để giữ cache cũ thay vì re-clone thất bại lặp lại
Timeout thao tác git	Tăng CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS (mặc định 120 giây)
Plugin dùng relative path lỗi trong marketplace qua URL	Marketplace thêm qua URL trực tiếp chỉ tải marketplace.json, không tải file plugin - chuyển sang nguồn GitHub/npm/git URL, hoặc host marketplace trên git
File không tìm thấy sau khi cài	Plugin được copy vào cache, path kiểu ../shared-utils ra ngoài thư mục plugin sẽ không hoạt động - dùng symlink

Xem thêm

• Khám phá và cài plugin có sẵn
• Constrain plugin dependency versions
• Recommend plugins for your org

Nguồn

Dịch và biên soạn từ Create and distribute a plugin marketplace.