Claude Code từ zero đến thành thạo · Phần 15 — Plugin và marketplace

Plugin là tầng đóng gói gộp skill, agent, hook và MCP server thành một đơn vị cài đặt được: cấu trúc và manifest, test cục bộ, cài từ marketplace, code intelligence plugin, và cách chuyển cấu hình .claude sẵn có.

SEP 15, 2026 17 MIN READ

Ba phần trước nói về ba cơ chế mở rộng riêng lẻ. Plugin là tầng đóng gói: nó gộp skill, agent, hook và MCP server thành một đơn vị cài đặt được, có version, chia sẻ được giữa các project và với người khác.

Bài này cũng khép lại chặng 3 của series.

Plugin hay cấu hình standalone?

Claude Code hỗ trợ hai cách thêm skill, agent và hook tuỳ biến:

Cách	Tên skill	Hợp với
Standalone (thư mục `.claude/`)	`/hello`	Workflow cá nhân, tuỳ biến riêng project, thử nghiệm nhanh
Plugin (thư mục tự chứa, có `.claude-plugin/plugin.json`)	`/plugin-name:hello`	Chia sẻ với đồng nghiệp, phân phối cho cộng đồng, phát hành có version, tái dùng giữa nhiều project

Bắt đầu bằng cấu hình standalone trong .claude/ để lặp nhanh, rồi chuyển thành plugin khi bạn sẵn sàng chia sẻ.

Tạo plugin đầu tiên

Bước 1 — tạo thư mục. Vị trí không quan trọng ở bước này vì bạn sẽ trỏ Claude Code tới nó bằng --plugin-dir:

mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin

Bước 2 — tạo manifest ở my-first-plugin/.claude-plugin/plugin.json:

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Trường	Mục đích
`name`	Định danh duy nhất và namespace của skill. Skill được thêm tiền tố này, ví dụ `/my-first-plugin:hello`
`description`	Hiện trong plugin manager khi duyệt hoặc cài
`version`	Tuỳ chọn. Nếu đặt, user chỉ nhận cập nhật khi bạn tăng trường này
`author`	Tuỳ chọn. Hữu ích cho việc ghi nhận tác giả

Bước 3 — thêm skill. Skill nằm trong thư mục skills/, mỗi skill là một folder chứa SKILL.md. Tên folder trở thành tên skill, kèm tiền tố namespace của plugin:

mkdir -p my-first-plugin/skills/hello

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

Bước 4 — test. Chạy Claude Code với flag --plugin-dir:

claude --plugin-dir ./my-first-plugin

Rồi thử skill mới:

/my-first-plugin:hello

Chạy /help và mở tab Custom commands để thấy skill của bạn liệt kê dưới namespace của plugin.

Vì sao có namespace? Skill của plugin luôn có namespace để tránh xung đột khi nhiều plugin có skill trùng tên. Muốn đổi tiền tố thì sửa trường name trong plugin.json.

Bước 5 — thêm tham số. Placeholder $ARGUMENTS bắt mọi text user đưa vào sau tên skill:

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

Chạy /reload-plugins để nhận thay đổi. Lưu ý một chỗ gây bối rối: số skill trong bản tóm tắt chỉ đếm thư mục commands/, nên nó báo 0 skills dù skill bạn vừa sửa đã được nạp lại.

Phát triển plugin ngay trong thư mục skills

Thay vì truyền --plugin-dir ở mỗi lần khởi động, bạn giữ plugin trong thư mục skills để Claude Code tự nạp. claude plugin init dựng khung hộ bạn:

claude plugin init my-tool

Lệnh này tạo ~/.claude/skills/my-tool/ với một manifest .claude-plugin/plugin.json và một SKILL.md khởi đầu. Ở phiên kế tiếp nó nạp dưới tên my-tool@skills-dir, không cần marketplace hay bước cài đặt nào.

Cấu trúc plugin

Lỗi hay gặp nhất: đừng đặt commands/, agents/, skills/ hay hooks/ bên trong thư mục .claude-plugin/. Chỉ plugin.json nằm trong .claude-plugin/. Mọi thư mục khác phải ở gốc plugin.

Gốc plugin là thư mục của chính plugin đó — thư mục bạn truyền cho --plugin-dir, hoặc thư mục chứa .claude-plugin/plugin.json. Nó không bao giờ là ~/.claude/.

Thư mục	Vị trí	Mục đích
`.claude-plugin/`	Gốc plugin	Chứa manifest `plugin.json`
`skills/`	Gốc plugin	Skill dạng thư mục `<name>/SKILL.md`
`commands/`	Gốc plugin	Skill dạng file Markdown phẳng. Plugin mới nên dùng `skills/`
`agents/`	Gốc plugin	Định nghĩa agent tuỳ biến
`hooks/`	Gốc plugin	Trình xử lý sự kiện trong `hooks.json`
`.mcp.json`	Gốc plugin	Cấu hình MCP server
`.lsp.json`	Gốc plugin	Cấu hình LSP server cho code intelligence
`monitors/`	Gốc plugin	Cấu hình background monitor trong `monitors.json`
`bin/`	Gốc plugin	File thực thi được thêm vào `PATH` của Bash tool khi plugin bật
`settings.json`	Gốc plugin	Settings mặc định áp khi plugin được bật

Một plugin ship đúng một skill thì đặt SKILL.md trực tiếp ở gốc plugin được, không cần tạo thư mục skills/. Claude Code nạp nó như một skill đơn và dùng trường name trong frontmatter làm tên gọi.

Thêm LSP server — code intelligence

LSP plugin cấp cho Claude code intelligence thời gian thực. Thêm một file .lsp.json:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

User cài plugin của bạn phải tự có binary của language server trên máy. Để xác nhận server khởi động, mở Claude Code với plugin bật rồi kiểm tab Errors của /plugin: một language server fail sẽ hiện ở đó, ví dụ Executable not found in $PATH.

Với các ngôn ngữ phổ biến như TypeScript, Python, Rust thì cài LSP plugin dựng sẵn từ marketplace chính thức. Chỉ tự tạo LSP plugin khi cần ngôn ngữ chưa được phủ.

Thêm background monitor

Background monitor cho plugin của bạn theo dõi log, file, hoặc trạng thái bên ngoài ở nền và thông báo cho Claude khi sự kiện tới. Claude Code tự khởi động mỗi monitor khi plugin hoạt động, nên bạn không cần bảo Claude bắt đầu theo dõi.

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

Mỗi dòng stdout của command được chuyển tới Claude như một notification trong phiên.

Ship settings mặc định

Plugin chứa được settings.json ở gốc để áp cấu hình mặc định khi được bật. Hiện chỉ hai khoá được hỗ trợ: agent và subagentStatusLine.

{
  "agent": "security-reviewer"
}

Đặt agent kích hoạt một trong các custom agent của plugin làm main thread, áp system prompt, giới hạn tool và model của nó. Đây là cách một plugin đổi hẳn cách Claude Code hành xử mặc định khi được bật. Settings từ settings.json thắng phần settings khai trong plugin.json; khoá lạ bị bỏ qua âm thầm.

Test plugin cục bộ

claude --plugin-dir ./my-plugin

Flag này cũng nhận một archive .zip của thư mục plugin. Nạp nhiều plugin cùng lúc bằng cách lặp flag:

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

Khi một plugin --plugin-dir trùng tên với một plugin đã cài từ marketplace, bản cục bộ thắng trong phiên đó. Nhờ vậy bạn test được thay đổi cho một plugin đã cài mà không phải gỡ nó trước. Ngoại lệ: plugin mà managed settings buộc bật hoặc buộc tắt — --plugin-dir không ghi đè được.

Muốn test một plugin đã đóng gói .zip và host ở một URL, ví dụ artifact build của CI, thì dùng --plugin-url. Claude Code tải archive lúc khởi động và nạp cho phiên đó thôi. Nếu không tải được hoặc archive không hợp lệ, nó khởi động không kèm plugin và ghi một lỗi nạp plugin vào tab Errors.

Trong lúc sửa plugin, chạy /reload-plugins để nhận cập nhật mà không cần khởi động lại. Nó nạp lại plugin, skill, agent, hook, MCP server và LSP server của plugin. Rồi kiểm từng thành phần:

Thử skill bằng /plugin-name:skill-name
Kiểm agent có xuất hiện trong /context dưới Custom Agents, hoặc @-mention một cái bằng tên có scope
Kích hoạt đúng sự kiện mà mỗi hook khớp rồi xác nhận tác dụng của nó. Claude Code ghi lại hook nào khớp, exit code và output của chúng trong debug log

Khi plugin không chạy như mong đợi

Kiểm cấu trúc — các thư mục phải ở gốc plugin, không nằm trong .claude-plugin/
Test từng thành phần riêng — kiểm từng skill, agent, hook một
Dùng công cụ validate và debug — claude plugin validate ./your-plugin

Nếu skill của plugin không xuất hiện, xoá cache rồi cài lại:

rm -rf ~/.claude/plugins/cache

Cài plugin từ marketplace

Marketplace là một catalog plugin do người khác tạo và chia sẻ. Dùng nó là quy trình hai bước: thêm marketplace (đăng ký catalog, chưa cài gì), rồi cài từng plugin bạn muốn.

Claude Code thêm marketplace chính thức của Anthropic (claude-plugins-official) tự động ở lần đầu bạn khởi động nó ở chế độ tương tác. Nếu không thêm được — ví dụ mạng chặn tải, hoặc một marketplace policy đã chặn lần thử trước — thì tự thêm:

/plugin marketplace add anthropics/claude-plugins-official

Cài một plugin từ đó:

/plugin install github@claude-plugins-official

Bốn nguồn marketplace

Nguồn	Cách thêm
GitHub repo	`/plugin marketplace add anthropics/claude-code` (dạng `owner/repo`)
Git URL bất kỳ	`/plugin marketplace add https://gitlab.com/company/plugins.git`
Đường dẫn cục bộ	`/plugin marketplace add ./my-marketplace`
Remote URL	`/plugin marketplace add https://example.com/marketplace.json`

Ba chi tiết về hậu tố .git đáng nhớ vì chúng gây lỗi hay gặp:

github.com và gitlab.com — nhận cả có và không có hậu tố .git.
Azure DevOps — bỏ hậu tố. Claude Code clone mọi URL có /_git/ trong path; thêm .git vào path /_git/ thì clone fail.
Mọi host khác, gồm cả GitLab self-managed — phải có hậu tố .git, nếu không Claude Code coi URL là link trực tiếp tới một file marketplace.json được host.

Luôn kèm tiền tố https://. Thêm branch hoặc tag cụ thể bằng cách nối # rồi tên ref: ...plugins.git#v1.0.0.

Dùng SSH cũng được: git@gitlab.com:company/plugins.git. Claude Code clone địa chỉ SSH bất kể có hậu tố .git hay không.

Viết tắt: dùng /plugin market thay cho /plugin marketplace, và rm thay cho remove.

Menu `/plugin` và ba scope cài đặt

/plugin mở một giao diện bốn tab, chuyển qua lại bằng Tab và Shift+Tab:

Discover — duyệt plugin khả dụng từ mọi marketplace của bạn
Installed — xem và quản lý plugin đã cài
Marketplaces — thêm, xoá, cập nhật marketplace
Errors — xem lỗi nạp plugin

Chọn một plugin để xem chi tiết. Pane chi tiết cho biết plugin chứa gì và nó tốn gì:

Context cost — ước lượng số token plugin thêm vào context window ở mọi lượt
Last updated — ngày cập nhật cuối
Will install — liệt kê command, agent, skill, hook, MCP và LSP server của plugin, để bạn review đúng thứ nó thêm vào trước khi cài

Ba scope cài đặt:

Scope	Nghĩa
User	Cài cho bạn, ở mọi project
Project	Cài cho mọi collaborator của repo này — thêm plugin vào `.claude/settings.json`
Local	Cài cho bạn, chỉ trong repo này

Bạn cũng có thể thấy plugin scope managed — do quản trị viên cài qua managed settings và không sửa được.

Sau khi cài: nó đã hoạt động chưa?

Đọc bản tóm tắt cài đặt, nó nói thẳng:

Plugin is now active. — Claude Code đã kích hoạt plugin ngay trong lúc cài, không cần làm gì thêm.
Run /reload-plugins to activate. — plugin chưa hoạt động, vì kích hoạt nó sẽ huỷ prompt cache (xem phần 3), hoặc vì lần thử kích hoạt đã fail. Chạy lệnh đó.
Nếu plugin fail khi nạp, bản tóm tắt báo lỗi và tab Errors hiện chi tiết.

Khi /reload-plugins sẽ huỷ prompt cache, lệnh cảnh báo rồi bỏ qua cho tới khi bạn chạy lại với --force.

Reload có chi phí token ở request kế tiếp: thành phần mới nạp tự giới thiệu trong nội dung nối vào hội thoại, còn lịch sử cũ vẫn đọc từ prompt cache. Một plugin cung cấp MCP server tốn nhiều hơn khi tool của nó không được hoãn bởi tool search — khi đó thay đổi huỷ cache và request kế tiếp đọc lại toàn bộ hội thoại.

Quản lý plugin đã cài

/plugin list
/plugin disable plugin-name@marketplace-name
/plugin enable plugin-name@marketplace-name
/plugin uninstall plugin-name@marketplace-name

Trong tab Installed, danh sách được nhóm theo scope và sắp để bạn thấy vấn đề trước: plugin có lỗi nạp hoặc dependency chưa giải quyết lên đầu, rồi tới plugin bạn đánh dấu yêu thích, còn plugin đã tắt bị gập lại dưới cùng. Bấm f để đánh dấu yêu thích, gõ để lọc, Enter để mở chi tiết.

Một tính năng đáng dùng: Claude Code liệt kê các plugin bạn tự cài nhưng chưa dùng trong ít nhất hai tuần, qua ít nhất 10 phiên, dưới nhãn Not used recently. Dùng nó để tìm plugin vẫn tốn chi phí khởi động và context dù bạn không còn dùng, rồi tắt hoặc gỡ.

Hai loại plugin không bao giờ bị liệt là không dùng: plugin do tổ chức quản lý hoặc bạn nạp bằng --plugin-dir; và plugin đóng góp theme, output style, monitor hoặc workflow — vì chúng có giá trị mà không cần một lần gọi nào để đếm.

Xoá một marketplace sẽ gỡ mọi plugin bạn đã cài từ nó.

Tự động cập nhật

Claude Code cập nhật marketplace và plugin đã cài ở nền sau khi phiên khởi động, với một khoảng chờ ngẫu nhiên tới mười phút — nên phiên đang chạy vẫn dùng version nó nạp lúc launch. Nếu có plugin được cập nhật, bạn thấy thông báo nhắc chạy /reload-plugins.

Marketplace chính thức của Anthropic bật auto-update mặc định. Marketplace của bên thứ ba và marketplace phát triển cục bộ thì tắt mặc định.

Muốn giữ auto-update cho plugin nhưng tắt auto-update của Claude Code:

export DISABLE_AUTOUPDATER=1
export FORCE_AUTOUPDATE_PLUGINS=1

Marketplace chính thức có gì

Code intelligence

Nhóm plugin này bật LSP tool dựng sẵn của Claude Code. Phải tự cài binary language server trước — plugin không cài hộ bạn.

Ngôn ngữ	Plugin	Binary cần có
C/C++	`clangd-lsp`	`clangd`
C#	`csharp-lsp`	`csharp-ls`
Go	`gopls-lsp`	`gopls`
Java	`jdtls-lsp`	`jdtls`
Kotlin	`kotlin-lsp`	`kotlin-language-server`
Lua	`lua-lsp`	`lua-language-server`
PHP	`php-lsp`	`intelephense`
Python	`pyright-lsp`	`pyright-langserver`
Rust	`rust-analyzer-lsp`	`rust-analyzer`
Swift	`swift-lsp`	`sourcekit-lsp`
TypeScript	`typescript-lsp`	`typescript-language-server`

Claude được hai năng lực từ nhóm plugin này:

Chẩn đoán tự động — sau mọi lần Claude sửa file, language server báo lỗi và warning về, nên Claude thấy type error, import thiếu và lỗi cú pháp mà không cần chạy compiler hay linter. Nếu Claude gây ra lỗi, nó nhận ra và sửa ngay trong cùng lượt.
Điều hướng code — nhảy tới định nghĩa, tìm reference, lấy type info khi hover, liệt kê symbol, tìm implementation, truy vết call hierarchy. Chính xác hơn hẳn tìm kiếm bằng grep.

Bấm Ctrl+O khi Claude Code hiện chỉ báo kiểu Found 3 new diagnostic issues in 2 files để tự đọc chúng.

Ba vấn đề hay gặp: language server không khởi động → kiểm binary đã cài và có trong $PATH, xem tab Errors. Ngốn bộ nhớ → rust-analyzer và pyright tiêu tốn đáng kể trên project lớn; tắt plugin bằng /plugin disable <plugin-name> và dựa vào tool tìm kiếm dựng sẵn. False positive trong monorepo → language server có thể báo lỗi import không giải được cho package nội bộ; những lỗi này không ảnh hưởng khả năng sửa code của Claude.

Tích hợp bên ngoài

Nhóm plugin đóng gói sẵn MCP server để bạn khỏi phải cấu hình tay:

Source control — github, gitlab
Quản lý project — atlassian (Jira/Confluence), asana, linear, notion
Thiết kế — figma
Hạ tầng — vercel, firebase, supabase
Giao tiếp — slack
Monitoring — sentry

Ba nhóm còn lại

Review bảo mật tự động — plugin security-guidance review từng thay đổi Claude thực hiện để tìm lỗ hổng phổ biến và chỉ dẫn Claude sửa ngay trong phiên đó.

Workflow phát triển — commit-commands (quy trình git commit, push, tạo PR), pr-review-toolkit (các agent chuyên review PR), agent-sdk-dev, plugin-dev.

Output style — explanatory-output-style (giải thích các lựa chọn cài đặt), learning-output-style (chế độ học tương tác).

Marketplace cộng đồng

Marketplace cộng đồng chứa plugin của bên thứ ba đã qua validate tự động và sàng lọc an toàn của Anthropic. Mỗi plugin được ghim vào một commit SHA cụ thể. Khác marketplace chính thức, bạn phải tự thêm nó:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install <plugin-name>@claude-community

Plugin và marketplace là thành phần được tin cậy rất cao — chúng thực thi được code bất kỳ trên máy bạn với quyền của chính bạn. Chỉ cài plugin và thêm marketplace từ nguồn bạn tin. Anthropic không kiểm soát MCP server, file hay software nào nằm trong plugin và không xác minh được chúng hoạt động đúng ý. Tổ chức giới hạn được marketplace nào user thêm được bằng managed marketplace restrictions.

Marketplace cho team

Admin của team thiết lập được việc tự động thêm marketplace cho project bằng cách thêm cấu hình vào .claude/settings.json. Một khi thành viên tin tưởng thư mục repo, Claude Code thêm các marketplace này không hỏi thêm lần nào:

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

Nhưng lưu ý một luật bảo mật quan trọng: thêm marketplace không tự cài plugin đến từ nguồn bên ngoài. Một plugin chỉ được .claude/settings.json của project bật, và đến từ nguồn ngoài như một GitHub repo, sẽ không nạp tới khi thành viên tự cài nó. Tới lúc đó Claude Code báo plugin chưa được cài và hiện lệnh claude plugin install cần chạy.

Chuyển cấu hình `.claude/` sẵn có thành plugin

Nếu bạn đã có skill hoặc hook trong .claude/, chuyển chúng thành plugin để dễ chia sẻ.

1. Tạo cấu trúc plugin cạnh thư mục .claude/ hiện có, để các đường dẫn cp tương đối ở bước sau giải đúng:

mkdir -p my-plugin/.claude-plugin

{
  "name": "my-plugin",
  "description": "Migrated from standalone configuration",
  "version": "1.0.0"
}

2. Copy file sẵn có. Bạn có thể không có cả ba thư mục; thiếu cái nào thì cp in No such file or directory và không copy gì, cứ bỏ qua:

cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

3. Chuyển hook. Tạo my-plugin/hooks/hooks.json và copy nguyên object hooks từ .claude/settings.json — định dạng giống nhau:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
          }
        ]
      }
    ]
  }
}

4. Test bằng claude --plugin-dir ./my-plugin, rồi kiểm từng thành phần.

Chuyển rồi thì gì thay đổi

Standalone (`.claude/`)	Plugin
Chỉ dùng được trong một project	Chia sẻ được qua marketplace
File ở `.claude/commands/`	File ở `plugin-name/commands/`
Hook trong `settings.json`	Hook trong `hooks/hooks.json`
Phải copy tay để chia sẻ	Cài bằng `/plugin install`

Sau khi chuyển, xoá file gốc khỏi .claude/ để tránh trùng. Định nghĩa agent ở .claude/agents/ cấp project và user ghi đè agent trùng tên của plugin, nên bản trong plugin chỉ có hiệu lực khi bản gốc đã bị xoá. Còn skill của plugin có namespace /plugin-name:skill-name, nên cả /skill-name gốc lẫn bản trong plugin đều tồn tại song song, không cái nào ghi đè cái nào.

Chia sẻ và phát hành

Khi plugin sẵn sàng: thêm một README.md với hướng dẫn cài và dùng; chọn chiến lược đánh version; tạo hoặc dùng một marketplace để phân phối; và để đồng nghiệp test trước khi phát hành rộng. Muốn giữ plugin nội bộ trong team thì host marketplace ở một private repository.

Anthropic duy trì hai marketplace công khai: claude-plugins-official (do Anthropic tuyển chọn, không có quy trình đăng ký, việc đưa vào là quyết định của Anthropic) và claude-community (nơi bài gửi của bên thứ ba xuất hiện sau khi được review).

Trước khi gửi, chạy validate cục bộ:

claude plugin validate ./your-plugin

Pipeline review chạy đúng kiểm tra này cho mọi bài gửi, cộng thêm sàng lọc an toàn tự động. Khi validate pass, Claude Code in ✔ Validation passed, hoặc ✔ Validation passed with warnings nếu có cảnh báo. Cảnh báo không làm fail validate; thêm --strict để coi chúng là lỗi.

Hết chặng mở rộng năng lực

Năm phần 11–15 đã phủ toàn bộ tầng mở rộng: cách chọn cơ chế (11), skill (12), hook (13), MCP (14), và plugin (15).

Chặng 4 chuyển sang nhiều agent làm việc cùng lúc: subagent và agent view (phần 16), agent team cùng worktree (phần 17), và dynamic workflow (phần 18).

Nguồn

Docs gốc cập nhật thường xuyên; khi có mâu thuẫn, tin bản tiếng Anh.