1. Vai trò của YAML frontmatter

Phần khai báo YAML nằm ở đầu file SKILL.md, là "Lớp 1" trong cơ chế progressive disclosure đã trình bày ở Bài 1. Phần này luôn được nạp sẵn và cung cấp vừa đủ thông tin để Claude quyết định khi nào nên dùng Skill, mà không cần nạp toàn bộ nội dung.

Nói cách khác: phần thân SKILL.md có hay đến đâu cũng vô nghĩa nếu YAML không khiến Skill kích hoạt đúng lúc.

2. Cú pháp tối thiểu

Định dạng tối thiểu cần có:

 
 
yaml
---
name: ten-skill-cua-ban
description: Mô tả Skill làm gì. Dùng khi người dùng yêu cầu [các cụm cụ thể].
---

Hai dấu --- ở trên và dưới là bắt buộc để đánh dấu vùng YAML. Chỉ cần hai trường name và description là đã đủ để bắt đầu.

3. Các trường và yêu cầu

3a. name (bắt buộc)

  • Chỉ dùng kebab-case (chữ thường, nối bằng dấu gạch ngang).
  • Không dấu cách, không viết hoa.
  • Nên trùng với tên thư mục Skill.

3b. description (bắt buộc) — trường quan trọng nhất

Trường này phải chứa cả hai thông tin:

  • Skill làm gì (chức năng).
  • Khi nào dùng (điều kiện kích hoạt).

Yêu cầu kỹ thuật:

Quy tắc Chi tiết
Độ dài Dưới 1024 ký tự
Ký tự cấm Không dùng dấu ngoặc nhọn XML (< hoặc >)
Trigger phrases Nên liệt kê các cụm người dùng thực sự sẽ nói
Loại file Nêu định dạng file liên quan nếu có

3c. Các trường tùy chọn

  • license: dùng khi phát hành mã nguồn mở (ví dụ MIT, Apache-2.0).
  • compatibility: ghi yêu cầu môi trường (sản phẩm áp dụng, gói hệ thống cần, nhu cầu truy cập mạng...).
  • metadata: các cặp khóa-giá trị tùy ý, ví dụ author, version, mcp-server.

4. Cấu trúc một description tốt

Công thức tham khảo:

 
 
text
[Skill làm gì] + [Khi nào dùng] + [Năng lực chính]

Ví dụ tốt (cụ thể, có trigger phrases)

 
 
yaml
description: Sinh test case từ user story theo template chuẩn của team.
  Dùng khi người dùng nói "viết test case", "tạo test case từ user story",
  hoặc dán một user story và yêu cầu phân tích kịch bản kiểm thử.
 
 
yaml
description: Chuyển bộ test case sang định dạng import TestRail.
  Dùng khi người dùng nói "export sang TestRail", "tạo file import test case",
  hoặc cung cấp danh sách test case cần đưa vào TestRail.

Ví dụ chưa tốt

 
 
yaml
# Quá chung chung — không rõ khi nào dùng
description: Hỗ trợ công việc kiểm thử.

# Thiếu trigger — không có cụm người dùng sẽ nói
description: Tạo hệ thống tài liệu kiểm thử nhiều cấp.

# Quá kỹ thuật, không có trigger người dùng
description: Triển khai mô hình thực thể test case với quan hệ phân cấp.

Điểm khác biệt: ví dụ tốt nêu rõ làm gì và liệt kê cụm từ người dùng thực sự sẽ gõ; ví dụ chưa tốt thì mơ hồ hoặc thiếu điều kiện kích hoạt.

5. Quy tắc bảo mật trong frontmatter

Phần frontmatter xuất hiện trong system prompt của Claude, nên có một số ràng buộc bắt buộc:

  • Không dùng dấu ngoặc nhọn XML (< >) — đây là hạn chế bảo mật.
  • Không đặt tên Skill có tiền tố "claude" hoặc "anthropic" — các tên này được dành riêng.
  • Cho phép các kiểu YAML chuẩn (chuỗi, số, boolean, danh sách, đối tượng) và các trường metadata tùy chỉnh.

6. Mẹo kiểm tra nhanh description

Sau khi viết xong, có thể kiểm tra bằng cách hỏi trực tiếp Claude: "Khi nào bạn sẽ dùng Skill [tên skill]?" Claude sẽ trích lại nội dung description. Dựa vào câu trả lời, điều chỉnh phần còn thiếu.

  • Nếu Skill không kích hoạt khi đáng lẽ phải có: bổ sung chi tiết và từ khóa vào description, đặc biệt là các thuật ngữ kỹ thuật.
  • Nếu Skill kích hoạt nhầm cho truy vấn không liên quan: thêm điều kiện loại trừ (negative trigger) và viết cụ thể hơn.

7. Tổng kết bài 4

  • YAML frontmatter là Lớp 1 luôn được nạp, quyết định Skill có kích hoạt đúng lúc không.
  • Hai trường bắt buộc: name (kebab-case) và description.
  • description phải nêu cả làm gì và khi nào dùng, kèm trigger phrases cụ thể, dưới 1024 ký tự, không chứa < >.
  • Không đặt tên Skill chứa "claude" hoặc "anthropic".
  • Kiểm tra bằng cách hỏi Claude khi nào nó dùng Skill, rồi tinh chỉnh.

Bài tiếp theo (Bài 5): Viết phần Instructions — cấu trúc phần thân SKILL.md, cách trình bày các bước, ví dụ và xử lý lỗi sao cho Claude làm đúng việc.