Tạo plugin

Plugin cho phép bạn mở rộng Claude Code với chức năng tùy chỉnh, chia sẻ được giữa các project và team. Trang này hướng dẫn cách tự tạo plugin với skill, agent, hook, và MCP server.

Muốn cài plugin có sẵn thay vì tự tạo? Xem Khám phá và cài plugin.

Khi nào dùng plugin, khi nào dùng cấu hình standalone

Claude Code có hai cách để thêm skill, agent, và hook tùy chỉnh:

Cách tiếp cận	Tên skill	Phù hợp cho
Standalone (thư mục .claude/)	/hello	Workflow cá nhân, tùy chỉnh riêng cho project, thử nghiệm nhanh
Plugin (thư mục tự chứa skill, agent, hook, hoặc manifest .claude-plugin/plugin.json)	/plugin-name:hello	Chia sẻ với đồng đội, phân phối cho cộng đồng, release có version, tái sử dụng qua nhiều project

Dùng cấu hình standalone khi:

• Bạn đang tùy chỉnh Claude Code cho một project duy nhất
• Cấu hình mang tính cá nhân, không cần chia sẻ
• Bạn đang thử nghiệm skill hoặc hook trước khi đóng gói
• Bạn muốn tên skill ngắn gọn như /hello hoặc /deploy

Dùng plugin khi:

• Bạn muốn chia sẻ chức năng với team hoặc cộng đồng
• Bạn cần cùng một bộ skill/agent trên nhiều project
• Bạn muốn quản lý version và cập nhật dễ dàng
• Bạn phân phối qua marketplace
• Bạn chấp nhận tên skill có namespace như /my-plugin:hello (namespace giúp tránh xung đột giữa các plugin)

Mẹo

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

Bắt đầu nhanh

Phần này hướng dẫn tạo một plugin với skill tùy chỉnh: tạo manifest (file cấu hình định nghĩa plugin), thêm skill, và test cục bộ bằng cờ --plugin-dir.

Điều kiện tiên quyết

• Claude Code đã cài đặt và xác thực

Ghi chú

Nếu không thấy lệnh /plugin, cập nhật Claude Code lên phiên bản mới nhất.

Tạo plugin đầu tiên

Bước 1: Tạo thư mục plugin

Mỗi plugin nằm trong thư mục riêng chứa skill, agent, hoặc hook, có thể kèm theo manifest .claude-plugin/plugin.json. Vị trí không quan trọng ở bước này vì bạn sẽ trỏ Claude Code vào thư mục bằng --plugin-dir ở bước test. Tạo thư mục ở bất kỳ đâu tiện lợi:

mkdir my-first-plugin

Bước 2: Tạo manifest cho plugin

File manifest tại .claude-plugin/plugin.json định nghĩa danh tính plugin: tên, mô tả, và version. Claude Code dùng metadata này để hiển thị plugin trong trình quản lý plugin.

mkdir my-first-plugin/.claude-plugin

Tạo 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 cho skill (ví dụ: /my-first-plugin:hello).
description	Hiển thị trong trình quản lý plugin khi duyệt hoặc cài đặt.
version	Tùy chọn. Nếu đặt, người dùng chỉ nhận cập nhật khi bạn tăng version. Nếu bỏ trống và plugin phân phối qua git, commit SHA sẽ được dùng thay thế.
author	Tùy chọn, hữu ích để ghi công.

Xem thêm các trường khác như homepage, repository, license trong schema manifest đầy đủ.

Bước 3: Thêm skill

Skill nằm trong thư mục skills/. Mỗi skill là một folder chứa file SKILL.md. Tên folder trở thành tên skill, có tiền tố là namespace của plugin (hello/ trong plugin my-first-plugin tạo ra /my-first-plugin:hello).

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

Tạo my-first-plugin/skills/hello/SKILL.md:

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

Chạy Claude Code với cờ --plugin-dir để nạp plugin:

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

Sau khi Claude Code khởi động, thử skill mới:

/my-first-plugin:hello

Bạn sẽ thấy Claude phản hồi với lời chào. Chạy /help và mở tab Custom commands để xem skill nằm dưới namespace của plugin.

Ghi chú

Vì sao có namespace? Skill của plugin luôn có namespace (như /my-first-plugin:hello) để tránh xung đột khi nhiều plugin có skill cùng tên. Để đổi tiền tố namespace, sửa trường name trong plugin.json.

Bước 5: Thêm tham số cho skill

Làm skill động hơn bằng cách nhận input từ người dùng. Placeholder $ARGUMENTS chứa mọi text người dùng nhập sau tên skill.

Cập nhật SKILL.md:

---
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 để nạp lại thay đổi, rồi thử skill với tên bạn:

/my-first-plugin:hello Alex

Claude sẽ chào bạn bằng tên. Xem thêm về truyền tham số cho skill tại Skills.

Bạn đã tạo và test thành công một plugin với các thành phần chính:

• Manifest plugin (.claude-plugin/plugin.json): mô tả metadata của plugin
• Thư mục skill (skills/): chứa các skill tùy chỉnh
• Tham số skill ($ARGUMENTS): nhận input từ người dùng cho hành vi động

Mẹo

Cờ --plugin-dir hữu ích khi phát triển và test. Khi sẵn sàng chia sẻ plugin, xem Tạo và phân phối marketplace plugin.

Phát triển plugin trong thư mục skill của bạn

Thay vì truyền --plugin-dir mỗi lần khởi động, bạn có thể giữ plugin trong thư mục skill và để Claude Code tự nạp. Lệnh claude plugin init sẽ dựng sẵn khung này:

claude plugin init my-tool

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

Cấu trúc plugin tổng quan

Ngoài skill, plugin có thể chứa agent tùy chỉnh, hook, MCP server, LSP server, và background monitor.

Chú ý

Lỗi thường gặp: đừng đặt commands/, agents/, skills/, hoặc 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 nằm ở gốc plugin.

Gốc plugin là thư mục riêng của plugin đó - thư mục bạn truyền cho --plugin-dir hoặ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 (tùy chọn nếu các thành phần dùng vị trí mặc định)
skills/	Gốc plugin	Skill dưới dạng thư mục <name>/SKILL.md
commands/	Gốc plugin	Skill dạng file Markdown phẳng. Dùng skills/ cho plugin mới
agents/	Gốc plugin	Định nghĩa agent tùy chỉnh
hooks/	Gốc plugin	Event handler 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 dụng khi plugin bật

Plugin chỉ có một skill duy nhất có thể đặt SKILL.md trực tiếp ở gốc plugin thay vì tạo thư mục skills/. Dùng cấu trúc skills/ cho plugin có khả năng phát triển thêm nhiều skill.

Phát triển plugin phức tạp hơn

Thêm Skill vào plugin

Thêm thư mục skills/ ở gốc plugin với các folder skill chứa SKILL.md:

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

Mỗi SKILL.md chứa YAML frontmatter và hướng dẫn. Luôn thêm description để Claude biết khi nào dùng skill:

---
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

Sau khi cài plugin, chạy /reload-plugins để nạp Skill. Xem hướng dẫn viết Skill đầy đủ tại Agent Skills.

Thêm LSP server vào plugin

Mẹo

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

Thêm file .lsp.json vào plugin:

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

Người dùng cài plugin phải có sẵn binary của language server trên máy. Để xác nhận server khởi động, chạy Claude Code với plugin bật và kiểm tra tab Errors trong /plugin.

Thêm background monitor vào plugin

Background monitor cho phép plugin theo dõi log, file, hoặc trạng thái bên ngoài trong nền và thông báo cho Claude khi có sự kiện. Claude Code tự khởi động mỗi monitor khi plugin đang bật.

Thêm file monitors/monitors.json ở gốc plugin:

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

Mỗi dòng stdout từ command được gửi tới Claude dưới dạng thông báo trong phiên.

Ship settings mặc định cùng plugin

Plugin có thể chứa file settings.json ở gốc để áp dụng cấu hình mặc định khi plugin bật. Hiện chỉ hỗ trợ hai khóa agent và subagentStatusLine.

{
  "agent": "security-reviewer"
}

Ví dụ trên kích hoạt agent tùy chỉnh security-reviewer được định nghĩa trong thư mục agents/ của plugin, khiến plugin thay đổi hành vi mặc định của Claude Code khi bật.

Test plugin cục bộ

claude --plugin-dir ./my-plugin

Cờ này cũng chấp nhận file .zip nén thư mục plugin (yêu cầu Claude Code v2.1.128 trở lên):

claude --plugin-dir ./my-plugin.zip

Khi plugin cài qua --plugin-dir trùng tên với plugin marketplace đã cài, bản cục bộ sẽ được ưu tiên trong phiên đó - hữu ích để test thay đổi mà không cần gỡ cài đặt trước.

Sau khi sửa plugin, chạy /reload-plugins để nạp lại mà không cần khởi động lại phiên. Lệnh này nạp lại plugin, skill, agent, hook, MCP server và LSP server của plugin.

Mẹo

Có thể nạp nhiều plugin cùng lúc bằng cách lặp lại cờ:

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

Để test plugin đã đóng gói dưới dạng .zip lưu trên URL (ví dụ CI build artifact), dùng --plugin-url thay thế. Chỉ trỏ cờ này vào các archive bạn kiểm soát hoặc tin tưởng.

Debug lỗi plugin

1. Kiểm tra cấu trúc: đảm bảo các thư mục nằm ở gốc plugin, không nằm trong .claude-plugin/
2. Test từng thành phần riêng lẻ: kiểm tra từng skill, agent, hook riêng biệt
3. Dùng công cụ validate và debug: xem các lệnh CLI và kỹ thuật debug liên quan

Chia sẻ plugin

Khi plugin sẵn sàng chia sẻ:

1. Thêm tài liệu: kèm README.md với hướng dẫn cài đặt và sử dụng
2. Chọn chiến lược version: quyết định đặt version cụ thể hay dựa vào commit SHA
3. Tạo hoặc dùng marketplace: phân phối qua plugin marketplace
4. Test cùng người khác: nhờ đồng đội test trước khi phân phối rộng rãi

Để giữ plugin nội bộ trong team, host marketplace trong private repository.

Gửi plugin lên community marketplace

Anthropic duy trì hai marketplace công khai cho plugin Claude Code:

• claude-plugins-official: bộ plugin được Anthropic tuyển chọn, tự động đăng ký lần đầu bạn khởi động Claude Code tương tác.
• claude-community: marketplace cộng đồng công khai, nơi các submission từ bên thứ ba xuất hiện sau khi review. Người dùng thêm bằng /plugin marketplace add anthropics/claude-plugins-community.

Chạy claude plugin validate ./your-plugin cục bộ trước khi gửi để kiểm tra trước. Plugin được duyệt sẽ được pin vào một commit SHA cụ thể trong catalog anthropics/claude-plugins-community.

Marketplace chính thức claude-plugins-official được tuyển chọn riêng, Anthropic tự quyết định plugin nào được đưa vào; không có quy trình đăng ký cho marketplace này.

Chuyển cấu hình hiện có thành plugin

Nếu bạn đã có skill hoặc hook trong thư mục .claude/, có thể chuyển chúng thành plugin để dễ chia sẻ và phân phối hơn.

Các bước migrate

Bước 1: Tạo cấu trúc plugin

mkdir -p my-plugin/.claude-plugin

Tạo manifest tại my-plugin/.claude-plugin/plugin.json:

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

Bước 2: Copy file hiện có

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

Nếu một trong ba thư mục không tồn tại, cp sẽ báo lỗi và không copy gì - bỏ qua hoặc phớt lờ lỗi đó.

Bước 3: Migrate hook

Nếu có hook trong settings, tạo thư mục hooks:

mkdir my-plugin/hooks

Tạo my-plugin/hooks/hooks.json với cấu hình hook. Copy object hooks từ .claude/settings.json hoặc settings.local.json, vì định dạng giống nhau. Command nhận input hook dưới dạng JSON qua stdin, nên dùng jq để trích xuất đường dẫn file:

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

Bước 4: Test plugin đã migrate

claude --plugin-dir ./my-plugin

Test từng thành phần: chạy các command, kiểm tra agent xuất hiện trong /context, và kích hoạt sự kiện mà mỗi hook khớp để xác nhận tác dụng.

Thay đổi gì khi migrate

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

Ghi chú

Sau khi migrate, xóa file gốc trong .claude/ để tránh trùng lặp. Định nghĩa .claude/agents/ cấp project và user sẽ ghi đè agent cùng tên của plugin, nên bản plugin chỉ có hiệu lực sau khi bạn xóa bản gốc. Skill của plugin có namespace /plugin-name:skill-name, nên /skill-name gốc và bản copy của plugin cùng tồn tại thay vì ghi đè lẫn nhau.

Bước tiếp theo

Cho người dùng plugin

• Khám phá và cài plugin: duyệt marketplace và cài plugin
• Cấu hình marketplace cho team: thiết lập plugin cấp repository cho team

Cho người phát triển plugin

• Tạo và phân phối marketplace: đóng gói và chia sẻ plugin
• Đào sâu từng thành phần plugin cụ thể:
  • Skills: chi tiết phát triển skill
  • Subagents: cấu hình và khả năng của agent
  • Hooks: xử lý sự kiện và tự động hóa
  • MCP: tích hợp công cụ bên ngoài

Nguồn

Dịch và biên soạn từ Create plugins.