Agent Skills — /.well-known/agent-skills/index.json
Tóm tắt
Một Agent Skill là một tệp SKILL.md: tên, một dòng mô tả và hướng dẫn mà AI agent nạp vào khi gặp việc phù hợp. Agent Skills Discovery RFC (Cloudflare, v0.2.0, tháng 3/2026) cho website một chỗ cố định để liệt kê các skill mình công bố: /.well-known/agent-skills/index.json. Agent đọc danh sách, cài skill, rồi đối chiếu tệp với mã sha256 ghi trong danh sách.
Giải thích đơn giản
Cửa hàng ghim một bảng thẻ hướng dẫn ở cửa: cách đặt hàng, cách đổi trả, cách tra đơn. Trợ lý robot đọc bảng, lấy đúng thẻ cần dùng, và kiểm tra dấu niêm phong để biết không ai tráo thẻ.
Tệp danh sách (RFC v0.2.0):
GET /.well-known/agent-skills/index.json
Content-Type: application/json
{"$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
"skills": [
{"name": "code-review",
"type": "skill-md",
"description": "Review code for bugs. Use when …",
"url": "/.well-known/agent-skills/code-review/SKILL.md",
"digest": "sha256:<64 ký tự hex thường>"}
]}Các quy tắc chính:
- $schema là bắt buộc và cho biết phiên bản; client không nên xử lý danh sách có $schema lạ.
- Mỗi mục cần đủ năm trường. name: 1-64 ký tự, gồm a-z, 0-9 và dấu gạch nối đơn. type: skill-md (một tệp SKILL.md) hoặc archive (.tar.gz hoặc .zip, SKILL.md nằm ở gốc). description: tối đa 1024 ký tự, nói skill làm gì và khi nào dùng. url: nơi đặt tệp, tính theo URL của danh sách. digest: SHA-256 của nội dung tệp.
- Client PHẢI kiểm tra digest và KHÔNG được dùng nội dung sai digest — mục không có digest là mục không dùng được.
- Bản thân SKILL.md mở đầu bằng YAML frontmatter có name và description (đặc tả agentskills.io).
Không phải danh sách skill: /.well-known/agent.json là đường dẫn cũ của A2A agent card (nay là agent-card.json), còn /.well-known/ai-plugin.json là manifest plugin ChatGPT, đã ngừng từ 2024. Bản nháp v0.1.0 dùng /.well-known/skills/index.json với danh sách files và không có digest; client v0.2.0 chỉ tìm ở /.well-known/agent-skills/.
⚡Tại sao quan trọng
Skill là cách rẻ nhất để dạy agent dùng đúng sản phẩm của bạn: gọi endpoint nào, tham số gì, gặp lỗi thì làm gì. Không có danh sách, agent hoặc người dùng phải tự tìm skill trong một repo GitHub. Tài liệu developer của Cloudflare, Vercel và Redocly đã công bố danh sách này. Website không có sản phẩm nào để agent thao tác thì không cần — vì vậy mức độ của check này là thấp.
🔍CiteStat kiểm tra thế nào
CiteStat tải /.well-known/agent-skills/index.json, nếu không có thì tải đường dẫn v0.1.0 /.well-known/skills/index.json. Đạt khi đó là danh sách v0.2.0 trả về dạng application/json và mọi mục đều có name, type, description, url và digest sha256 hợp lệ. Mục sai quy tắc, danh sách rỗng, $schema lạ hoặc JSON không có mảng skills là lỗi mức trung bình; danh sách v0.1.0 hoặc sai media type là mức thấp. Trang HTML tại đường dẫn này được tính là không có danh sách. Bản quét chỉ đọc danh sách, không tải các skill.
Điểm CiteStat
Một trong 9 check chính của thẻ Agent Readiness (điểm = số check chính đạt / 9 × 10). Không làm thay đổi điểm SEO tổng.
Độ khó sửa
Biên tập viên: Khó | Lập trình viên: Dễ | AI Agent: Dễ