Cách xây dựng plugin Claude Code: Hướng dẫn từng bước

Claude Code xử lý hầu hết tác vụ phát triển ngay khi cài đặt, nhưng mỗi nhóm đều có quy trình riêng mà mặc định không bao quát hết. Bạn có thể muốn một lệnh tùy chỉnh để dựng khung component theo cấu trúc ưa thích của công ty, tự động lint trước mỗi commit, hoặc truy cập nhanh tài liệu cho một framework bạn dùng thường xuyên.

Plugin Claude Code cho phép bạn tự bổ sung các tính năng này. Bạn có thể cài plugin do cộng đồng xây dựng hoặc tự tạo của riêng mình.

Nếu bạn mới dùng công cụ mã hóa dạng agent của Anthropic, tôi khuyến nghị bắt đầu với Hướng dẫn Claude Code hoặc khóa học Giới thiệu về các mô hình Claude. Hướng dẫn này giả định bạn đã cài Claude Code và đã dùng cho các tác vụ cơ bản.

Kết thúc bài, bạn sẽ biết cách:

• Tìm và cài plugin từ thư mục của Anthropic và nguồn cộng đồng
• Hiểu ba loại thành phần mà plugin có thể chứa
• Chọn đúng loại cho từng trường hợp sử dụng
• Xây dựng và chia sẻ plugin của riêng bạn

Để tổng quan về khả năng của mô hình mới nhất từ Anthropic, hãy xem hướng dẫn về Claude Sonnet 5.

TL;DR

• Plugin Claude Code gói các skill, máy chủ MCP và hook vào các gói có thể chia sẻ, bạn cài bằng claude plugin add

• Skill được nạp theo nhu cầu (~100 token mỗi skill); máy chủ MCP nạp trước định nghĩa công cụ (được giảm nhờ Tool Search); hook chạy như script shell với chi phí token bằng 0

• Dùng skill cho tri thức và quy trình, máy chủ MCP cho truy cập API bên ngoài, và hook cho các quy tắc phải chạy mọi lần

• Xây plugin với ba tệp: tệp khai báo .claude-plugin/plugin.json, thư mục skills/, và tệp hướng dẫn SKILL.md

Plugin Claude Code là gì?

Plugin là một gói gom một hoặc nhiều tiện ích mở rộng Claude Code để dễ chia sẻ và cài đặt. Thay vì sao chép thủ công các tệp cấu hình giữa máy hoặc đồng đội, bạn có thể gói mọi thứ vào một plugin và phân phối như một đơn vị duy nhất.

Plugin có thể chứa ba loại thành phần:

• Skills: Các lệnh tùy chỉnh bạn gọi bằng /skill-name, hoặc các nhắc lệnh theo ngữ cảnh mà Claude tự dùng khi phù hợp

• Máy chủ MCP: Kết nối tới dịch vụ và API bên ngoài để Claude truy cập dữ liệu mà bình thường không có

• Hooks: Script shell chạy tự động theo các sự kiện cụ thể, như trước khi chỉnh sửa tệp hoặc sau khi commit

Một plugin có thể chỉ chứa một trong số này, hoặc kết hợp nhiều phần hoạt động cùng nhau. Một plugin "triển khai" có thể bao gồm skill /deploy cho triển khai thủ công, một máy chủ MCP kiểm tra trạng thái môi trường staging của bạn, và một hook chạy test trước khi bất kỳ lệnh triển khai nào thực thi.

Tệp khai báo plugin.json định nghĩa nội dung plugin. Nó chỉ ra các skill, máy chủ MCP và hook cần cài, cùng siêu dữ liệu như tên plugin, phiên bản và tác giả. Khi bạn cài plugin, Claude Code đọc manifest này và thiết lập từng thành phần đúng vị trí.

Định dạng đóng gói này giúp bạn không cần hiểu cấu trúc tệp nội bộ của tiện ích mở rộng Claude Code. Bạn chỉ cần cài plugin, và mọi thứ sẽ vào đúng chỗ.

Tìm và cài đặt plugin Claude Code

Hầu hết plugin nằm ở hai nơi. Thư mục chính thức của Anthropic tại claude.com/plugins bao gồm plugin do Anthropic xây dựng, đóng góp đã xác minh từ cộng đồng, và tiện ích mở rộng phổ biến từ bên thứ ba. Mỗi mục liệt kê hiển thị các thành phần plugin chứa, thông tin tương thích và hướng dẫn cài đặt.

Nguồn thứ hai là GitHub:

Khi đã tìm được plugin mong muốn, lệnh cài đặt phụ thuộc vào nơi lưu trữ:

# From the official directory
claude plugin add @anthropic/deploy-helper
 
# From a GitHub repository
claude plugin add github:username/repo-name
 
# From a local directory (useful during development)
claude plugin add ./my-plugin

Sau khi cài vài plugin, bạn sẽ muốn theo dõi chúng. Lệnh plugin xử lý việc liệt kê, cập nhật và gỡ bỏ:

# List all installed plugins
claude plugin list
 
# Update a specific plugin to the latest version
claude plugin update @anthropic/deploy-helper
 
# Update all plugins
claude plugin update --all
 
# Remove a plugin
claude plugin remove @anthropic/deploy-helper

Một quyết định khi cài đặt là phạm vi. Plugin có thể tồn tại ở hai nơi: phạm vi người dùng cài vào ~/.claude/plugins/ và hoạt động trên mọi dự án của bạn, trong khi phạm vi dự án cài vào .claude/plugins/ trong một kho cụ thể.

Mặc định là phạm vi người dùng. Để cài plugin chỉ cho dự án hiện tại, thêm cờ --project:

claude plugin add @anthropic/deploy-helper --project

Plugin phạm vi dự án phù hợp khi tiện ích gắn với một codebase cụ thể. 

Plugin hiểu quy trình triển khai của công ty bạn nên đặt trong dự án đó. Plugin định dạng mã theo sở thích cá nhân nên đặt ở cấp người dùng. Khi plugin tồn tại ở cả hai phạm vi, phiên bản dự án sẽ được ưu tiên, cho phép nhóm áp dụng cấu hình riêng theo dự án trong khi nhà phát triển vẫn giữ plugin cá nhân hoạt động ở nơi khác.

Chọn đúng loại plugin Claude Code

Ba loại thành phần phục vụ mục đích khác nhau và tiêu thụ token cửa sổ ngữ cảnh theo cách khác nhau. Hiểu các đánh đổi này giúp bạn chọn đúng loại cho từng công việc.

Skills so với máy chủ MCP: Bài toán token

Máy chủ MCP nạp trước mọi định nghĩa công cụ vào cửa sổ ngữ cảnh khi bắt đầu phiên. Mỗi công cụ cần tên, mô tả và toàn bộ schema tham số, thường khoảng 100–300 token cho mỗi công cụ. Một thiết lập 5 máy chủ tiêu tốn xấp xỉ 55.000 token trước khi bạn gõ ký tự đầu tiên:

• GitHub: 35 công cụ
•  Slack: 11 công cụ
• Sentry: 5 công cụ
• Grafana: 5 công cụ
• Splunk: 2 công cụ

Một phân tích cho thấy thiết lập với 7+ máy chủ tiêu tốn hơn 67.000 token, tức là mất một phần ba cửa sổ ngữ cảnh 200K trước khi cuộc trò chuyện bắt đầu.

Skill dùng cách tiếp cận khác qua nạp dần. Khi khởi động phiên, Claude chỉ thấy tên và mô tả một dòng của mỗi skill từ YAML frontmatter, khoảng 100 token mỗi skill. 

Chỉ khi Claude xác định skill phù hợp với tác vụ hiện tại thì hướng dẫn đầy đủ mới được nạp. Tệp tham chiếu chỉ nạp khi thực sự cần. Còn script thì không bao giờ vào cửa sổ ngữ cảnh; Claude chạy chúng bên ngoài và chỉ nhận lại đầu ra.

Anthropic đã xử lý sự mất cân đối này vào cuối năm 2025 với Tool Search, tính năng mang cơ chế nạp lười cho máy chủ MCP. 

Thay vì nạp trước mọi định nghĩa công cụ, Claude Code nay phát hiện khi mô tả công cụ sẽ tiêu tốn hơn 10% ngữ cảnh sẵn có và chuyển sang nạp theo nhu cầu. 

Thử nghiệm nội bộ cho thấy mức dùng ngữ cảnh giảm từ ~134.000 token xuống ~5.000 token với thư viện công cụ lớn. Độ chính xác chọn công cụ cũng cải thiện, với Opus 4 tăng từ 49% lên 74% và Opus 4.5 từ 79,5% lên 88,1% trong bài đánh giá MCP.

Cách quyết định giữa chúng như sau.

Skill phù hợp nhất khi bạn muốn Claude truy cập tri thức hoặc quy trình và áp dụng có cân nhắc. Một skill mô tả checklist review mã của nhóm sẽ được nạp khi Claude review code, nhưng Claude vẫn quyết định cách áp dụng từng mục tùy ngữ cảnh. 

Skill cũng hợp với các thao tác cần script tính toán nặng, vì mã script nằm ngoài cửa sổ ngữ cảnh.

Máy chủ MCP phù hợp khi Claude cần dữ liệu thời gian thực từ dịch vụ bên ngoài như tin nhắn Slack, PR GitHub, hoặc truy vấn cơ sở dữ liệu. Chúng cũng là lựa chọn đúng khi nhiều agent AI cần dùng chung công cụ, hoặc khi bạn cần tính năng doanh nghiệp như nhật ký kiểm toán và quyền hạn rõ ràng.

Nhiều thiết lập kết hợp cả hai: skill cung cấp "cách làm" và "khi nào" qua hướng dẫn ngôn ngữ tự nhiên, còn máy chủ MCP xử lý các lời gọi API thực tế.

Những skill Claude Code phổ biến đáng cài

• Superpowers (hướng dẫn của chúng tôi): Hơn 20 quy trình đã kiểm chứng cho TDD, debug, và lập kế hoạch có cấu trúc
• frontend-design: Chỉ dẫn Claude tránh thẩm mỹ chung chung và đưa ra quyết định thiết kế táo bạo
• mcp-builder: Hướng dẫn tạo máy chủ MCP để tích hợp API bên ngoài
•  webapp-testing: Kiểm thử ứng dụng web cục bộ bằng Playwright để xác thực UI
•  skill-creator: Công cụ tương tác hướng dẫn bạn xây dựng skill mới

Những máy chủ MCP phổ biến đáng kết nối

• Context7: Tra cứu tài liệu theo thời gian thực, đúng phiên bản
• GitHub: Tìm kiếm kho, quản lý PR, theo dõi issue
• Playwright: Tự động hóa trình duyệt dùng cây khả năng truy cập thay vì ảnh chụp màn hình
• Supabase: Truy vấn cơ sở dữ liệu với nhận thức Row Level Security
• Sentry: Theo dõi lỗi và hiệu năng trực tiếp trong trình soạn thảo

Bạn cũng có thể đọc hướng dẫn về các máy chủ MCP từ xa hàng đầu.

Hooks: Lớp tất định

Hook nằm hoàn toàn ngoài cuộc tranh luận skill-so với-MCP. Trong khi cả skill và máy chủ MCP đều hướng về phía Claude (Claude quyết định khi nào dùng), hook thì hướng về hệ thống. Chúng kích hoạt theo các sự kiện như PreToolUse hoặc PostToolUse, chạy script shell trước hoặc sau khi Claude thực hiện hành động cụ thể. Claude không có quyền quyết định một hook có chạy hay không.

Điều này khiến Hook là lựa chọn đúng khi có việc phải xảy ra không ngoại lệ: linting trước mọi commit, chặn ghi vào thư mục bảo vệ, ghi log mọi lệnh bash, hoặc chạy test trước bất kỳ triển khai nào.

Nhà phát triển này khuyến nghị dùng hook "block-at-submit" thay vì "block-at-write". Chặn Claude giữa tác vụ sẽ gây nhầm lẫn cho agent và cho kết quả tệ hơn. Nhóm của cô ấy dùng hook PreToolUse bọc Bash(git commit) và kiểm tra tệp tạm chỉ tồn tại khi test qua. Không có tệp, không commit. Agent hoàn tất công việc rồi mới xác thực ở cuối.

Hook không thêm chi phí token vì chúng chạy như script shell bên ngoài cửa sổ ngữ cảnh.

Những hook Claude hữu ích nên thiết lập

• ESLint/Prettier khi chỉnh sửa: Tự động định dạng tệp sau khi Claude ghi
• Cổng kiểm thử khi commit: Chặn commit trừ khi test qua
• Đường dẫn bảo vệ: Ngăn ghi vào thư mục migrations, configs, hoặc vendor
• Thông báo khi hoàn tất: Gửi cảnh báo Slack hoặc desktop khi tác vụ dài hoàn thành
• Sao lưu bản ghi: Lưu lịch sử hội thoại trước khi nén

Cách tự xây plugin Claude Code

Khi một skill nằm trong thư mục cá nhân .claude/ của bạn, chỉ mình bạn dùng được. Đóng gói nó thành plugin cho phép bạn chia sẻ với đồng đội hoặc tái sử dụng giữa các dự án.

Chúng ta sẽ xây một plugin tên session-logger bổ sung lệnh /session-logger:summarize. Khi được gọi, Claude xem lại cuộc trò chuyện và bổ sung một bản tóm tắt có cấu trúc vào SESSION_LOG.md.

Tạo cấu trúc plugin

Plugin có thể đặt ở bất kỳ đâu trên hệ thống tệp. Trong hướng dẫn này, ta sẽ tạo một plugin trong thư mục nhà của bạn:

cd ~
mkdir -p session-logger/.claude-plugin
mkdir -p session-logger/skills/summarize

Cấu trúc được tạo:

~/session-logger/
├── .claude-plugin/
│   └── plugin.json  	# manifest goes here, nowhere else
└── skills/
	└── summarize/   	# folder name becomes the command name
    	└── SKILL.md 	# must be named exactly this

Viết manifest

Tạo ~/session-logger/.claude-plugin/plugin.json:

{
  "name": "session-logger",
  "description": "Log session summaries to a markdown file",
  "version": "1.0.0"
}

Trường name trở thành tiền tố namespace. Mọi lệnh trong plugin này sẽ bắt đầu với /session-logger:.

Viết skill

Tạo ~/session-logger/skills/summarize/SKILL.md:

---
description: Log a summary of the current session to SESSION_LOG.md
disable-model-invocation: true
---
 
When invoked, review the conversation and create a summary with these sections:
 
- **Date/time**: Current timestamp
- **Tasks completed**: What was accomplished
- **Files modified**: List of files created or changed
- **Decisions made**: Architectural or implementation choices
- **Open questions**: Unresolved items for future sessions
 
Append the summary to SESSION_LOG.md in the project root. Create the file if it doesn't exist.

Dòng disable-model-invocation: true báo cho Claude rằng chỉ bạn mới có thể kích hoạt skill này. Nếu thiếu cờ này, Claude có thể tự quyết định chạy lệnh nếu cho rằng hữu ích cho cuộc trò chuyện. Với công cụ ghi log hoặc triển khai, bạn thường muốn kiểm soát thủ công.

Kiểm thử cục bộ

Đi tới bất kỳ dự án nào bạn muốn dùng plugin, rồi khởi chạy Claude Code với cờ --plugin-dir trỏ tới plugin của bạn:

cd ~/your-project
claude --plugin-dir ~/session-logger

Gõ /session-logger:summarize để gọi lệnh. Lưu ý lệnh plugin sẽ không xuất hiện trong gợi ý tự hoàn thành cho đến khi bạn gõ đầy đủ tên. Văn bản sẽ chuyển màu xanh khi Claude Code nhận diện là lệnh hợp lệ.

Sau khi làm một số việc trong phiên, hãy chạy lệnh. Claude xem lại cuộc trò chuyện và bổ sung một mục vào SESSION_LOG.md trong thư mục dự án hiện tại của bạn.

Chia sẻ với người khác

Đẩy plugin của bạn lên GitHub. Để phân phối rộng hơn ngoài việc clone thủ công, hãy thêm nó vào marketplace plugin. Hướng dẫn marketplace bao gồm việc tạo marketplace của riêng bạn hoặc gửi lên các marketplace hiện có.

Lời kết

Plugin biến Claude Code từ một trợ lý đa dụng thành công cụ phù hợp chính xác với quy trình của bạn. Bộ ghi nhật ký phiên mà chúng ta xây dựng chỉ mất khoảng năm phút và ba tệp. Hầu hết plugin hữu ích cũng không phức tạp hơn nhiều.

Nếu bạn làm theo, giờ bạn đã có một plugin hoạt động trên máy. Hãy thử chỉnh sửa nó: thay đổi định dạng tóm tắt, thêm mục mới, hoặc thay bằng thứ nhóm bạn thực sự cần. Cấu trúc vẫn giữ nguyên dù bạn xây một công cụ cá nhân nhanh gọn hay thứ sẽ phân phối cho hàng trăm nhà phát triển.

Ngoài ra, hãy duyệt các kho cộng đồng khi có dịp. Cách người khác cấu trúc plugin sẽ dạy bạn những mẫu thiết kế mà tài liệu khó truyền đạt.

Để tìm hiểu sâu hơn về Claude Code, hãy xem các hướng dẫn về thực hành tốt nhất với Claude Code, khung kỹ năng Superpowers, slash command cho các phiên dài, và bảo mật và quyền hạn. Nếu muốn tìm hiểu thêm về các mô hình Claude, tôi khuyên dùng khóa học Giới thiệu về các mô hình Claude.