Chuyển đến nội dung chính
Mỗi skill là một file 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ừ name trong frontmatter, nên tên thư mục không cần khớp.
  • Đặt tên file zip đúng bằng name trong 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ó name trong 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.md bằ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.sh with the account ID.” Script có thể là Bash hoặc TypeScript (chạy bằng bun). 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_KEY sẽ là $DATADOG_API_KEY trong 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 ---.
  • name bắt đầu bằng chữ cái hoặc chữ số và chỉ dùng chữ cái, chữ số, _ và -.
  • name không trùng tên skill tích hợp sẵn, như pdf hay deep-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ặc schemas/.

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ó.
Chọn kiểu quy tắc theo mức tự do bạn muốn cho agent: Cho thấy, đừng mô tả. Một cặp ví dụ hiệu quả hơn một đoạn văn:
Mỗi skill một chủ đề. Tách quy tắc bảo mật khỏi quy tắc hiệu năng để bạn có thể bật từng skill ở những nơi khác nhau. Nếu skill dài quá khoảng 300 dòng, hãy tách ra, hoặc chuyển các bảng tham chiếu dài vào 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:
Sau khi lưu, hãy tick Review trong Available in để skill áp dụng cho review pull request. Review không bao giờ dùng 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ố

  • Frontmatter. Frontmatter bị thiếu, có lỗi YAML, hoặc name hay description để trống. Kiểm tra SKILL.md bắ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 tra name tuâ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ên skill.md thành SKILL.md rồi nén lại.
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.
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 đó.
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.