1. Vai trò của phần Instructions

Phần thân SKILL.md (viết bằng Markdown, ngay sau khối YAML) là "Lớp 2" trong cơ chế progressive disclosure: chỉ được nạp khi Claude xác định Skill liên quan đến tác vụ. Đây là nơi mô tả chi tiết các bước, ví dụ và cách xử lý lỗi.

2. Cấu trúc tham khảo

Một bố cục phổ biến cho phần thân:

 
markdown
---
name: ten-skill
description: [...]
---

# Tên Skill

## Hướng dẫn

### Bước 1: [Bước lớn đầu tiên]
Giải thích rõ điều gì xảy ra.

Ví dụ lệnh:
```bash
python scripts/fetch_data.py --input {filename}
```
Kết quả mong đợi: [mô tả thế nào là thành công]

(Thêm các bước khác nếu cần)

## Ví dụ

### Ví dụ 1: [tình huống thường gặp]
Người dùng nói: "..."
Hành động:
1. ...
2. ...
Kết quả: ...

## Xử lý lỗi

### Lỗi: [thông báo lỗi thường gặp]
Nguyên nhân: [vì sao xảy ra]
Cách xử lý: [cách khắc phục]

Cấu trúc gồm ba khối chính: hướng dẫn theo bước, ví dụ minh họa, và phần xử lý lỗi.

3. Nguyên tắc viết hướng dẫn hiệu quả

3a. Cụ thể và có thể hành động

Hướng dẫn cần đủ rõ để thực thi, không chung chung.

Nên:

 
markdown
Chạy `python scripts/validate.py --input {filename}` để kiểm tra định dạng dữ liệu.
Nếu kiểm tra thất bại, các lỗi thường gặp gồm:
- Thiếu trường bắt buộc (bổ sung vào file CSV)
- Sai định dạng ngày (dùng YYYY-MM-DD)

Không nên:

 
markdown
Hãy kiểm tra dữ liệu trước khi tiếp tục.

3b. Có phần xử lý lỗi

Liệt kê các lỗi thường gặp kèm nguyên nhân và cách khắc phục, thay vì để Claude tự đoán. Ví dụ: lỗi kết nối, thiếu trường dữ liệu, sai định dạng.

3c. Tham chiếu tài nguyên rõ ràng

Khi Skill có thư mục references/, hãy chỉ rõ khi nào cần đọc file nào:

 
markdown
Trước khi viết test case, tham khảo `references/test-case-template.md` để biết:
- Cấu trúc các trường bắt buộc
- Quy ước đặt tiêu đề test case
- Mức độ ưu tiên (priority) áp dụng cho team

3d. Dùng progressive disclosure

Giữ SKILL.md tập trung vào hướng dẫn cốt lõi. Đẩy tài liệu chi tiết sang references/ và liên kết tới, thay vì nhồi hết vào file chính. Khuyến nghị giữ SKILL.md dưới khoảng 5.000 từ.

4. Các lỗi khiến Claude không tuân thủ hướng dẫn

Khi Skill được nạp nhưng Claude không làm đúng, nguyên nhân thường thuộc các nhóm sau:

Nguyên nhân Biểu hiện Cách khắc phục
Hướng dẫn quá dài dòng Claude bỏ sót bước Viết gọn, dùng gạch đầu dòng và danh sách đánh số; đẩy chi tiết sang file riêng
Hướng dẫn bị "chôn" Bỏ qua điểm quan trọng Đặt hướng dẫn then chốt lên đầu, dùng tiêu đề "Quan trọng" / "Critical"
Ngôn ngữ mơ hồ Làm sai ý Diễn đạt cụ thể, nêu rõ điều kiện cần kiểm tra

Ví dụ về diễn đạt mơ hồ và cách sửa:

 
markdown
# Mơ hồ
Hãy đảm bảo kiểm tra mọi thứ cho đúng.

# Cụ thể
QUAN TRỌNG: Trước khi sinh test case, xác minh:
- User story có mô tả rõ điều kiện đầu vào
- Có ít nhất một tiêu chí chấp nhận (acceptance criteria)
- Đã xác định loại kiểm thử cần áp dụng

5. Khi nào nên dùng script thay vì hướng dẫn bằng lời

Với các kiểm tra mang tính then chốt (validation), nên đóng gói một script thực hiện kiểm tra bằng mã thay vì chỉ dựa vào hướng dẫn ngôn ngữ. Lý do: mã chạy có tính xác định, còn diễn giải ngôn ngữ thì không. Cách này áp dụng tốt cho các bước như kiểm tra định dạng file đầu vào trước khi xử lý.

6. Tổng kết bài 5

  • Phần thân SKILL.md là Lớp 2, chứa hướng dẫn theo bước, ví dụ và xử lý lỗi.
  • Hướng dẫn cần cụ thể, có thể hành động; tránh diễn đạt chung chung.
  • Đặt hướng dẫn quan trọng lên đầu; giữ file gọn và đẩy chi tiết sang references/.
  • Với kiểm tra then chốt, ưu tiên dùng script thay vì hướng dẫn bằng lời.

Bài tiếp theo (Bài 6): Bắt tay xây Skill đầu tiên cho tester — "Sinh test case từ user story", đi từ ý tưởng đến cấu trúc và nội dung hoàn chỉnh.