Thông số kỹ thuật, định dạng đầy đủ cho Agent Skills

Cấu trúc thư mục

Skill là một thư mục chứa ít nhất một file SKILL.md:

skill-name/
├── SKILL.md          # Yêu cầu: siêu dữ liệu + hướng dẫn
├── scripts/          # Tùy chọn: code thực thi
├── references/       # Tùy chọn: tài liệu
├── assets/           # Tùy chọn: template, tài nguyên
└── ...               # Bất kỳ file hoặc thư mục bổ sung nào

Định dạng SKILL.md

File SKILL.md phải chứa phần đầu YAML theo sau là nội dung Markdown.

Phần đầu

Ví dụ tối thiểu:

---
name: tên-skill
description: Mô tả skill này làm được gì và khi nào nên sử dụng nó.
---

Ví dụ với các trường tùy chọn:

---
name: pdf-processing
description: Trích xuất văn bản PDF, điền biểu mẫu, hợp nhất file. Sử dụng khi xử lý các file PDF.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

Trường name

Trường name là bắt buộc:

• Phải có độ dài từ 1 đến 64 ký tự
• Chỉ được chứa các ký tự chữ số viết thường Unicode (a-z) và dấu gạch ngang (-)
• Không được bắt đầu hoặc kết thúc bằng dấu gạch ngang (-)
• Không được chứa các dấu gạch ngang liên tiếp (--)
• Phải trùng khớp với tên thư mục cha

Ví dụ hợp lệ:

name: pdf-processing

name: data-analysis

name: code-review

Ví dụ không hợp lệ:

• name: PDF-Processing # không được viết hoa
• name: -pdf # không được bắt đầu bằng dấu gạch ngang
• name: pdf--processing # không cho phép dấu gạch ngang liên tiếp

Trường description

Trường description là bắt buộc:

• Phải có độ dài từ 1 đến 1024 ký tự
• Cần mô tả cả chức năng của skill và thời điểm sử dụng skill đó
• Cần bao gồm các từ khóa cụ thể giúp người dùng xác định những nhiệm vụ liên quan

Ví dụ về một mô tả tốt:

description: Trích xuất văn bản và bảng biểu từ các file PDF, điền vào những biểu mẫu PDF và hợp nhất nhiều file PDF. Sử dụng khi làm việc với tài liệu PDF hoặc khi người dùng đề cập đến PDF, biểu mẫu hoặc trích xuất tài liệu.

Ví dụ về một mô tả kém:

description: Hỗ trợ xử lý file PDF.

Trường license

Trường license là tùy chọn:

• Chỉ định giấy phép được áp dụng cho skill
• Bạn nên giữ cho trường này ngắn gọn (hoặc tên của giấy phép hoặc tên của file giấy phép đi kèm)

Ví dụ:

license: Thuộc sở hữu độc quyền. File LICENSE.txt chứa đầy đủ các điều khoản.

Trường compatibility

Trường compatibility là tùy chọn:

• Phải có độ dài từ 1 đến 500 ký tự nếu được cung cấp
• Chỉ nên bao gồm trường này nếu skill của bạn có các yêu cầu môi trường cụ thể
• Có thể cho biết sản phẩm dự định sử dụng, các gói hệ thống cần thiết, nhu cầu truy cập mạng, v.v...

Ví dụ:

compatibility: Được thiết kế cho Claude Code (hoặc các sản phẩm tương tự)

compatibility: Yêu cầu git, docker, jq và kết nối Internet

compatibility: Yêu cầu Python 3.14 trở lên và uv

Hầu hết các skill không cần trường compatibility.

Trường metadata

Trường metadata là tùy chọn:

• Một bản đồ từ khóa chuỗi đến giá trị chuỗi
• Client có thể sử dụng trường này để lưu trữ các thuộc tính bổ sung không được định nghĩa trong thông số Agent Skills
• Bạn nên đặt tên khóa tương đối độc đáo để tránh xung đột ngoài ý muốn

Ví dụ:

metadata:
  author: example-org
  version: "1.0"

Trường allowed-tools

Trường allowed-tools là tùy chọn:

• Một danh sách các công cụ được phân tách bằng dấu cách đã được phê duyệt trước để chạy.
• Thử nghiệm. Việc hỗ trợ trường này có thể khác nhau giữa các triển khai agent.

Ví dụ:

allowed-tools: Bash(git:*) Bash(jq:*) Read

Nội dung chính

Phần nội dung Markdown sau phần mở đầu chứa hướng dẫn skill. Không có hạn chế về định dạng. Hãy viết bất cứ điều gì giúp các agent thực hiện nhiệm vụ một cách hiệu quả.

Các phần được đề xuất:

• Hướng dẫn từng bước
• Ví dụ về đầu vào và đầu ra
• Các trường hợp ngoại lệ thường gặp

Lưu ý rằng agent sẽ load toàn bộ file này sau khi quyết định kích hoạt một skill. Hãy cân nhắc chia nội dung SKILL.md dài hơn thành các file tham chiếu.

​Các thư mục tùy chọn

scripts/

Chứa code thực thi mà các agent có thể chạy. Các script nên:

• Độc lập hoặc ghi rõ các dependency
• Bao gồm các thông báo lỗi hữu ích
• Xử lý các trường hợp ngoại lệ một cách khéo léo

Các ngôn ngữ được hỗ trợ phụ thuộc vào cách triển khai của agent. Các tùy chọn phổ biến bao gồm Python, Bash và JavaScript.

​references/

Chứa tài liệu bổ sung mà các agent có thể đọc khi cần:

• REFERENCE.md - Tài liệu tham khảo kỹ thuật chi tiết
• FORMS.md - Mẫu biểu mẫu hoặc định dạng dữ liệu có cấu trúc
• Các file chuyên biệt theo lĩnh vực (finance.md, legal.md, v.v...)

Giữ cho các file tham khảo riêng lẻ tập trung vào chủ đề. Các agent load những tài nguyên này theo yêu cầu, vì vậy kích thước file nhỏ hơn đồng nghĩa với việc sử dụng ngữ cảnh ít hơn.

​assets/

Chứa các tài nguyên tĩnh:

• Template (template tài liệu, template cấu hình)
• Hình ảnh (sơ đồ, ví dụ)
• File dữ liệu (bảng tra cứu, lược đồ)

Mẹo cấu trúc skill

Các skill nên được cấu trúc để sử dụng ngữ cảnh hiệu quả:

1. Siêu dữ liệu (~100 token): Những trường name và description được load khi khởi động cho tất cả các skill
2. Hướng dẫn (< 5000 token được khuyến nghị): Toàn bộ nội dung SKILL.md được load khi skill được kích hoạt
3. Tài nguyên (khi cần): Các file (ví dụ: các file trong scripts/, references/ hoặc assets/) chỉ được load khi cần

Giữ file SKILL.md chính của bạn dưới 500 dòng. Chuyển tài liệu tham khảo chi tiết sang các file riêng biệt.

T​ham chiếu file

Khi tham chiếu các file khác trong skill của bạn, hãy sử dụng đường dẫn tương đối từ thư mục gốc của skill:

Xem [the reference guide](references/REFERENCE.md) để biết chi tiết.

Chạy script trích xuất:
scripts/extract.py

Giữ các tham chiếu file ở độ sâu một cấp so với SKILL.md. Tránh các chuỗi tham chiếu lồng nhau quá sâu.

Xác thực

Sử dụng thư viện tham chiếu skills-ref để xác thực các skill của bạn:

skills-ref validate ./my-skill

Thao tác này kiểm tra xem phần đầu của file SKILL.md có hợp lệ và tuân thủ tất cả các quy ước đặt tên hay không.