Agent Skills Discovery: cách AI agent tìm skill của bạn

Câu trả lời ngắn: một Agent Skill là một thư mục có tệp SKILL.md: phần đầu YAML gồm name và description, sau đó là hướng dẫn bằng markdown để AI agent làm một việc cụ thể. Để agent tìm thấy skill của bạn mà không cần cài đặt tay, đặt một chỉ mục tại /.well-known/agent-skills/index.json, trả về với Content-Type: application/json. Mỗi mục trong chỉ mục có năm trường bắt buộc: name, type, description, url và digest (SHA-256 của tệp).

Skill là gì, và vì sao cần chỉ mục

Định dạng Agent Skills do Anthropic phát triển và phát hành thành chuẩn mở tại agentskills.io. Một skill dạy agent một quy trình: triển khai một ứng dụng, chạy một lượt quét, dùng đúng một API. Agent nạp skill theo ba tầng, gọi là progressive disclosure:

1. Lúc khởi động, chỉ đọc name và description — khoảng 100 token mỗi skill.
2. Khi việc cần đến skill, đọc toàn bộ SKILL.md — khuyến nghị dưới 5.000 token.
3. Tệp phụ trong scripts/, references/, assets/ chỉ nạp khi một bước cần đến.

Nhờ vậy agent có thể biết hàng trăm skill mà không làm đầy ngữ cảnh.

Vấn đề là tìm skill. Trước đây người dùng phải tự tải và cài. Đặc tả Agent Skills Discovery via Well-Known URIs của Cloudflare (bản nháp v0.2.0, cập nhật 12/3/2026) đặt danh sách skill ở một đường dẫn cố định, giống API catalog cho API (xem bài hướng dẫn API catalog) và llms.txt cho nội dung.

Chỉ mục Agent Skills trông như thế nào

Đây là chỉ mục của chính chúng tôi, tải ngày 23/10/2026 (tệp skill: SKILL.md):

GET /.well-known/agent-skills/index.json
Content-Type: application/json

{"$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
 "skills": [
  {"name": "citestat-seo-audit",
   "type": "skill-md",
   "description": "Audit a web page's SEO and AI-search readiness with the CiteStat API: ...",
   "url": "https://citestat.com/.well-known/agent-skills/citestat-seo-audit/SKILL.md",
   "digest": "sha256:6dd30b6f0489348cfd7ec111098168dd15794c4cf42044a7c568d7eb964a5090"}
 ]}

Các quy tắc chính trong đặc tả:

• $schema cho biết phiên bản. Agent phải đọc nó trước; giá trị lạ thì không xử lý chỉ mục.
• name: 1–64 ký tự, chữ thường, số và dấu gạch nối, không bắt đầu hoặc kết thúc bằng gạch nối, không có hai gạch nối liền nhau. Tên phải trùng với tên thư mục của skill.
• type là skill-md (một tệp SKILL.md) hoặc archive (.tar.gz hoặc .zip có SKILL.md ở gốc).
• description tối đa 1.024 ký tự, nên trùng với phần đầu của SKILL.md: skill làm gì và khi nào dùng.
• url có thể tương đối hoặc tuyệt đối, kể cả ở tên miền khác.
• digest có dạng sha256: + 64 ký tự hex thường. Agent phải kiểm tra tệp tải về với digest và không được dùng tệp không khớp.

Vì sao digest là quy tắc quan trọng nhất

Một trang web sai chỉ làm agent trả lời sai. Một skill sai làm agent hành động sai, vì skill là chỉ dẫn mà agent sẽ làm theo. Vì vậy đặc tả xử lý skill như phần mềm. Agent phải:

• kiểm tra digest trước khi dùng tệp, và kiểm tra digest của archive trước khi giải nén;
• từ chối archive có đường dẫn .. hoặc liên kết trỏ ra ngoài thư mục skill;
• không chạy tệp trong scripts/ theo mặc định;
• và, theo khuyến nghị của đặc tả, chỉ tin các nguồn trong danh sách cho phép.

Hệ quả cho người công bố: mỗi lần sửa SKILL.md mà quên tính lại digest, mọi agent đúng chuẩn sẽ từ chối skill đó.

Chúng tôi kiểm tra chỉ mục Agent Skills của 8 website

Ngày 23/10/2026, chúng tôi chạy chính bộ chấm của bản quét CiteStat (packages/core/agent-skills.ts) trên 8 website. Với các chỉ mục đạt, chúng tôi tải thêm từng tệp được liệt kê và tính SHA-256 — việc đặc tả yêu cầu agent làm:

Website	Chỉ mục	Digest khớp
developers.cloudflare.com	Đạt — 19 skill (11 SKILL.md, 8 archive)	19/19
vercel.com	Đạt — 9 skill (3 SKILL.md, 6 archive), tệp đặt trên github.com	9/9
blog.cloudflare.com	Đạt — 1 skill	1/1
citestat.com	Đạt — 1 skill	1/1
docs.stripe.com	Định dạng cũ v0.1.0 tại /.well-known/skills/ — 10 skill, không có digest	—
docs.claude.com	Không có	—
github.com	Không có	—
erpfit.com	Không có	—

Ngày 23/10/2026, 4 trong 8 website có chỉ mục v0.2.0 hợp lệ (tổng cộng 30 skill), và cả 30 tệp đều khớp digest. Các phát hiện khác:

• Tệp của Vercel nằm trên GitHub Releases, không phải vercel.com, và trả về với application/octet-stream. Đặc tả cho phép đặt ở máy chủ khác, nhưng bắt buộc máy chủ trả SKILL.md với text/markdown hoặc text/plain, archive với application/gzip hoặc application/zip. Digest vẫn khớp nên agent dễ tính vẫn dùng được; agent dùng danh sách nguồn cho phép phải tin cả github.com.
• Stripe công bố 10 skill theo định dạng cũ v0.1.0: đường dẫn cũ, mảng files, không digest. Đặc tả nói rõ v0.2.0 không tương thích ngược, và agent v0.2.0 chỉ tìm ở /.well-known/agent-skills/, nên các skill đó không được tìm thấy — và không có digest thì cũng không kiểm tra được.

Hiện nay agent nào đọc chỉ mục?

Đến ngày 23/10/2026, chúng tôi chưa thấy agent lớn nào ghi trong tài liệu rằng nó tự tải /.well-known/agent-skills/index.json. Đặc tả vẫn là bản nháp của Cloudflare. Ngày 30/6/2026, một người đóng góp viết trong kho mã (issue #13) rằng kế hoạch là đưa nó chính thức vào đặc tả Agent Skills. Công bố bây giờ chỉ tốn một tệp JSON; lợi ích phụ thuộc vào việc chuẩn được áp dụng.

Lỗi của chính chúng tôi

Trước ngày 23/10/2026, bản quét CiteStat chấm sai mục này theo cả hai chiều. Nó cho đạt bất kỳ JSON nào tại /.well-known/agent.json (thực ra là thẻ agent của giao thức A2A), agent-skills.json hoặc ai-plugin.json (plugin ChatGPT, đã ngừng từ 2024), và không bao giờ đọc đường dẫn thật. Kết quả: developers.cloudflare.com với 19 skill và Vercel với 9 skill bị báo "không có", còn citestat.com — khi đó chưa có skill nào — lại đạt nhờ tệp agent.json. Chúng tôi đã sửa bộ chấm theo đặc tả v0.2.0 và công bố skill citestat-seo-audit. Digest của nó được tính từ chính các byte máy chủ trả về, và một bài kiểm tra tự động chạy bộ chấm của bản quét trên chỉ mục của chúng tôi.

Cách công bố skill trong bốn bước

1. Viết SKILL.md. Phần đầu YAML có name (trùng tên thư mục) và description nói skill làm gì và khi nào dùng. Thân bài là các bước, ví dụ lệnh, lỗi thường gặp. Giữ dưới 500 dòng.
2. Đặt tệp tại /.well-known/agent-skills/<name>/SKILL.md, trả về với text/markdown.
3. Tính digest: shasum -a 256 SKILL.md, rồi ghi sha256:<hex> vào chỉ mục.
4. Viết chỉ mục index.json với $schema v0.2.0 và mảng skills, trả về với application/json. Nếu có thể, tạo digest trong bước build để nó không bao giờ lệch khỏi tệp.

Nếu agent không có gì để thao tác trên website của bạn — không API, không CLI, không quy trình — hãy bỏ qua toàn bộ phần này. Một skill chỉ nhắc lại nội dung quảng cáo không dạy agent điều gì.

CiteStat kiểm tra những gì

Trong thẻ Agent Readiness, bản quét đọc /.well-known/agent-skills/index.json. Đạt khi chỉ mục là v0.2.0 và mọi mục có đủ năm trường hợp lệ. Mục thiếu trường, digest sai dạng, $schema lạ hoặc không có mảng skills là lỗi mức trung bình. Định dạng cũ v0.1.0, sai media type hoặc không có chỉ mục là mức thấp. Mục này không đổi điểm SEO tổng. Bạn có thể tự kiểm tra website của mình miễn phí, 10 lượt mỗi ngày; nếu bạn kiểm tra website khách hàng hằng tuần, gói Pro cho 100 lượt mỗi ngày với giá 500.000₫/tháng (chưa VAT) — xem bảng giá.

Câu hỏi thường gặp

Agent Skills khác MCP server thế nào?

MCP server cung cấp công cụ mà agent gọi được. Skill là hướng dẫn bằng văn bản: khi nào dùng, các bước, ví dụ. Hai thứ bổ sung cho nhau — một skill có thể hướng dẫn agent dùng API hoặc MCP server của bạn cho đúng.

Website nào nên công bố chỉ mục Agent Skills?

Website có sản phẩm mà agent thao tác thay người dùng: API, CLI, nền tảng triển khai, công cụ cho lập trình viên. Website chỉ có nội dung đọc thì không cần; llms.txt và markdown phù hợp hơn. Vì vậy bản quét CiteStat chỉ báo thiếu chỉ mục ở mức thấp.

Digest dùng để làm gì?

Digest là SHA-256 của tệp skill. Đặc tả bắt buộc agent kiểm tra tệp tải về với digest và không dùng tệp không khớp. Skill là chỉ dẫn mà agent sẽ làm theo, nên tệp bị sửa trên đường truyền hoặc trên CDN không được phép lọt vào. Mỗi lần sửa SKILL.md phải tính lại digest.

Agent Skills có giúp tăng thứ hạng Google không?

Tài liệu của Google hoàn toàn không nhắc đến Agent Skills. Chỉ mục giúp agent làm việc thay người dùng, không giúp thứ hạng tìm kiếm. Bản quét CiteStat chỉ hiển thị nó trong thẻ Agent Readiness; điểm SEO tổng của bạn không đổi.

Nguồn: Agent Skills Discovery via Well-Known URIs (Cloudflare, bản nháp v0.2.0, cập nhật 12/3/2026) · Agent Skills specification (agentskills.io) · RFC 8615 (Well-Known URIs). Dữ liệu 8 website và 30 digest: tải ngày 23/10/2026.