10 quy tắc viết Claude skill mới từ guide của Anthropic

1. Claude 5.5 ra mắt, và cách viết skill phải đổi theo

Jay mở đầu bằng một tin: các model Claude 5.5 đã ra mắt, và cách chúng ta build lẫn dùng skill có vẻ cũng phải đổi theo. Lý do là Anthropic vừa cập nhật bộ guide chính thức, đầy đủ, về cách viết skill. Theo Jay, có vẻ như nhiều thứ trước đây chạy tốt thì giờ hoặc đang làm bạn chậm lại, hoặc đang khiến bạn tốn tiền hơn.

Anh đưa ngay một ví dụ để gây chú ý: bạn có biết rằng nếu skill của bạn là một file dài, Claude có thể chỉ đọc 100 dòng đầu tiên của file đó, tuỳ vào cách bạn sắp xếp nó? Vậy nếu những guideline quan trọng nhất của bạn nằm sâu bên dưới trong skill, thì với Claude, chúng coi như không tồn tại.

Jay nói anh đã đọc trọn bộ skills guide mới của Anthropic, và trong video này anh sẽ đi qua từng rule mới cùng nhiều ví dụ. Anh cũng sẽ chia sẻ một prompt dùng để audit toàn bộ skill của bạn theo các rule này rồi cải thiện chúng trong một lượt.

Anh tự giới thiệu ngắn cho người mới: tên anh là Jay (trên màn hình ghi Jay Enriquez). Anh đã làm hơn mười năm với những thương hiệu mà có lẽ bạn đều biết (màn hình hiện logo Knorr, Hellmann's, HelloFresh và Microsoft), làm về AI từ hồi học thạc sĩ data science, và giờ đang dẫn mảng kinh doanh AI ở một trong những cộng đồng AI lớn nhất toàn cầu.

2. Rule 1: progressive disclosure, SKILL.md dưới 500 dòng

Rule đầu tiên là những quy tắc mới quanh progressive disclosure. Theo guide của Anthropic, best practice là giữ file chính SKILL.md dưới 500 dòng, còn mọi thứ khác thì tách ra thành file riêng, được link thẳng từ SKILL.md.

Anthropic gọi cách này là progressive disclosure, nghĩa là Claude chỉ load thứ nó cần, đúng lúc nó cần. File SKILL.md chính hoạt động như một trang mục lục, và Claude chỉ mở các file khác ở đúng bước thật sự cần đến chúng.

Jay lấy ví dụ một skill làm hoá đơn (invoice). File chính chứa các bước, bên cạnh nó là một file giá (pricing), một file khách hàng (clients) và một thư mục scripts. Khi Claude đang lập một hoá đơn, nó chỉ mở file pricing, còn các file trong scripts có khi không bao giờ được load, và như vậy bạn tiết kiệm được token.

---
name: invoicing
description: Raises invoices.
---
# Invoicing

## Steps
1. Find client: clients.md
2. Price it: pricing.md
3. Run scripts/invoice.py
4. Send for approval

3. Cái bẫy của reference lồng nhau: Claude chỉ xem 100 dòng đầu

Nhưng đây là chỗ cần để ý. Nếu file chính trỏ tới một file thứ hai, và file thứ hai lại trỏ tiếp tới file thứ ba, tức là có nhiều tầng reference lồng nhau, thì Claude có thể chỉ preview file thứ ba, cụ thể là chỉ đọc 100 dòng đầu. Chính Anthropic nhắc tới đây là một hành vi mà các model Claude mới có.

Vì thế best practice, theo Jay, là cố giữ skill của bạn chỉ sâu một tầng nếu có thể: mọi file reference đều được link thẳng từ SKILL.md. Còn nếu bạn thật sự cần nhiều tầng reference lồng nhau, thì cách xử lý nằm ở rule số hai, phần anh sẽ nói ngay sau.

4. Một prompt để audit mọi skill, và PDF guide

Nếu bạn muốn làm một đợt audit đơn giản cho những skill bạn dùng nhiều nhất theo rule này, Jay đưa một prompt để bắt đầu. Anh cũng gom mọi resource và prompt trong video vào một PDF guide miễn phí. Bạn có thể gửi thẳng PDF đó cho AI agent của mình, agent sẽ audit toàn bộ skill của bạn theo từng rule và nói cho bạn biết nó định đổi gì trước khi thật sự đổi. Jay để link lấy PDF ở phần mô tả video.

Video có một đoạn quảng cáo cho cộng đồng trả phí RoboNuggets của chính kênh (khoá Claude Living Masterclass và khoá Agents as a Service).

5. Rule 2: content list ở đầu mọi file dài hơn 100 dòng

Quay lại nội dung chính, rule số hai là content list. Bất kỳ file nào dài hơn 100 dòng đều nên có một danh sách nội dung ngắn ngay trên cùng, kiểu như một table of contents, cho agent biết bên trong có gì trước khi nó tiêu token để đọc cả file.

Rule này nối với điểm trước: với một số file, Claude chỉ đọc 100 dòng đầu. Trong những trường hợp đó, kể cả khi nó chỉ đang preview, nó vẫn có thể nhảy thẳng tới phần nó cần, miễn là table of contents nằm ở đầu file.

Jay quay lại file pricing đã xem lúc nãy: ở đầu file có liệt kê nội dung bên trong. Khi Claude thấy danh sách đó, nó biết rằng thông tin về discount, chẳng hạn, nằm ở tận cuối file, dù nó chỉ preview 100 dòng đầu tiên.

Trên docs của Anthropic, câu tương ứng là: với các file reference dài hơn 100 dòng, hãy thêm table of contents ở đầu file, để Claude thấy được toàn bộ phạm vi thông tin có sẵn kể cả khi chỉ preview.

6. Rule 3: degrees of freedom, ba mức tự do

Rule số ba xoay quanh degrees of freedom. Nguyên tắc rất gọn: ở bước hay việc nào rủi ro, bạn cần đưa nhiều chi tiết và guardrail hơn. Còn nếu việc đó không quá hệ trọng, bạn có thể bớt cứng nhắc và để model sáng tạo trong cách giải quyết. Anthropic gọi việc này là đặt degrees of freedom, và họ nêu ra ba mức.

• High freedom: chỉ là hướng dẫn bằng lời thường, bạn nói nó cần làm gì. Ví dụ khi bạn mới bắt đầu brainstorm các cách tự động hoá quy trình kinh doanh, vì có rất nhiều cách hay để làm việc đó.
• Medium freedom: một template với vài thiết lập. Ví dụ một weekly report, bạn muốn nó có một hình dạng nhất định nhưng xê dịch chút cũng được. Bạn vẫn muốn model bám template bạn đã đặt, nhưng không cứng tới mức bỏ lỡ một thông tin mới quan trọng mà lẽ ra nó đã đưa vào nếu được tự do hơn.
• Low freedom: một script chính xác. Ví dụ lập hoá đơn, hay soạn giấy tờ thuế, những việc đòi hỏi phải cứng, chặt và chi tiết tới từng li.

Chọn đúng mức tự do quan trọng vì các model Claude 5.5 giờ rất thông minh và thường khá sáng tạo so với các bản cũ. Nếu skill của bạn quá cứng, bạn có thể đang trói tay output của chúng.

Điểm đáng chú ý là một skill có thể trộn cả ba mức. Trong skill invoicing, phần viết email có thể để hoàn toàn mở, trong khi bước tạo hoá đơn là bước có mức tự do thấp, khoá chặt vào một script.

7. Rule 4: test skill trên đúng các model bạn dùng

Rule số bốn là test skill trên các model bạn thật sự dùng. Một skill thường chỉ tốt bằng model đang chạy nó. Theo Anthropic, bạn nên test skill trên mọi model mà bạn định dùng cùng nó, và họ đưa cho mỗi model một câu hỏi để kiểm:

• Haiku, rẻ hơn nhưng kém thông minh hơn: skill có đưa đủ hướng dẫn cho model không?
• Sonnet, tầng giữa khá tốt: skill có rõ ràng, có chút hướng dẫn và hiệu quả không?
• Opus và Fable, các model thông minh nhất: skill có tránh giải thích quá đà để model có thêm tự do sáng tạo không?

Chuyện này giờ càng quan trọng, vì Anthropic nói skill viết cho model cũ thường quá "prescriptive" (ra lệnh quá chi tiết) đối với các model mới nhất, và thật ra có thể làm output tệ đi. Nên nếu bạn có những skill build từ lâu, đáng để thử chạy chúng với ít guideline hơn.

Chiều ngược lại cũng đúng. Có thể bạn có những skill mà bạn vẫn cứ chạy trên model thông minh nhất, nhưng nếu chúng đã đủ chi tiết rồi, có khi một model Haiku là đủ.

Jay chỉ lưu ý một điều: test mọi skill trên mọi model có thể khá đắt. Hiển nhiên Anthropic sẽ khuyên bạn làm vậy, và họ sẽ rất vui nếu bạn làm, vì như thế bạn đốt hết token. Nên với rule này, anh khuyên bạn chỉ làm cho những skill bạn dựa vào nhiều nhất, và những skill mà một lỗi sẽ gây hậu quả.

8. Rule 5: viết gọn, và description ở ngôi thứ ba

Rule số năm là tối ưu cách viết skill. Đây là rule nhanh: nếu skill của bạn mở đầu bằng một đoạn giải thích cho model invoice là gì, thì đó về cơ bản là chỗ trống và token bị lãng phí, vì Claude đã biết invoice là gì rồi. Anthropic thậm chí gọi context window là một "public good", một tài sản chung mà mọi thứ phải chia nhau.

Cách tốt hơn là chỉ giữ những gì Claude không tự suy ra được, như những thứ riêng của công ty bạn: bảng giá, điều khoản, hay các quy định nội bộ.

Jay còn thấy một mẹo hay về phần description của skill: viết nó ở ngôi thứ ba. Ví dụ description nên ghi rằng skill này tạo hoá đơn cho khách và gửi nhắc thanh toán, chứ không phải "tôi có thể giúp bạn về hoá đơn và nhắc thanh toán". Lý do là description chính là thứ Claude đọc khi quyết định dùng skill nào, và viết ở ngôi thứ nhất có thể làm nó rối, nhất là với các model thấp hơn.

description: Creates client invoices and sends payment reminders

9. Rule 6: workflow và checklist, kèm dòng "go back"

Rule số sáu là workflow và checklist. Với những việc có nhiều bước, Anthropic khuyên trình bày các bước thật rõ, và đưa cho Claude một checklist thật sự mà nó copy vào câu trả lời của mình rồi đánh dấu dần khi làm xong từng bước. Theo Anthropic, các bước rõ ràng giúp Claude không bỏ sót việc gì quan trọng, điều mà đôi khi vẫn được ghi nhận, nhất là với các model 5.5.

Áp vào skill invoicing đang làm ví dụ, checklist có thể trông như sau:

## Monthly invoicing
Copy this checklist and track your progress:
- [ ] Step 1: Pull this month's completed jobs
- [ ] Step 2: Match each job to the client and the price
- [ ] Step 3: Create the invoices
- [ ] Step 4: Check every total against the job list
- [ ] Step 5: Send them out

Phần Jay muốn nhấn mạnh ở đây là cái anh gọi là dòng "go back". Ngay dưới bước kiểm, bạn có thể thêm một câu như: nếu có tổng tiền nào không khớp với danh sách job, thì quay lại bước hai. Đó là ví dụ khá đơn giản, nhưng Anthropic cũng dùng đúng ý tưởng này trong các ví dụ của chính họ. Trong trường hợp này, nó có thể chặn một hoá đơn sai bị gửi đi chỉ vì một ô đã được tick.

If any total doesn't match the job list, go back to Step 2.

10. Rule 7: feedback loop, skill tự kiểm bài của mình

Rule số bảy liên quan tới rule trước: feedback loop. Feedback loop là gì? Về cơ bản, đó là skill tự kiểm tra bài làm của chính nó. Theo Anthropic, pattern là: chạy skill, sửa bất cứ thứ gì không đạt, rồi lặp lại cho tới khi đạt. Họ nói cách này cải thiện chất lượng output rất nhiều.

Và ngày nay, vòng verify và feedback không nhất thiết phải liên quan tới code. Ví dụ đầu tiên của Anthropic thực ra là một style guide. Họ cho Claude soạn nội dung theo guide. Rồi, nếu việc theo đúng style guide là quan trọng, họ cho nó review bản nháp theo một checklist ngắn:

• Thuật ngữ có nhất quán không?
• Các ví dụ có theo đúng định dạng chuẩn mà ta đã đặt không?
• Có đủ mọi phần bắt buộc không?

Nếu có gì không đạt, Claude ghi lại từng lỗi cùng với phần nào của guide mà nó vi phạm, sửa bản nháp, rồi kiểm lại, và chỉ hoàn tất việc khi mọi thứ đã đạt.

11. Rule 8: ba common pattern cho output cần rõ khuôn

Rule số tám là các common pattern. Anthropic khuyên ba pattern hay dùng cho những skill mà bạn cần output có hình dạng rõ ràng hơn.

Thứ nhất là template. Ở đây bạn còn chọn được mức độ chặt mà model cần theo: hoặc luôn dùng đúng cấu trúc của template, hoặc đưa ra một mặc định hợp lý và để model tự phán đoán tốt nhất.

Thứ hai là examples, tức các cặp gồm một input và output bạn muốn. Bằng cách này bạn cho model thấy những prompt bạn sẽ gửi (input) và những kết quả bạn mong đợi (output). Ví dụ cho model thấy văn phong và mức chi tiết rõ hơn nhiều so với một đoạn mô tả.

Thứ ba là conditional workflow, về cơ bản là một ngã ba trên đường: Claude biết phải theo bộ bước nào tuỳ vào điều kiện của việc đang làm.

Vậy nếu bạn thấy output mà skill đang trả cho bạn lẽ ra phải rõ khuôn hơn, hãy nghĩ về ba pattern này và xem cái nào hợp với việc đang làm.

12. Rule 9: build để chia sẻ được

Rule số chín là build để chia sẻ được. Có thể ban đầu bạn tạo skill được tuỳ biến cho workspace của riêng mình. Nhưng tới một lúc nào đó, nhất là khi agentic AI ngày càng phổ biến, bạn nhiều khả năng sẽ cần chia sẻ một skill cho một đồng nghiệp hay cho cả team. Rule này là về việc build với tinh thần chia sẻ ngay từ đầu.

Nguyên tắc của nó là đừng mặc định rằng các tool và plugin skill của bạn cần đã được cài sẵn trên máy của người kia. Theo Anthropic, bạn đừng chỉ viết "dùng thư viện PDF", mà hãy đưa luôn hướng dẫn cài đặt vào trong chính skill, và liệt kê đúng các package bạn hay dùng trong skill. Sau đó bạn chỉ cần thêm một ghi chú: cài cái này nếu máy của người đó chưa được thiết lập.

**Bad example: Assumes installation**:
"Use the pdf library to process the file."

**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`

Then use it:

Nếu không làm vậy, skill invoicing của chúng ta, chẳng hạn, có thể chạy tốt trên máy bạn, nhưng lần đầu một đồng nghiệp chạy nó, họ sẽ không dùng được nó một cách hiệu quả.

13. Rule 10: luật không được phá thì chuyển thành hook

Rule số mười, theo Jay, khá ít được tận dụng, nhưng có lẽ là một trong những rule quan trọng nhất ở đây: hook. Giả sử có một luật trong skill invoicing mà không bao giờ được phá. Ví dụ: không bao giờ gửi một hoá đơn trên 10.000 đô la mà không có người duyệt ký.

Bạn có thể viết luật đó vào skill bằng chữ in hoa, và phần lớn thời gian Claude sẽ tuân theo. Nhưng với thứ quan trọng tới mức này, "phần lớn thời gian" có lẽ là không đủ.

Đó là lúc cần hook. Hook là một đoạn code mà Claude Code tự chạy vào một thời điểm định sẵn, ví dụ ngay trước khi Claude gửi một thứ gì đó hoặc chạy một lệnh. Và nó chạy bất kể Claude có đang tuân theo skill hay không.

Theo docs của Anthropic, nếu bạn thấy đôi khi Claude bỏ qua một luật mà lần nào cũng phải giữ, thì cách tốt hơn là chuyển luật đó từ skill sang một hook. Bạn thậm chí có thể đặt hook ngay bên trong skill. Ví dụ của họ là một skill tên secure-operations, với hook này trong phần thiết lập, chạy một bước kiểm bảo mật trước mỗi lệnh. Khi skill đó được dùng, Claude Code giữ hook chạy cho phần còn lại của session.

---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

Vậy hãy chọn ra vài luật mà chỉ một lần sai thôi cũng gây thiệt hại thật cho bạn hoặc doanh nghiệp của bạn, và kiểm xem chúng có chuyển được thành hook không.

14. Tổng kết và Skill Creator Plus

Vậy là đủ cả mười rule. Jay nhắc lại rằng các resource và prompt anh đã nhắc đều nằm trong PDF. Trong đó có cả một skill anh tự làm tên là Skill Creator Plus, thứ anh hiện dùng cá nhân để bảo đảm skill của mình bám đúng best practice mới nhất.

Lý do anh làm bản riêng: Anthropic có sẵn skill skill-creator đi kèm mặc định với Claude Code, nhưng khi anh kiểm thì thấy đường dẫn đó được cập nhật lần cuối vào tháng Ba năm nay, không rõ vì sao. Nên chẳng có lý do gì để không có bản của riêng mình, và anh chia sẻ bản của anh ở phần mô tả.

Như thường lệ, Jay cảm ơn người xem đã theo tới cuối, hy vọng video hữu ích, và mời bấm subscribe nếu thấy có ích để anh tiếp tục làm thêm nội dung giáo dục như thế này.