SKILL.md: một header YAML ngắn (frontmatter) đặt tên skill và cho biết khi nào dùng, tiếp theo là phần hướng dẫn viết bằng Markdown. Trang này trình bày các quy tắc mà file phải đáp ứng để tải được, và các cách viết giúp agent làm theo.
Skill hợp lệ tối thiểu
Sao chép đoạn này, đổi tên, mô tả và quy tắc, là skill sẽ tải được:Các trường frontmatter
Các trường khác, như
license hay allowed-tools trong các file SKILL.md viết cho công cụ khác, không chặn việc tải lên, và CloudThinker không dùng chúng. Skill chuyển từ công cụ khác sang vẫn tải được, miễn là có name và description.
Ví dụ về tên:
Khi bạn tạo skill bằng Write skill instructions, CloudThinker tự dựng frontmatter từ các trường Skill name và Description. Bạn chỉ tự viết frontmatter khi tải lên file
.zip hoặc sửa SKILL.md bằng tay.Cấu trúc gói zip
Dùng.zip khi skill cần file hỗ trợ, hoặc để chuyển skill giữa các workspace. Tải lên từ More → Workspace settings → Skills → + (cạnh Search skills) → Upload zip file.
-
Đặt
SKILL.mdở thư mục gốc của zip hoặc bên trong một thư mục cấp cao nhất. Skill lấy tên từnametrong frontmatter, nên tên thư mục không cần khớp. -
Đặt tên file zip đúng bằng
nametrong frontmatter, kể cả chữ hoa chữ thường (ví dụsecurity-review-checklist.zip). CloudThinker dùng tên file zip để nhận ra skill đã có và đề xuất Replace. Nếu hai tên khác nhau, Replace có thể xóa skill trùng với tên zip và tải lên một skill dưới tên khác. Khi không có skill nào trùng, lần tải lên cónametrong frontmatter đã bị dùng sẽ thất bại với This skill name is already in use. -
Chỉ
scripts/,schemas/vàreferences/được giữ lại. Các file và thư mục khác bị bỏ qua. -
Tham chiếu file hỗ trợ từ
SKILL.mdbằng đường dẫn tương đối. Agent không tự đọc các file này: agent chỉ mở file khi hướng dẫn trỏ tới, ví dụ: -
Với script, hãy nêu tên và nói khi nào chạy, ví dụ “Run
scripts/check_tags.shwith the account ID.” Script có thể là Bash hoặc TypeScript (chạy bằngbun). Agent chạy script bằng chính công cụ lệnh dùng cho mọi lệnh khác, nên mọi thao tác ghi của script đều đi qua Approvals như các lệnh khác. -
Script nhận Credentials của workspace dưới dạng biến môi trường, đặt tên theo Key của từng credential. Credential có key
DATADOG_API_KEYsẽ là$DATADOG_API_KEYtrong script.
Credential không dành riêng cho script của skill: mọi lệnh agent chạy đều nhận mọi credential của workspace, dù skill hay prompt có dùng tới hay không. Bạn không thể giới hạn một credential cho riêng một skill hay agent. Chỉ lưu những key mà skill cần và ưu tiên key chỉ đọc của nhà cung cấp. Xem cách agent dùng credential.
Giới hạn
Kiểm tra trước khi tải lên
SKILL.mdđược viết hoa và nằm ở thư mục gốc của zip hoặc sâu một thư mục.- File bắt đầu bằng
---ở dòng đầu tiên, và frontmatter đóng lại bằng---. namebắt đầu bằng chữ cái hoặc chữ số và chỉ dùng chữ cái, chữ số,_và-.namekhông trùng tên skill tích hợp sẵn, nhưpdfhaydeep-research.descriptionđã được điền, và nằm trong ngoặc kép nếu có dấu hai chấm.- Tên file zip khớp chính xác với
name. - File hỗ trợ nằm trong
references/,scripts/hoặcschemas/.
Viết hướng dẫn mà agent làm theo
Chỉ viết những gì agent chưa biết. Agent đã hiểu SQL injection. Agent chưa biết quy tắc riêng của bạn về nó.
Cho thấy, đừng mô tả. Một cặp ví dụ hiệu quả hơn một đoạn văn:
references/ và trỏ tới đó. Đây là lời khuyên để agent đi đúng hướng, thấp hơn nhiều so với giới hạn cứng 50.000 ký tự.
Ví dụ đầy đủ
Một skill về tiêu chuẩn pull request mà bạn có thể điều chỉnh:argument-hint; trường này chỉ giúp người chạy skill từ menu / trong chat. Xem custom skill.
Khắc phục sự cố
Failed to upload skill to executor
Failed to upload skill to executor
- Frontmatter. Frontmatter bị thiếu, có lỗi YAML, hoặc
namehaydescriptionđể trống. Kiểm traSKILL.mdbắt đầu bằng---, header đóng bằng---, và cả hai trường đều có giá trị. Đặt mô tả có dấu hai chấm trong ngoặc kép. Đồng thời kiểm tranametuân theo quy tắc đặt tên ở trên. - Không có
SKILL.mdở nơi CloudThinker tìm. File phải nằm ở thư mục gốc của zip hoặc sâu một thư mục, và tên file phân biệt chữ hoa chữ thường. Đổi tênskill.mdthànhSKILL.mdrồi nén lại.
SKILL.md name must match the selected skill
SKILL.md name must match the selected skill
Khi bạn sửa tay một skill có sẵn,
name trong frontmatter phải giữ nguyên chính xác. Để đổi tên skill, hãy tải skill xuống, đổi tên, rồi tải lên như một skill mới. Sau đó xóa skill cũ, và tick lại Available in trên skill mới, vì skill mới chỉ bắt đầu với Chat.Script hoặc tài liệu bị mất sau khi tải lên
Script hoặc tài liệu bị mất sau khi tải lên
Chỉ các file trong
scripts/, schemas/ và references/ nằm cạnh SKILL.md được giữ lại. Hãy chuyển các file khác vào một trong các thư mục đó.Skill tải được nhưng agent hiếm khi dùng
Skill tải được nhưng agent hiếm khi dùng
Viết lại
description để nói khi nào dùng skill, bằng đúng những từ người dùng thường gõ (“Use when reviewing a pull request”). Sau đó làm các quy tắc cụ thể hơn và thêm ví dụ.Liên quan
Custom skill
Tạo, tải lên và chọn nơi skill được áp dụng.
Tổng quan skill
Cách agent chọn và áp dụng skill.