Tiêu chuẩn chất lượng yêu cầu đối với plugin sản xuất
Chất lượng yêu cầu đối với plugin đặt trong dotfiles cá nhân và plugin phát hành trên marketplace công khai khác nhau đáng kể. Cái trước chỉ cần "hoạt động trong môi trường của mình" là đủ, nhưng cái sau phải xem xét nhiều yếu tố: tương thích với nhiều OS và phiên bản Node.js khác nhau, khả năng cùng tồn tại với các shell và cấu hình hiện có, trải nghiệm onboarding, chiến lược nâng cấp và nhiều điều nữa.
Tính đến tháng 4 năm 2026, hơn 1.800 plugin đã được công bố trên marketplace plugin chính thức của Anthropic, nhưng chỉ khoảng 100 plugin hàng đầu vượt qua 1.000 lượt cài đặt hoạt động hàng tuần. Điều tạo ra sự khác biệt này không phải là sự phô trương về tính năng, mà là "những nền tảng cơ bản tẻ nhạt" như chất lượng manifest, tài liệu, kỷ luật versioning và quy tắc merge cấu hình.
Cấu trúc repository chuẩn
Cấu trúc chuẩn của repository plugin như sau.
``` my-claude-plugin/ ├── .claude-plugin/ │ └── plugin.json # Manifest (bắt buộc) ├── commands/ # Lệnh slash │ ├── review.md │ └── deploy.md ├── skills/ # Skill │ └── security-audit/ │ └── SKILL.md ├── agents/ # Định nghĩa subagent │ └── researcher.md ├── hooks/ # Cấu hình hook │ └── hooks.json ├── mcp/ # MCP server đi kèm │ ├── server.ts │ └── package.json ├── scripts/ # Script cài đặt & migrate │ └── postinstall.sh ├── README.md ├── CHANGELOG.md └── LICENSE ```
Các repository phổ biến như gsd-build/get-shit-done hay wshobson/agents hầu như đều hội tụ về cấu trúc này. Đặc biệt, quy ước đặt `.claude-plugin/plugin.json` ở thư mục gốc là quy tắc bắt buộc trên thực tế, vì lệnh `plugin add` của Anthropic CLI tìm đường dẫn này một cách cố định.
Cách viết manifest plugin.json
plugin.json tối thiểu phải có các trường sau.
```json { "name": "gsd-build", "displayName": "Get Shit Done", "version": "2.4.1", "description": "Stop-hook driven task persistence for Claude Code", "author": { "name": "GSD Team", "url": "https://github.com/gsd-build" }, "license": "MIT", "homepage": "https://github.com/gsd-build/get-shit-done", "repository": "https://github.com/gsd-build/get-shit-done.git", "claudeCode": { "minVersion": "2.8.0" }, "commands": ["commands/"], "skills": ["skills/"], "agents": ["agents/"], "hooks": "hooks/hooks.json", "mcpServers": { "gsd-db": { "command": "node", "args": ["mcp/server.js"] } }, "configSchema": "config.schema.json", "telemetry": { "endpoint": "https://telemetry.gsd.dev/v1" } } ```
`claudeCode.minVersion` phải được cập nhật mỗi khi có thay đổi phá vỡ tương thích. Đây là vì trải nghiệm người dùng tệ nhất là plugin được cài đặt trên CLI cũ của người dùng và gây ra lỗi hoạt động ngầm. `configSchema` cung cấp validation cấu hình người dùng theo định dạng JSON Schema, để hiển thị thông báo lỗi thân thiện khi cấu hình sai.
Thực tiễn semantic versioning
Versioning plugin về cơ bản tuân theo semver, nhưng việc "xác định điều gì là thay đổi phá vỡ tương thích" có những khó khăn riêng. Thay đổi tên lệnh slash, thay đổi matcher của hook hiện có, thêm trường bắt buộc vào `inputSchema` của MCP tool đều là thay đổi phá vỡ. Ngược lại, thêm lệnh mới, thêm đối số tùy chọn vào lệnh hiện có, thêm MCP tool mới chỉ cần minor version.
CHANGELOG.md được khuyến nghị mạnh theo định dạng Keep a Changelog. Vì UI của marketplace tự động parse CHANGELOG.md để hiển thị trên màn hình cập nhật, nên việc thống nhất định dạng trực tiếp ảnh hưởng đến thực tiễn. Tại KGA IT, chúng tôi áp dụng định dạng này bắt buộc cho tất cả các dự án, kể cả plugin nội bộ.
Phân phối trên marketplace
Tính đến tháng 4 năm 2026, có 3 kênh phân phối chính. Thứ nhất là Anthropic marketplace chính thức (claude.ai/plugins), có quá trình xem xét nhưng khả năng được tìm thấy cao nhất. Thứ hai là cài đặt trực tiếp từ repository GitHub (`claude plugin add github.com/user/repo`), không cần xem xét và phản ánh ngay, phổ biến với tác giả OSS. Thứ ba là marketplace riêng tư, dạng doanh nghiệp host `claude-plugin-registry` và phân phối nội bộ.
Khi xem xét marketplace chính thức, các điểm được kiểm tra bao gồm: tính hợp lý của việc thực thi lệnh shell, khai báo điểm đến mạng, khai báo xử lý thông tin cá nhân và bảo mật quy trình thanh toán đối với plugin có phí. Từ tháng 2 năm 2026, chế độ "audit badge" được giới thiệu, và các plugin đã vượt qua phân tích tĩnh được gắn badge xanh. Có dữ liệu công khai cho thấy tỷ lệ chấp nhận thay đổi hơn gấp đôi tùy thuộc vào việc có hay không có badge này, và việc đạt được nó được khuyến nghị mạnh mẽ.
Telemetry và khả năng quan sát
Việc vận hành plugin cần hiểu "ai đang sử dụng như thế nào". Tuy nhiên, người dùng Claude Code có ý thức về quyền riêng tư cao, và telemetry không minh bạch sẽ bị gỡ cài đặt ngay lập tức. Phương pháp được khuyến nghị là ba nguyên tắc: "opt-in, ẩn danh, chỉ gửi giá trị tổng hợp".
Cụ thể, hiển thị prompt "Bạn có đồng ý gửi thống kê sử dụng ẩn danh không?" khi khởi động lần đầu, và chỉ gửi ID cài đặt và số lần gọi từng lệnh hàng ngày nếu người dùng chọn Yes. Tuyệt đối không gửi nội dung prompt cá nhân hay đường dẫn file. wshobson/agents tổng hợp xếp hạng các định nghĩa Subagent phổ biến theo phương pháp này và công bố hàng tháng trong README. Điều này cũng hoạt động như một tín hiệu cho thấy "plugin này được vận hành lành mạnh".
Theo kịp API phá vỡ tương thích
Từ nửa sau năm 2025, tốc độ bổ sung tính năng của Claude Code gốc tăng tốc, và đôi khi các plugin hiện có ngừng hoạt động ngay cả với minor version. Khi Claude Code 3.0 vào tháng 1 năm 2026 thay đổi hợp đồng Hook và việc truyền JSON qua stdin trở thành bắt buộc, hơn 1.200 plugin đã phải cập nhật trong vòng hai tuần.
Có hai lớp biện pháp đối phó. Đầu tiên, chỉ định nghiêm ngặt `claudeCode.minVersion` trong `plugin.json` để không khởi động trên CLI chưa hỗ trợ. Tiếp theo, sử dụng `claude-code-nightly` trong GitHub Actions để chạy kiểm thử tích hợp và tự động hóa việc xác nhận hoạt động với phiên bản mới. Từ tháng 2, Anthropic công bố `plugin-compat-matrix` và trực quan hóa trạng thái hoạt động của plugin chính thức trên từng phiên bản CLI. Các bên thứ ba cũng đang đi theo schema này.
Chiến lược merge cấu hình người dùng
Plugin ghi vào `.claude/settings.json`, nhưng không được phá vỡ cấu hình hiện có của người dùng. Việc triển khai được khuyến nghị là "áp dụng patch dựa trên JSON Pointer". Lưu diff patch vào `.claude/plugins/<name>/applied-patch.json` khi `plugin install` và đảm bảo có thể hoàn tác chính xác khi `uninstall`.
Điều cần đặc biệt chú ý là việc merge mảng `permissions`. Để không xung đột với các quy tắc allow/deny hiện có của người dùng, đang dần trở thành thông lệ cô lập các quy tắc dành riêng cho plugin bằng tiền tố namespace (ví dụ: `"gsd:*"`). get-shit-done là người tiên phong áp dụng phương pháp này và trở thành triển khai tham khảo cho nhiều plugin kế tiếp.
Vận hành sau khi công bố
Không phải công bố xong là hết. Tốc độ phản hồi ban đầu trên GitHub Issues, vá lỗi ngay lập tức khi vi phạm semver, quy trình phát hành security advisory, thông báo deprecation cho người dùng — chất lượng vận hành của những điều này quyết định tỷ lệ chấp nhận dài hạn. Plugin càng phổ biến, gánh nặng vận hành càng nặng, và có những trường hợp cần tăng thêm maintainer hay thành lập pháp nhân.
Tại KGA IT, khi giao nộp plugin nội bộ cho khách hàng, chúng tôi đóng gói cả runbook vận hành, thể thức on-call và cuộc họp review hàng quý. Plugin không phải là sản phẩm bàn giao mà là sản phẩm, và trách nhiệm vận hành phát sinh ngay từ khoảnh khắc công bố trên môi trường sản xuất — nhận thức này là ranh giới phân biệt plugin chuyên nghiệp và plugin hobby.