Instruction Design
Instruction Design
Viết phần instructions của SKILL.md: nguyên tắc 'súc tích' (concise), chọn đúng mức độ tự do (degrees of freedom) theo độ dễ vỡ của tác vụ, viết description đúng chuẩn ngôi thứ 3.
Nắm vững nguyên lý và khái niệm nền tảng trước khi đi vào công cụ thực tế.
Áp dụng quy trình từng bước, case study thực chiến và template mẫu có sẵn.
Kiểm tra checklist hoàn thành, né tránh các sai lầm kinh điển để vận hành bền vững.
Nắm vững các khái niệm nền tảng, cơ chế hoạt động và mô hình tư duy cốt lõi.
1. Mục tiêu học tập
Sau bài này, bạn có thể:
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.description hiệu quả — đúng ngôi kể, đủ cụ thể để Claude chọn đúng Skill.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.”
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.
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).
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’.”
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.” Ví dụ tệ (quá mơ hồ): “Helps with documents”, “Processes data”.
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 — đâ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.
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 — 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.
Quy trình thực thi từng bước, case study cụ thể và bộ prompt/template áp dụng ngay.
6. Hướng dẫn từng bước
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ể.7. Ví dụ thực tế
Đối chiếu tip tham khảo với 1 Skill thật đang chạy — “negative trigger”:
tài liệu tham khảo 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 tài liệu chính thức 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 chính thức 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
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
descriptionhoà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?
Checklist kiểm tra mức độ sẵn sàng, nhận diện các bẫy sai lầm và nguyên tắc vàng vận hành.
11. Checklist
12. Lỗi thường gặp
15. Best practices
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”. Đâ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.
⚠️ 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 chính thức.
🔐 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”.
📚 17. Nguồn tham khảo
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 · Tạo Claude Skill Đầu Tiên Của Bạn, Phan Đông Giang — 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.