Plugin Claude Code là gì, cài ở đâu và tốn bao nhiêu

Plugin Claude Code là gì

Plugin Claude Code là một thư mục chứa các thành phần mà Claude Code tải và quản lý như một đơn vị duy nhất. Các thành phần đó gồm skill, agent, hook, MCP server, LSP server và monitor chạy nền. Khi cài đặt một plugin, tất cả thành phần của plugin được thêm cùng lúc dưới một tên duy nhất. Khi tắt plugin, tất cả thành phần đó cũng được gỡ theo cùng cách.

Plugin không cấp cho agent khả năng nào mà agent chưa có. Mọi thành phần bên trong plugin đều có thể được bạn tự viết trong thư mục .claude/. Plugin chỉ là lớp đóng gói: một cách để version các thành phần đó, cung cấp chúng cho mười lăm người và cập nhật về sau mà không cần yêu cầu mọi người tự sao chép file. Đó là toàn bộ ý tưởng. Phần lớn nhầm lẫn về plugin xuất phát từ việc kỳ vọng chúng là một loại capability mới.

Manifest tùy chọn tại .claude-plugin/plugin.json đặt tên cho plugin, và tên đó trở thành một namespace. Một skill trong plugin có tên commit-commands được gọi bằng /commit-commands:commit. Vì vậy, hai plugin có thể cùng cung cấp một skill tên commit mà không plugin này che khuất plugin kia. Agent của plugin cũng được giới hạn theo cách tương tự trong danh sách @-mention, dưới tên plugin-name:agent-name.

Plugin, skill, MCP server hoặc rules file

Bốn thuật ngữ này thường được dùng như thể chúng cạnh tranh với nhau. Thực tế không phải vậy, và cần phân biệt rõ một lần.

• Skill là một đơn vị instruction mà Claude load khi task yêu cầu. Xem skill của Agent thực sự là gì.
• MCP server là một process riêng, expose các tool cho agent qua một protocol. Thường đây là một network service do bạn tự chạy.
• Rules file như CLAUDE.md là context của project. File này được đọc khi session bắt đầu và áp dụng cho mọi thứ.
• Plugin là một container có thể chứa skill, agent, hook và định nghĩa MCP server, cùng với version number và distribution channel.

Vì vậy, câu hỏi mà một plugin trả lời không phải là “agent có thể làm gì”. Câu hỏi đúng là “làm thế nào để tôi phân phối phần này cho team và update nó vào tháng sau”. Nếu bạn đang chọn giữa ba loại đầu tiên, so sánh skill, MCP server và rules file trình bày chi tiết quyết định này. Nếu bạn quan tâm đến phần MCP, chạy MCP server riêng trên VPS trình bày phần hosting.

Plugin nằm ở đâu và bên trong plugin có gì

Plugin cài từ marketplace được sao chép vào local cache tại ~/.claude/plugins/cache thay vì chạy từ thư mục đã clone. Mỗi version đã cài có một thư mục riêng. Khi bạn update hoặc uninstall, thư mục của version cũ được đánh dấu là orphaned và bị xóa sau khoảng hai tuần. Vì vậy, session đã load version cũ vẫn tiếp tục hoạt động thay vì lỗi giữa chừng.

Vì path thay đổi sau mỗi lần update, plugin không được hardcode vị trí của chính nó. Hooks và MCP config bên trong plugin dùng ${CLAUDE_PLUGIN_ROOT}. Giá trị này trỏ đến thư mục cài đặt hiện tại. State cần tồn tại sau khi update phải đặt trong ${CLAUDE_PLUGIN_DATA}. Giá trị này trỏ đến một thư mục ổn định bên dưới ~/.claude/plugins/data/.

Chỉ thư mục riêng của plugin được sao chép vào cache. Điều này gây ra một lỗi thường chỉ phát hiện ở giai đoạn sau. Path trỏ ra ngoài plugin root, chẳng hạn ../shared-utils, vẫn hoạt động khi bạn phát triển bằng local path nhưng sẽ lỗi sau khi cài đặt vì các file đó không được sao chép.

Cấu trúc thư mục như sau.

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
├── .mcp.json
└── bin/

Chỉ plugin.json được đặt bên trong .claude-plugin/. Mọi thứ khác nằm ở plugin root. Đặt skills/ hoặc hooks/ bên trong .claude-plugin/ là lý do phổ biến nhất khiến plugin cài đặt thành công nhưng sau đó hoàn toàn không làm gì: Claude Code tìm các thư mục đó ở root nhưng không thấy, rồi load một plugin không có component.

Manifest cũng rất nhỏ.

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

Cách cài plugin Claude Code

Cài đặt gồm 2 bước, và bước đầu tiên chưa cài gì cả. Bạn thêm một marketplace, tức catalog chứa các plugin, rồi cài từng plugin từ marketplace đó. Marketplace chính thức của Anthropic, claude-plugins-official, được đăng ký tự động cho bạn khi lần đầu khởi động Claude Code ở chế độ tương tác. Các marketplace khác bạn phải tự thêm.

/plugin marketplace add anthropics/claude-code
/plugin install commit-commands@claude-code-plugins

Lưu ý repository là anthropics/claude-code, còn marketplace có tên claude-code-plugins. Tên này lấy từ file catalog bên trong repository, không lấy từ đường dẫn repository. Vì vậy, hãy đọc tên marketplace trong tab Marketplaces của /plugin trước khi nhập lệnh cài đặt.

Sau khi cài đặt, hãy đọc dòng tóm tắt. Plugin is now active. nghĩa là các component đã được load trong session hiện tại. Run /reload-plugins to activate. nghĩa là chúng chưa được load và bạn cần chạy lệnh đó. Nếu /reload-plugins cảnh báo rằng lệnh sẽ đọc lại conversation, hãy chạy lại lệnh đó dưới dạng /reload-plugins --force. Sau đó xác nhận plugin thực sự đã có: /plugin hiển thị plugin trong tab Installed, /help liệt kê các skill của plugin trong Custom commands, còn mọi thành phần load thất bại sẽ xuất hiện trong tab Errors cùng với nguyên nhân.

Khi cài đặt, bạn phải chọn scope. Scope quyết định ai được dùng plugin. User scope là bạn, trong mọi project. Project scope ghi plugin vào .claude/settings.json của repository, bên dưới enabledPlugins, nên mọi người clone repository sẽ được đề xuất cài plugin đó. Local scope là bạn, chỉ trong repository hiện tại.

Với script, Dockerfile hoặc bất kỳ session nào không có panel tương tác, hãy dùng dạng shell. Dạng này cài plugin vào user scope, trừ khi bạn truyền --scope.

claude plugin install commit-commands@claude-code-plugins --scope project
claude plugin list

claude plugin install chạy bên ngoài session, nên session đang mở sẽ chưa thấy plugin mới cho đến khi bạn chạy /reload-plugins hoặc khởi động session mới.

Cách quản lý các plugin hiện có cũng giống nhau ở cả hai nơi. /plugin list in ra danh sách plugin đã cài và chấp nhận --enabled hoặc --disabled. /plugin disable name@marketplace tắt plugin mà không gỡ plugin, /plugin enable bật lại plugin, còn /plugin uninstall gỡ plugin. Các dạng slash-command sẽ mở plugin panel để áp dụng thay đổi. Vì vậy, trong script nên dùng các lệnh shell tương đương claude plugin ....

Để cung cấp một marketplace cho cả team, hãy thêm marketplace đó vào .claude/settings.json của project. Thành viên sẽ được nhắc cài marketplace sau khi họ tin cậy thư mục repository.

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

Trong quá trình xây dựng plugin riêng, hãy bỏ qua marketplace. claude --plugin-dir ./my-plugin load một directory cho session hiện tại, /reload-plugins nhận các chỉnh sửa của bạn mà không cần restart, còn claude plugin validate ./my-plugin kiểm tra manifest, frontmatter của skill và agent, cùng hooks/hooks.json trước khi người khác sử dụng plugin.

Plugin Claude Code tốn bao nhiêu?

Cơ chế này miễn phí. Tính đến tháng 8 năm 2026, bạn không phải trả phí để thêm marketplace, cài plugin hoặc để plugin tiếp tục được bật. Các marketplace chính thức và marketplace do cộng đồng duy trì đều là git repository công khai, còn plugin là một thư mục chứa các tệp văn bản.

Thứ plugin tiêu tốn là token. Token là đơn vị mà gói thuê bao hoặc hóa đơn API thực tế đo lường. Plugin trừ vào loại chi phí nào phụ thuộc vào cách bạn trả tiền cho công cụ ngay từ đầu. Chi phí Claude Code trên từng gói trình bày các cấp gói thuê bao cùng với giá API theo token. Chi phí này phát sinh theo ba cách khác nhau và mỗi cách có cơ chế riêng.

Chi phí context thường trực. Nội dung plugin thêm vào nằm trong context của bạn và được đọc lại ở mỗi lượt của session. Trước khi cài đặt, chế độ xem chi tiết /plugin hiển thị ước tính Context cost theo token cùng phần Will install liệt kê các command, skill, agent, hook và server MCP và LSP mà bạn sắp thêm. Hãy đọc cả hai. Plugin từ local marketplace hoặc marketplace tùy chỉnh có thể không cung cấp dữ liệu này. Khi đó bạn phải tự ước tính. Plugin đóng gói một server MCP thường nặng nhất vì các định nghĩa tool có kích thước lớn. Tuy nhiên, trên các model hỗ trợ MCP tool search, những định nghĩa này được trì hoãn cho đến khi cần dùng tool.

Chi phí khi gọi. Khi chạy skill của plugin, hệ thống thêm instruction của skill vào cuộc hội thoại. Vì vậy, bạn chỉ trả phí cho phần nội dung skill khi skill được sử dụng. Tuy nhiên, phần nội dung này thường là phần rẻ. Những gì skill yêu cầu agent thực hiện mới có thể tốn nhiều hơn: phương pháp Depth Tree của skill unlazy dùng gần như toàn bộ token cho các lượt xử lý bổ sung mà nó buộc agent thực hiện trước khi được phép đánh dấu task là hoàn tất, chứ không phải cho tệp bạn đã cài đặt. Agent thì khác. Subagent chạy cuộc hội thoại riêng với system prompt riêng và cache riêng, bắt đầu mà không có cache hit nào. Vì vậy, plugin có workflow tạo agent sẽ tốn nhiều hơn đáng kể so với mức ước tính context.

Chi phí cache. Bật hoặc tắt plugin giữa session có thể buộc request tiếp theo xử lý lại toàn bộ cuộc hội thoại. Skill, command, agent, hook, server LSP, monitor và theme không làm vậy. Nội dung chúng thêm vào được nối sau history hiện có, nên request tiếp theo chỉ trả phí cho nội dung mới và vẫn đọc mọi nội dung trước đó từ cache. Ngoại lệ là plugin cung cấp server MCP. Nếu tool của server được trì hoãn bằng tool search, cache vẫn được giữ. Nếu chúng được nạp vào prompt prefix, request tiếp theo sẽ đọc lại toàn bộ cuộc hội thoại dưới dạng input chưa được cache. Đó chính là lý do /reload-plugins cảnh báo và từ chối trong trường hợp này cho đến khi bạn truyền --force.

Bạn có thể theo dõi thay vì đoán. Mỗi API response đều báo cáo cache_read_input_tokens và cache_creation_input_tokens. Một statusline tùy chỉnh hiển thị lượng token đang dùng sẽ đưa cả hai chỉ số ra trước mắt bạn. Một session khỏe mạnh thường đọc nhiều hơn mức nó tạo ra. Nếu lượng tạo ra vẫn cao qua từng lượt, có thứ gì đó trong prefix đang thay đổi ở mỗi lượt. Để xem đầy đủ những gì đang chiếm chỗ trong cửa sổ context, hãy xem cách quản lý cửa sổ context của Claude Code và ý nghĩa thực tế của các số lượng token đó.

Một việc dọn dẹp nhỏ có thể tự bù chi phí. Tab Installed nhóm các plugin bạn chưa dùng trong ít nhất hai tuần dưới tiêu đề Not used recently và hiển thị dòng Last used trong chế độ xem chi tiết. Các plugin đó vẫn làm tăng thời gian khởi động và chiếm context trong mỗi session. Hãy tắt hoặc gỡ cài đặt chúng.

Plugin chạy với quyền của bạn

Tài liệu chính thức của Anthropic nói rất rõ: plugin và marketplace là các thành phần được tin cậy cao, có thể thực thi mã tùy ý trên máy của bạn với quyền của user hiện tại. Đây không phải rủi ro giả định. Hook của plugin chạy các shell command khi có sự kiện trong session, bao gồm trước và sau các lần gọi tool. Thư mục bin/ của plugin được thêm vào PATH của Bash tool trong thời gian plugin được bật. MCP server của plugin là các process do plugin khởi chạy. Không có thành phần nào trong số này được sandbox tách khỏi user account của bạn.

Trên laptop, rủi ro này bị giới hạn bởi những tài nguyên mà desktop user của bạn có thể truy cập. Trên server thì thường không như vậy. Account chạy agent thường có SSH key, deploy token, session của cloud CLI và quyền truy cập Docker socket. Vì vậy, “mã tùy ý chạy với quyền của bạn” thực tế có nghĩa là quyền trên toàn bộ máy. Nếu Claude Code chạy trên VPS, hãy đọc cách chạy Claude Code an toàn trên VPS trước khi cài bất kỳ thứ gì, và đọc cách giữ credential ngoài tầm với của agent trước khi cài plugin kết nối đến external service. Các harness khác cũng gặp cùng vấn đề trên cùng một máy thuê. Vì vậy, các plugin DeepSeek Harness đáng cài chủ yếu cung cấp giới hạn chi phí, rule cấp quyền cho tool và quét injection, thay vì thêm capability mới.

Một số guardrail vẫn tồn tại, và bạn nên biết chúng là gì. Plugin có scope là project đến từ repository thay vì từ bạn, nên chỉ được load sau khi bạn tin cậy workspace. MCP server của plugin vẫn cần được approve riêng cho từng server. LSP server cũng chờ trạng thái tin cậy đó. Các monitor chạy background hoàn toàn không được load. Agent do plugin cung cấp không được phép khai báo hook, MCP server hoặc permission mode. Plugin từ marketplace được copy vào cache, đồng thời các symlink trỏ ra ngoài marketplace sẽ bị bỏ qua. Vì vậy, plugin không thể tùy ý đưa file từ host vào.

Không điều nào trong số đó thay thế cho việc đọc nội dung bạn cài đặt. Kiểm tra danh sách Will install, ưu tiên các plugin mà bạn có thể mở và đọc source, giữ plugin của team trong một marketplace repository do bạn kiểm soát, và chạy claude plugin validate trên mọi thứ bạn tự viết.

FAQ

Claude Code plugin có tốn thêm tiền không?

Không. Hệ thống plugin, việc thêm marketplace và việc cài plugin đều không mất phí. Chi phí là lượng token sử dụng, được tính vào plan hoặc khoản chi API của bạn như mọi context khác. Plugin thêm context cố định vào mỗi lượt, thêm context khi một skill hoặc agent của plugin được gọi, và có thể buộc một lượt tốn kém không dùng cache nếu plugin cung cấp MCP server có các tool được nạp vào prompt prefix. Chế độ xem chi tiết /plugin hiển thị ước tính Context cost trước khi bạn cài.

Plugin khác skill như thế nào?

Skill là một đơn vị instruction riêng lẻ. Plugin là một package có thể chứa skill, agent, hook, MCP server, LSP server và monitor, cùng name, version và marketplace để cài đặt. Hãy viết skill độc lập trong .claude/ khi skill đó chỉ dành cho bạn và project này. Một skill chỉ làm một việc, chẳng hạn Ponytail, giúp agent hướng đến thay đổi nhỏ nhất nhưng vẫn hoạt động, là trường hợp điển hình: một file chứa một rule, cho đến khi team của bạn cũng cần dùng nó. Hãy chuyển thành plugin khi người khác cần dùng và nó cần được cập nhật theo thời gian. Skill trong plugin có namespace, nên skill bên trong plugin được gọi là /plugin-name:skill-name thay vì /skill-name.

Plugin đã cài nhưng skill không xuất hiện. Có vấn đề gì?

Trước tiên, hãy kiểm tra phần tóm tắt cài đặt. Nếu phần này hiển thị Run /reload-plugins to activate., các component chưa được nạp và nếu thao tác reload cảnh báo rằng nó sẽ đọc lại conversation, hãy chạy lại bằng /reload-plugins --force. Nếu plugin đã được nạp nhưng không hiển thị gì, mở /plugin và đọc tab Errors. Lỗi cấu trúc thường gặp nhất là đặt skills/, agents/ hoặc hooks/ bên trong .claude-plugin/, trong khi Claude Code không tìm chúng ở đó. Hãy nhớ rằng skill của plugin có namespace, vì vậy bạn cần tìm /plugin-name:skill-name trong tab Custom commands của /help. Nếu vẫn không được, hãy rm -rf ~/.claude/plugins/cache, khởi động lại và cài lại.

Tôi có thể cài plugin mà không dùng panel tương tác không?

Có. Dùng shell command claude plugin install name@marketplace. Command này cài vào user scope nếu bạn không truyền --scope project hoặc --scope local. Nó hoạt động trong script, image và môi trường non-interactive nơi panel /plugin không khả dụng. Vì command chạy bên ngoài session, session đang mở cần /reload-plugins trước khi plugin có hiệu lực.

Cài plugin từ marketplace tôi tìm thấy trên GitHub có an toàn không?

Hãy xem việc này tương đương với chạy install script của repository đó bằng tài khoản của bạn, vì về bản chất gần như vậy. Plugin có thể chạy shell command thông qua hook, thêm executable vào PATH của Bash tool và khởi động MCP server, tất cả bằng quyền của user hiện tại. Anthropic không kiểm soát hoặc xác minh nội dung plugin của bên thứ ba. Hãy cài từ source mà bạn có thể đọc, xem lại danh sách Will install trước khi xác nhận và thận trọng hơn trên server so với laptop, vì account trên server thường giữ các key và token có giá trị đối với kẻ tấn công.