Instruction Design

Level: L4 — AI Skills (Bài 3/12)

1. Mục tiêu học tập

Sau bài này, bạn có thể:

Viết phần instructions của SKILL.md theo nguyên tắc “súc tích” (concise) chính thức của Anthropic — không giải thích những gì Claude đã biết sẵn.
Chọn đúng “mức độ tự do” (degrees of freedom) cho từng loại tác vụ trong Skill.
Viết description hiệu quả — đúng ngôi kể, đủ cụ thể để Claude chọn đúng Skill.
Áp dụng nguyên tắc “negative trigger” (khi nào KHÔNG nên dùng Skill này).

2. Khái niệm cốt lõi

Nguyên tắc số 1, quan trọng nhất: “Concise is key”.

“The context window is a public good… Not every token in your Skill has an immediate cost… However, being concise in SKILL.md still matters: once Claude loads it, every token competes with conversation history and other context.” [S77]

Giả định mặc định: Claude đã rất thông minh — chỉ thêm những gì Claude thực sự chưa biết. Ví dụ chính thức đối chiếu 2 cách viết cùng 1 nội dung (trích PDF text bằng pdfplumber): súc tích (~50 token, TỐT) — đưa thẳng đoạn code, không giải thích PDF là gì. Dài dòng (~150 token, KHÔNG TỐT) — giải thích lại “PDF là gì”, “vì sao cần thư viện”… toàn thông tin Claude đã biết sẵn [S77].

Nguyên tắc số 2: chọn đúng “mức độ tự do” (degrees of freedom) theo độ dễ vỡ của tác vụ:

Mức tự do	Khi dùng	Ví dụ
Cao	Nhiều cách đều đúng, cần bối cảnh để quyết định	Quy trình code review (liệt kê các bước kiểm tra, để Claude tự vận dụng)
Trung bình	Có khuôn mẫu ưu tiên, cho phép biến đổi	Pseudocode/script có tham số
Thấp	Thao tác dễ vỡ, cần nhất quán tuyệt đối, đúng thứ tự	Script migration database — “chạy đúng script này, không thêm cờ”

Ẩn dụ chính thức: hình dung Claude như “1 robot đi trên đường” — cầu hẹp có vực 2 bên (chỉ có 1 đường an toàn duy nhất → chỉ dẫn thấp-tự-do, chính xác tuyệt đối) vs cánh đồng trống không chướng ngại (nhiều đường đều tới đích → chỉ dẫn cao-tự-do, tin tưởng Claude tự tìm đường) [S77].

Nguyên tắc số 3: viết description đúng chuẩn.

“Always write in third person… Good: ‘Processes Excel files and generates reports’. Avoid: ‘I can help you process Excel files’.” [S77]

description phải nêu cả 2 vế: Skill làm gì + khi nào nên dùng. Ví dụ tốt: “Extract text and tables from PDF files… Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.” [S77] Ví dụ tệ (quá mơ hồ): “Helps with documents”, “Processes data” [S77].

3. Tại sao nội dung này quan trọng

description là thứ duy nhất luôn có mặt trong ngữ cảnh trước khi Skill được kích hoạt (Tầng 1, bài 31) — nếu viết mơ hồ, Skill sẽ không bao giờ được gọi đúng lúc, dù nội dung bên trong có tốt tới đâu. Còn phần instructions dài dòng không chỉ tốn ngữ cảnh mỗi lần kích hoạt mà còn làm loãng phần quan trọng — nguyên tắc “súc tích” không phải sở thích cá nhân, mà là khuyến nghị chính thức có lý do kỹ thuật rõ ràng (token cạnh tranh với lịch sử hội thoại).

4. Cơ chế hoạt động

Description được chèn thẳng vào system prompt ngay từ đầu phiên [S77] — đây là lý do quy tắc “luôn viết ngôi thứ 3” không phải tùy chọn phong cách: nếu 1 description viết “I can help you…” trong khi các description khác viết ở ngôi thứ 3, sự thiếu nhất quán này gây rối cho việc Claude tự đối chiếu nhiều Skill cùng lúc để chọn đúng cái cần dùng [S77].

Khi Skill được kích hoạt, phần instructions markdown mới được đọc vào ngữ cảnh — và theo đúng nguyên tắc “1 tầng sâu” (bài 31/33): nếu instructions dẫn tới quá nhiều lớp file lồng nhau, Claude có xu hướng chỉ đọc lướt (như head -100) thay vì đọc trọn vẹn, dẫn tới bỏ sót thông tin [S77] — 1 lý do kỹ thuật cụ thể vì sao cấu trúc phẳng lại quan trọng, không chỉ là “gọn gàng cho đẹp”.

5. Mental model

Tiếp nối ẩn dụ “hồ sơ đào tạo”: nếu description là tựa đề + tóm tắt 1 dòng trên bìa hồ sơ (thứ người quản lý liếc qua để biết có nên mở hồ sơ này ra không), thì phần instructions là nội dung bên trong — nguyên tắc viết instructions tốt giống hệt nguyên tắc viết 1 tài liệu đào tạo tốt cho 1 nhân viên đã có kinh nghiệm: không giảng lại kiến thức nền, đi thẳng vào quy trình cụ thể, và ghi rõ mức độ được phép “tùy biến” ở từng bước.

6. Hướng dẫn từng bước

Viết description trước — 1 câu nêu Skill làm gì, 1 câu (hoặc vế thứ 2 cùng câu) nêu khi nào nên dùng, ngôi thứ 3, có từ khóa cụ thể.
Với mỗi bước trong quy trình, tự hỏi: “đây là tác vụ dễ vỡ (cần đúng thứ tự tuyệt đối) hay linh hoạt (nhiều cách đều ổn)?” — chọn mức tự do tương ứng.
Viết phần chính bằng giọng ra lệnh trực tiếp (“Chạy X”, “Kiểm tra Y”), không giải thích lý do/nền tảng trừ khi thực sự cần cho quyết định.
Rà lại: mỗi đoạn có “đáng giá token” nó chiếm không? Xóa mọi câu Claude vốn đã biết.
Thêm “negative trigger” nếu Skill dễ bị kích hoạt nhầm — nêu rõ khi nào KHÔNG nên dùng Skill này.
Nếu quy trình có bước xác thực/kiểm tra chất lượng, cân nhắc thêm 1 vòng lặp “validator → sửa → lặp lại” thay vì chỉ liệt kê bước xong-là-xong [S77] — quay lại ở bài 38/39 khi thực hành.

7. Ví dụ thực tế

Đối chiếu tip Tier 3 với 1 Skill thật đang chạy — “negative trigger”:

Nguồn Tier 3 (S09) từng đưa ra 1 tip kinh nghiệm: “Negative triggers (‘Do NOT use for…’) quan trọng hơn positive trigger để tránh kích hoạt nhầm.” Đây là quan điểm thực hành (chưa được nguồn Tier 1 xác nhận trực tiếp bằng đúng cụm từ này), nhưng đối chiếu với 1 ví dụ thật: description của chính Skill vận hành dự án này (ai-mastery-bible) có cả positive trigger LẪN negative trigger tường minh:

“…Also trigger on phrases like ‘thêm nguồn mới’, ‘cập nhật research matrix’… Do NOT trigger for generic AI/Claude questions unrelated to this project’s curriculum pipeline.”

Đây là bằng chứng thực hành thực tế cho thấy tip của S09 phản ánh đúng 1 thực hành phổ biến, dù bản thân tài liệu Tier 1 (S77) không dùng đúng thuật ngữ “negative trigger” — S77 tập trung nhiều hơn vào việc mô tả rõ “khi nào dùng” trong chính description, đạt hiệu quả tương tự theo cách khác.

8. Prompt/template/workflow

description: [Skill làm gì — động từ + đối tượng cụ thể]. Use when
  [tình huống/từ khóa cụ thể kích hoạt việc dùng Skill này]. Do NOT use
  for [trường hợp dễ nhầm lẫn cần loại trừ tường minh, nếu có].

Bước: [mô tả bước]
- Có nhiều cách làm đều chấp nhận được? → mức Cao (mô tả bằng văn bản)
- Có 1 khuôn mẫu ưu tiên, cho phép biến đổi nhẹ? → mức Trung bình (pseudocode)
- Sai 1 chi tiết là hỏng cả kết quả? → mức Thấp (script cụ thể, không tham số)

9. Visual hoặc diagram cần thiết

Hình 4.3 — 3 mức độ tự do khi viết instructions: Thấp (cầu hẹp vực sâu) → Trung bình (đường mòn có biển chỉ dẫn) → Cao (cánh đồng trống).

10. Bài tập thực hành

Viết lại 1 đoạn hướng dẫn dài dòng bất kỳ theo nguyên tắc “concise” — so sánh số từ trước/sau.
Với 1 quy trình bạn từng làm với AI (bài 29 mục 10), xác định từng bước thuộc mức tự do nào (Cao/Trung bình/Thấp).
Viết 1 description hoàn chỉnh cho Skill giả định của bạn (bài 29), gồm đủ 2 vế bắt buộc + (nếu cần) 1 negative trigger.
So sánh description bạn viết với 2 ví dụ chính thức ở mục 2 — có đủ cụ thể để phân biệt với 1 Skill gần giống không?

11. Checklist

Viết được 1 description đủ 2 vế (làm gì + khi nào dùng), đúng ngôi thứ 3.
Phân loại đúng mức độ tự do cho 1 bước quy trình bất kỳ.
Biết cách rút gọn 1 đoạn hướng dẫn dài dòng theo nguyên tắc 'Claude đã biết sẵn'.
Biết khi nào nên thêm negative trigger.

12. Lỗi thường gặp

Viết description ở ngôi thứ nhất/thứ hai (“I can help…”, “You can use…”) — gây lỗi discovery do không nhất quán với description khác [S77].
Giải thích lại kiến thức nền Claude đã biết — lãng phí token, làm loãng phần hướng dẫn thật sự cần thiết.
Cho mức tự do cao ở tác vụ dễ vỡ — dẫn tới kết quả không nhất quán.
Đưa quá nhiều lựa chọn cùng lúc (“dùng thư viện A, hoặc B, hoặc C…”) thay vì 1 lựa chọn mặc định + phương án dự phòng rõ ràng [S77].

13. Giới hạn & khi nào KHÔNG nên áp dụng

Bài này không thay thế Level 2 (nguyên tắc prompt cơ bản) — giả định bạn đã biết cách viết rõ ràng, cụ thể, có ví dụ.
Không áp dụng cho tài nguyên/script đính kèm (bài 33) hay ràng buộc input/output hình thức (bài 34) — đây là 2 phần khác của Skill.
Nguyên tắc “negative trigger” (mục 7) là thực hành hợp lý, không phải yêu cầu bắt buộc trong tài liệu Tier 1.

14. An toàn & quản trị (Safety/Governance)

Description viết mơ hồ hoặc quá rộng làm tăng rủi ro Skill bị kích hoạt nhầm trên tác vụ không liên quan — không chỉ là vấn đề hiệu quả mà còn là vấn đề an toàn nếu Skill đó có quyền chạy script/thao tác file (bài 31 mục 14). Viết negative trigger rõ ràng là 1 biện pháp giảm rủi ro kích hoạt ngoài ý muốn, không chỉ là “thực hành hay”.

15. Best practices

Luôn viết evaluation/tình huống thử nghiệm TRƯỚC khi viết instructions chi tiết — theo đúng “evaluation-driven development” [S77] (chi tiết đầy đủ ở bài 34).
Dùng giọng ra lệnh trực tiếp, tránh giọng narrator giải thích “vì sao” trừ khi lý do ảnh hưởng tới quyết định thực tế.
Test description với câu hỏi thực tế người dùng có thể gõ, không chỉ test với câu diễn đạt “sạch” giống hệt trong description.

16. Nội dung nâng cao (không bắt buộc)

Tài liệu chính thức khuyến nghị không viết thông tin gắn mốc thời gian cụ thể trong instructions (kiểu “trước tháng 8/2025 dùng API cũ”) — thay vào đó tách riêng 1 phần “Old patterns” [S77]. Đây là nguyên tắc gần như trùng khớp với chính kỷ luật “Content requiring updates” mà dự án AI Mastery Bible đang áp dụng xuyên suốt Research Matrix.

17. Nguồn tham khảo

[S77] Skill authoring best practices, Anthropic (platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — nguồn chính cho toàn bộ nguyên tắc concise/degrees of freedom/description · [S09] Tạo Claude Skill Đầu Tiên Của Bạn, Phan Đông Giang (Tier 3) — tip “negative trigger”, đối chiếu với ví dụ thật ở mục 7 · Ví dụ thực tế: .claude/skills/ai-mastery-bible/SKILL.md.

18. Ngày kiểm chứng

Claim kỹ thuật kiểm chứng qua nguồn Tier 1 (S77) ngày 2026-07-12. Ví dụ đối chiếu (mục 7) xác nhận trực tiếp từ file thật cùng ngày.