Tự tay đóng gói Plugin Claude Code: Từ plugin.json đến package sẵn sàng chia sẻ

Định nghĩa

Plugin Claude Code là bưu kiện công nghệ — một gói bundle đóng gói slash commands, subagents, hooks, MCP servers và skills thành một đơn vị duy nhất qua manifest plugin.json. Khác với việc copy-paste file rời rạc giữa các project, plugin cho phép bạn ghi lại tribal knowledge dưới dạng executable code: một lần cài đặt (/plugin install), toàn bộ workflow và chuẩn mực của team được triển khai ngay lập tức. Đây là cách mà startup Việt scale quy trình từ 2 lập trình viên lên 20 người mà không lo "mỗi người một kiểu".

Giải thích chi tiết

plugin.json: Bản khai sinh của plugin

File .claude-plugin/plugin.json là điểm vào bắt buộc — như package.json của npm hay Cargo.toml của Rust. Đây là bản khai báo metadata để Claude hiểu plugin chứa gì, thuộc về ai, và cách ánh xạ vào hệ thống:

{
  "name": "vietqr-gen",
  "version": "1.2.0",
  "author": "fintech-vietnam",
  "description": "Tự động sinh VietQR chuẩn Napas, validate STK ngân hàng",
  "repository": "https://github.com/your-org/vietqr-plugin",
  "entry": {
    "commands": ["vietqr", "bank-validate"],
    "agents": ["payment-auditor"],
    "hooks": ["pre-commit"]
  }
}

Khi chạy /plugin install, Claude đọc manifest này đầu tiên để xác thực tính toàn vẹn và phân giải dependencies trước khi giải nén các thành phần vào đúng vị trí. Một lỗi nhỏ trong JSON structure hoặc thiếu trường bắt buộc (name, version, entry) sẽ khiến quá trình cài đặt fail ngay từ đầu — đảm bảo atomicity: hoặc cài đủ, hoặc không cài.

Cấu trúc thư mục Convention-over-Configuration

Plugin tuân theo nguyên tắc convention-over-configuration: tên thư mục map 1:1 với hệ thống load của Claude Code. Bạn không cần khai báo đường dẫn trong manifest, chỉ cần đặt file đúng chỗ:

vietqr-plugin/
├── .claude-plugin/
│   └── plugin.json          # Manifest trung tâm
├── commands/
│   ├── vietqr.md            # `/vietqr` command
│   └── bank-validate.md     # `/bank-validate` command  
├── agents/
│   └── payment-auditor.md   # Subagent chuyên review code thanh toán
├── skills/
│   └── napas-spec.md        # Kiến thức về chuẩn Napas 2024
├── hooks/
│   └── pre-commit.json      # Auto-validate trước khi commit
└── .mcp.json                # Kết nối ngân hàng API qua MCP

Quy ước chi tiết:

• commands/: Chứa Markdown files với YAML frontmatter. Mỗi file định nghĩa một slash command — ví dụ vietqr.md chứa prompt template để sinh QR từ STK và ngân hàng. Khi cài, Claude copy vào .claude/commands/.
• agents/: Subagents chuyên biệt với context isolation riêng. File payment-auditor.md có thể định nghĩa agent chỉ được quyền Read và Grep để audit code thanh toán, không được Write để tránh sửa nhầm logic quan trọng.
• skills/: SKILL.md files cho progressive disclosure — metadata luôn load để Claude biết "tôi có chuyên môn về VietQR", nhưng instructions chi tiết chỉ load khi user hỏi về ngân hàng.
• hooks/: Event handlers cho 25+ events (PostToolUse, PreToolUse, v.v.). Dạng JSON cho simple triggers hoặc executable scripts cho logic phức tạp.
• .mcp.json: Cấu hình MCP servers được merge vào active configuration. Ví dụ: khai báo sẵn server kết nối VietQR API hoặc Zalo Webhook.

Điểm tinh tế quan trọng: Plugin không tạo ra capability mới — nó chỉ đóng gói những gì Claude đã hỗ trợ sẵn. Bạn không thể tạo "custom hook type" hay "new command syntax" qua plugin, chỉ có thể bundle các primitives sẵn có thành workflow liền mạch.

Cơ chế Installation và Scope Isolation

Claude hỗ trợ 4 tiers phân phối, phù hợp với cấu trúc tổ chức tại Việt Nam — từ freelancer đến công ty outsourcing lớn:

1. Official: Anthropic-maintained, global availability (ví dụ: plugin chính thức cho Python best practices)
2. Community: Public registry, cài qua /plugin install name — phù hợp open source từ cộng đồng dev Việt Nam
3. Organization: Team-scoped internal tools, lưu trên private registry (GitLab self-hosted của công ty) — cực kỳ quan trọng cho các công ty fintech cần giữ bí mật logic nghiệp vụ
4. Personal: Individual workflows trong ~/.claude/plugins/ — dùng cho máy cá nhân, không commit lên repo chung

Installation là atomic: tất cả components được cấu hình đồng thời. Nếu MCP server trong plugin không connect được (ví dụ API key sai), toàn bộ plugin báo lỗi thay vì để trạng thái partial — tránh tình trạng "có command nhưng thiếu agent hỗ trợ".

Ví dụ thực tế

Plugin VietQR Gen: Fintech made in Vietnam

Plugin cho team phát triển ví điện tử hoặc app ngân hàng số tại Việt Nam, tuân thủ chuẩn Napas 2024:

// .claude-plugin/plugin.json
{
  "name": "vietqr-gen",
  "version": "2.0.0",
  "description": "Sinh VietQR, validate STK, kiểm tra mã ngân hàng",
  "entry": {
    "commands": ["vietqr", "check-bank"],
    "agents": ["payment-reviewer"]
  }
}

Cấu trúc chi tiết:

• commands/vietqr.md: Slash command /vietqr nhận tham số bankCode (TCB cho Techcombank, VCB cho Vietcombank...) và accountNumber, tự động sinh chuỗi QR theo chuẩn EMVCo, kiểm tra tính hợp lệ bằng checksum.
• agents/payment-reviewer.md: Subagent chỉ có quyền đọc code, chuyên tìm lỗi bảo mật trong module thanh toán: kiểm tra xem có hardcode API key MoMo/VNPay không, có validate số tiền âm không, có log sensitive data không.
• skills/napas-spec.md: Chứa quy tắc định dạng STK từng ngân hàng (Techcombank 14 số, Vietcombank 13 số, v.v.) để Claude tự động báo lỗi nếu user nhập sai định dạng trước khi gọi API.
• hooks/pre-commit.json: Auto-scan file .env và config files để đảm bảo không commit nhầm API keys của ngân hàng lên GitHub.

Kết quả: Developer chỉ cần gõ /vietqr TCB 123456789 thay vì nhớ cú pháp phức tạp của thư viện VietQR và lo lắng về bảo mật.

Plugin Zalo OA Manager: Tự động hóa Marketing

Dành cho team Martech quản lý Zalo Official Account — nền tảng cực kỳ phổ biến tại Việt Nam nhưng ít có công cụ CLI tốt:

• .mcp.json: Cấu hình sẵn Zalo Webhook MCP server với access_token và oa_id, cho phép Claude đọc tin nhắn khách hàng và gửi broadcast.
• commands/broadcast.md: Prompt template để soạn tin nhắn Zalo chuẩn UTF-8, tự động kiểm tra độ dài (không vượt quá 2000 ký tự Zalo cho phép) và preview trước khi gửi.
• skills/zalo-policy.md: Kiến thức về quy định của Zalo về spam, giờ vàng gửi tin (tránh gửi trước 8h sáng), và cách xử lý từ khóa nhạy cảm bị Zalo chặn.
• hooks/post-save.json: Khi lưu file marketing copy (.txt, .md), tự động kiểm tra có chứa link lạ không, tránh phishing scam.

Plugin này biến Claude thành "trợ lý marketing" am hiểu nền tảng số Việt Nam, giúp team không cần mở Zalo Official Account Dashboard liên tục.

Plugin Shopee Seller: Tối ưu cho dropshipper

Giúp các seller trên Shopee — nền tảng thương mại điện tử chiếm 70% thị phần Việt Nam — tự động hóa listing sản phẩm:

• commands/listing.md: Tạo title Shopee chuẩn SEO (tối đa 120 ký tự, đủ từ khóa spamm không quá 3 lần), sinh mô tả HTML đẹp mắt, tự động tính giá bán lẻ dựa trên giá nhập + phí Shopee (đang là ~10-15% tùy ngành hàng).
• agents/price-monitor.md: Subagent chuyên crawl giá đối thủ (thông qua MCP server kết nối Shopee Open API hoặc scraping hợp lệ), cảnh báo nếu giá bạn đang cao hơn trung bình thị trường quá 20%.
• skills/shopee-rules.md: Quy định cấm hàng giả, từ khóa cấm (không được dùng từ "hàng Auth" nếu không có giấy tờ), kích thước ảnh chuẩn (800x800 pixel).
• hooks/pre-commit.json: Validate file ảnh sản phẩm trước khi commit lên repo: đảm bảo định dạng JPG/PNG, không chứa watermark của đối thủ, kích thước tối thiểu 500x500.

Ứng dụng

Developer cá nhân và Freelancer Việt Nam

Package workflow cá nhân thành plugin để sync giữa máy làm việc tại công ty (macOS) và máy cá nhân (Windows/Ubuntu). Ví dụ: bạn có bộ commands chuẩn để setup project React + TypeScript + Tailwind theo chuẩn công ty outsourcing, bộ hooks format code theo preference riêng — đóng gói thành plugin my-dev-setup thay vì copy-paste file .claude/commands/ qua lại giữa các máy.

Team Lead tại công ty Outsourcing

Phân phối tribal knowledge dưới dạng executable code cho team 10-20 developer. Thay vì viết wiki dài dòng "Cách chúng tôi review code cho khách hàng Nhật", tạo plugin company-standards chứa:

• Commands để generate commit message theo chuẩn Conventional Commits (bắt buộc trong hợp đồng với đối tác Nhật Bản)
• Agents kiểm tra xem code có comment tiếng Anh không (yêu cầu của đa số dự án offshore)
• Hooks chặn push trực tiếp lên main branch — bắt buộc phải qua pull request

New hire chỉ cần /plugin install company-standards là có sẵn toàn bộ workflow, giảm thời gian onboarding từ 1 tuần xuống 1 ngày.

Startup Fintech và E-commerce

Dùng Organization-tier plugins để enforce compliance trong môi trường regulated. Plugin có thể bundle:

• PreToolUse hooks chặn rm -rf / hoặc các lệnh nguy hiểm trên production database
• MCP servers chỉ kết nối đến internal APIs đã được security team approve (ví dụ: chỉ cho phép gọi API VietQR chính thức, chặn các endpoint lạ)
• Agents với restricted toolsets cho junior developers — họ chỉ được đọc code và viết unit test, không được touch vào phần authentication hay payment gateway

Đây là governance-as-code: policy không còn nằm trên giấy mà được thực thi tự động qua plugin configuration, rất quan trọng cho các công ty cần chứng chỉ bảo mật ISO 27001 hay PCI DSS.

So sánh

Kết luận: Plugin là composition layer — nó kết hợp MCP (kết nối), Skills (chuyên môn), Commands (tương tác), và Hooks (automation) thành một trải nghiệm thống nhất. Nếu Skill là một công cụ trong hộp đồ nghề, thì Plugin là cả hộp đồ nghề được sắp xếp sẵn cho một công việc cụ thể, sẵn sàng đưa cho đồng nghiệp sử dụng ngay.

Bài viết liên quan

Cùng cụm

• Plugin System: Đóng gói commands + agents + hooks + MCP — Tổng quan kiến trúc plugin và cách chúng tương tác với core system.
• Plugin Marketplace: Cài đặt, chia sẻ, phân phối — Hướng dẫn publish plugin lên registry và quản lý version cho cộng đồng dev Việt Nam.
• 3 Plugin mẫu: PR Review, DevOps, Documentation — Phân tích chi tiết implementation của 3 plugin thực tế phổ biến trong môi trường enterprise.

Đọc tiếp

• Skills là gì? Từ slash command đến auto-invoke — Hiểu sâu về Skill.md, thành phần cơ bản trong mọi plugin.
• Cài đặt MCP Server đầu tiên: Hướng dẫn từng bước — Tìm hiểu MCP, giao thức "USB-C" để kết nối external tools vào plugin.
• Hooks là gì? 25 events và 4 loại hook — Event-driven automation để tạo plugin reactive và thông minh.