Agent Plugin là gì? Đây là một gói thư mục dùng để đóng gói các thành phần mở rộng cho AI agent, chủ yếu gồm Agent Skills và cấu hình MCP server. Thay vì sao chép cùng một kỹ năng sang từng công cụ với nhiều cấu trúc khác nhau, bạn chuẩn bị một thư mục chuẩn có plugin.json, thư mục skills/ và tùy chọn mcp.json. Những ứng dụng hỗ trợ chuẩn có thể đọc và nạp lại các thành phần này theo cùng quy tắc. Agent Plugins 1.0.0 hiện định nghĩa hai loại thành phần di động là skill và MCP server, không phải một runtime AI hoàn chỉnh hay một chợ plugin chung (theo agent-plugins.org).
Giá trị chính của định dạng này là khả năng tương tác AI. Bạn vẫn phải kiểm tra từng client có hỗ trợ chuẩn, transport MCP và cách cấp quyền hay không; một plugin hợp lệ không tự động chạy giống nhau trên mọi công cụ.
Agent Plugin là gì và giải quyết vấn đề nào?
Trong thực tế, một AI agent thường cần hai lớp mở rộng. Lớp thứ nhất là skill: hướng dẫn quy trình, tiêu chí, định dạng đầu ra hoặc cách sử dụng tài liệu. Lớp thứ hai là tool: khả năng truy cập hệ thống bên ngoài như cơ sở dữ liệu, API, kho mã nguồn hoặc dịch vụ tìm kiếm. MCP server thường đảm nhiệm lớp thứ hai, còn SKILL.md mô tả lớp thứ nhất.
Agent Plugin gom hai lớp này vào một gói có vị trí tệp cố định:
plugin.json: manifest bắt buộc ở thư mục gốc.skills/: mỗi thư mục con trực tiếp có thể chứa mộtSKILL.md.mcp.json: cấu hình một hoặc nhiều MCP server, nếu plugin cần công cụ bên ngoài.- Thư mục mở rộng theo namespace ngược tên miền, chẳng hạn
com.example.client/, dành cho dữ liệu riêng của từng client.
Chuẩn không cho phép plugin.json tự định nghĩa đường dẫn tùy ý cho skill hoặc MCP. Client phải tìm skill trong skills/ và cấu hình MCP tại mcp.json. Nếu một vị trí tùy chọn không tồn tại, đó không phải lỗi; plugin có thể chỉ chứa skill hoặc chỉ chứa MCP server (theo agent-plugins.org).
Điểm cần phân biệt là Agent Plugin không thay thế MCP. MCP vẫn quy định cách client và server giao tiếp, vòng đời kết nối cũng như việc cung cấp công cụ. Agent Plugins chỉ quy định cách đóng gói và chỉ dẫn client tìm cấu hình MCP ở đâu.
Nếu bạn vận hành blog hoặc website muốn nội dung dễ được tác nhân AI đọc và sử dụng, hãy tham khảo checklist tối ưu blog cho AI agent để xử lý cấu trúc, dữ liệu và khả năng truy xuất ngay từ nguồn.
Cấu trúc Agent Plugins 1.0.0 và cách đóng gói
1. Tạo manifest plugin.json
Trong Agent Plugins 1.0.0, plugin.json phải là một đối tượng JSON ở thư mục gốc. Hai trường bắt buộc là $schema và name. Các trường như version, description, author, homepage, repository, license, keywords và extensions là tùy chọn.
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "content-audit",
"version": "1.0.0",
"description": "Kiểm tra cấu trúc và chất lượng nội dung blog",
"author": {
"name": "Example Studio"
},
"license": "MIT",
"keywords": ["seo", "content", "audit"]
}Giá trị name phải dài từ 1 đến 64 ký tự, chỉ dùng chữ thường, chữ số, dấu gạch ngang hoặc dấu chấm; không được bắt đầu hay kết thúc bằng dấu phân cách, đồng thời không dùng chuỗi -- hoặc ... Đây là lỗi thường khiến manifest bị từ chối ngay cả khi JSON không sai cú pháp (theo agent-plugins.org).
2. Thêm skill vào skills/
Mỗi skill cần nằm trong một thư mục con trực tiếp của skills/. Ví dụ:
content-audit/
├── plugin.json
├── skills/
│ └── seo-review/
│ ├── SKILL.md
│ ├── references/
│ │ └── checklist.md
│ └── scripts/
│ └── check-links.py
└── mcp.jsonClient không tìm đệ quy vô hạn. Vì vậy, đặt SKILL.md tại skills/seo-review/SKILL.md là đúng, còn đặt sâu hơn như skills/seo-review/docs/SKILL.md có thể khiến skill không được phát hiện. Nội dung và frontmatter của SKILL.md phải tuân theo đặc tả Agent Skills; tên skill trong frontmatter nên khớp với tên thư mục để tránh lỗi định tuyến (theo agentskills.io).
Hãy viết phần mô tả skill theo hướng “khi nào cần nạp skill này” thay vì chỉ mô tả chủ đề. Ví dụ: “Nạp khi cần kiểm tra tiêu đề, liên kết nội bộ và dữ liệu có cấu trúc của bài blog”. Cách viết này giúp agent quyết định đúng thời điểm, giảm việc nạp hướng dẫn không liên quan.
3. Khai báo MCP server trong mcp.json
Nếu skill cần gọi công cụ bên ngoài, tạo mcp.json tại thư mục gốc:
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"local-audit": {
"type": "stdio",
"command": "./bin/audit-server",
"args": ["--data", "${PLUGIN_DATA}/audit"],
"cwd": "${PLUGIN_ROOT}"
},
"remote-search": {
"type": "streamable-http",
"url": "https://example.com/mcp"
}
}
}Với stdio, command phải là một token thực thi, không phải chuỗi shell kiểu node server.js && echo done. Đường dẫn tương đối phải bắt đầu bằng ./. Các biến ${PLUGIN_ROOT} và ${PLUGIN_DATA} hữu ích để phân biệt tệp đóng gói cố định với dữ liệu phát sinh cần tồn tại sau khi cập nhật plugin.
Không đặt khóa API hoặc mật khẩu trong env, headers, mã nguồn hay manifest. Agent Plugins 1.0.0 không định nghĩa cơ chế lưu trữ bí mật di động; việc đăng nhập, OAuth và quản lý thông tin xác thực thuộc về client. Đây là giới hạn bảo mật quan trọng: “dùng được trên nhiều công cụ” không đồng nghĩa “dùng chung một cách cấp quyền”.
4. Đóng gói, kiểm tra và phát hành
- Tạo thư mục plugin với đúng tên và cấu trúc.
- Kiểm tra JSON bằng trình phân tích cú pháp trước khi đưa lên Git.
- Đối chiếu
$schematrongplugin.jsonvàmcp.json; hai phiên bản phải khớp. - Kiểm tra từng
SKILL.md, đặc biệt là frontmatter, tên thư mục và đường dẫn tệp tham chiếu. - Chạy thử trên từng client mục tiêu, với cả trường hợp thiếu MCP server hoặc sai thông tin xác thực.
- Ghi rõ yêu cầu cài đặt, biến môi trường, quyền truy cập và transport được hỗ trợ trong README.
Cách kiểm tra kết quả thực tế là yêu cầu agent liệt kê skill đã nạp, kiểm tra MCP server có hoàn tất handshake hay chưa, sau đó chạy một tác vụ nhỏ có thể đối chiếu bằng tay. Nếu MCP lỗi, skill vẫn nên được nạp; đặc tả yêu cầu client tiếp tục tải các thành phần khác thay vì làm hỏng toàn bộ plugin.
Giới hạn, lỗi thường gặp và cách dùng hiệu quả
Thứ nhất, không phải client nào cũng tương thích đầy đủ. Một client có thể đọc skill nhưng chưa hỗ trợ MCP, hoặc chỉ hỗ trợ stdio mà chưa hỗ trợ streamable-http. Hãy công bố ma trận tương thích thay vì tuyên bố plugin chạy trên mọi công cụ.
Thứ hai, plugin không phải sandbox. Quy tắc đường dẫn giúp client ngăn tham chiếu thoát khỏi thư mục plugin trong các trường hợp được đặc tả, nhưng không tự động hạn chế mọi hành vi của tiến trình MCP. Bạn vẫn cần đánh giá mã nguồn, quyền hệ điều hành, phụ thuộc bên thứ ba và dữ liệu mà server có thể truy cập.
Thứ ba, đừng nhồi mọi logic vào skill. Skill nên chứa quy trình và tiêu chí ra quyết định; MCP server nên cung cấp thao tác hoặc dữ liệu có giao diện rõ ràng. Nếu một SKILL.md vừa dài, vừa chứa thông tin thay đổi liên tục, vừa mô tả hàng chục công cụ, agent sẽ khó định tuyến và khó bảo trì.
Thứ tư, đừng dùng trường tùy ý ở cấp cao nhất của plugin.json. Dữ liệu riêng cho client phải đặt trong extensions với namespace ổn định, chẳng hạn com.example.client. Client khác sẽ bỏ qua namespace mà nó không triển khai, nhờ đó giảm xung đột giữa các hệ sinh thái.
Với website, việc mô tả tác giả, phạm vi chuyên môn và trách nhiệm nội dung cũng quan trọng khi các agent đánh giá nguồn. Bạn có thể xem thêm cách tạo trang tác giả cho blog để củng cố tín hiệu tin cậy trước khi đóng gói nội dung thành skill.
Cuối cùng, hãy quản lý phiên bản plugin độc lập với phiên bản đặc tả. Agent Plugins 1.0.0 là phiên bản của định dạng; trường version trong plugin.json là phiên bản riêng của plugin. Khi thay đổi hành vi, MCP endpoint hoặc yêu cầu cài đặt, hãy cập nhật changelog và mô tả tác động để người dùng biết có cần cấu hình lại hay không.
Kết luận: Agent Plugin phù hợp khi bạn muốn phân phối một kỹ năng AI có cấu trúc, kèm công cụ MCP server tùy chọn, qua một thư mục thống nhất. Quy trình an toàn nhất là bắt đầu với manifest tối thiểu, thêm một skill nhỏ, kiểm tra trên client mục tiêu, rồi mới bổ sung MCP và các phần mở rộng. Chuẩn này cải thiện khả năng tương tác AI ở lớp đóng gói, nhưng vẫn để client quyết định cách cài đặt, cấp quyền, hiển thị và thực thi.
Nếu bạn đang tối ưu nội dung để nhiều hệ thống AI có thể hiểu và sử dụng, hãy kết hợp plugin với hướng dẫn tối ưu blog cho AI Overviews và AI Mode; hai việc này giải quyết hai lớp khác nhau: plugin chuẩn hóa thành phần của agent, còn SEO giúp nguồn nội dung dễ được khám phá.
Nguồn tham khảo
