Agent Skill có xịn đến mấy mà thiếu phần này cũng như mở quán Bún Bò Huế chỉ treo biển "quán ăn sáng"

Năm ngoái mình bị “quê độ” trong lúc demo tạo skill bằng tay mà mãi SKILL không nhận, lý do đơn giản là mình đặt tên folder chứa skills bị sai (agent thay vì agent, claud thay vì claude).

Dù làm nghề giải pháp phần mềm hơn 16+ năm nhưng mình cũng mắc lỗi tương tự anh chị em mới khác, nên mọi người có bị thì cũng nên “quê độ” như mình nha (ủa) ^^

Sau đợt đó cũng “rảnh” nên ngồi tìm hiểu tài liệu từ Anthropic và đọc thêm blog của họ để đào sâu thêm cách viết skill sao cho hiệu quả, sẵn chia sẻ lại cho anh chị em trong cộng đồng luôn.

Agent Skill là gì? Tại sao nên dùng nó?

Hiểu đơn giản nó như là quy trình (SOP) và kỹ năng của nhân viên ảo, không khác gì quy trình với nhân viên thật.

Agent Skill cũng y chang vậy đó, mình đóng gói lại các bước và cách thức để AI Agent đọc và thực thi theo giống như mình đã mô tả.

Chỗ này nhiều người dễ nhầm, nghe skill là nghĩ ngay tới chuyện kỹ thuật của mấy ông developer, nhưng thật ra không cần biết code vẫn có thể làm được. Vì vốn dĩ nó là câu chuyện của quy trình và hướng dẫn cho AI làm thay mình.

Không có skill thì mỗi lần Claude/Antigravity mở lên là bắt đầu từ số 0, mình phải prompt lại từ đầu, giải thích lại từ đầu hoặc.. nó tự đoán rồi làm trúng hay không là hên xui.

Cấu trúc SKILL chuẩn

Mỗi skill là 1 folder, bên trong chứa:

• SKILL. md (bắt buộc): file chính, gồm YAML frontmatter + instructions

• references/: tài liệu chi tiết, Claude chỉ đọc khi cần

• scripts/: code chạy trực tiếp (Python stdlib only)

• assets/: templates, fonts, images

Folder name viết kiểu kebab-case, ví dụ: video-to-audio, sketch-note-graphic...

SKILL. md mô tả rằng phải viết đúng case, viết sai là Claude không nhận.

Cái này thì mình viết sai thành skill.md hoặc Skill.md thì upload lên Claude nó vẫn tự chuyển lại thành SKILL.md cho mình luôn, chắc tài liệu đã cũ.

Nhưng mà thật ra phần quyết định skill có hoạt động hoặc nhận diện được đúng không thì.. không phải đến từ chất lượng nội dung (instruction) bên trong.

Mà là DESCRIPTION.

Progressive disclosure 3 tầng để AI nhận diện chính xác và.. kích hoạt SKILL

Phần đầu file SKILL. md bắt buộc có 2 trường:

• name: tên skill, kebab-case

• description: mô tả dưới 1024 ký tự, viết cho Claude đọc (không phải cho người)

Chỗ này 90% anh em viết skill bỏ qua. Dành 3 tiếng viết instructions viết tới viết lui thật hay, còn description viết cho có.

Kết quả: Claude không bao giờ tự bật skill, phải gọi tay mỗi lần.

Cái này giống như mở quán ăn ồ ngon cỡ nào mà biển hiệu chỉ ghi “quán ăn sáng” --> không ai biết mình bán gì để mà ghé. Ghi đúng “bún bò Huế chính gốc, mở từ 6 sáng” --> khách đúng nhu cầu sẽ tự tìm tới.

Description cũng vậy. Nó là biển hiệu. Là điểm tiếp cận đầu tiên. AI chưa kịp đọc sâu bên trong thì đã phải quyết định: có nên gọi skill này ra hay không rồi.

Description không viết cho người đọc. Description viết cho AI đọc.. để nó quyết định CÓ BẬT SKILL HAY KHÔNG.

Mọi người có thể xem trong tài liệu của Anthropic có nhắc tới.

1. Tầng 1 (YAML frontmatter): khoảng 100 tokens/skill, luôn được load. Claude scan qua tất cả skill để quyết định cái nào liên quan đến yêu cầu hiện tại.

2. Tầng 2 (SKILL. md body): chỉ load khi Claude quyết định skill này cần được bật lên. Nên giữ dưới 500 dòng.

3. Tầng 3 (references/): zero tokens cho đến khi Claude tự quyết định cần đọc thêm chi tiết.

Có một số con số cụ thể:

• Description chung chung --> tỉ lệ được gọi ~20%.

• Có trigger phrases (câu user hay nói) --> ~50%.

• Có trigger phrases + ví dụ tình huống cụ thể --> 72-90%.

Khác biệt không nằm ở skill phức tạp hay đơn giản. Nằm ở cách mọi người mô tả nó để AI nhận ra đúng lúc.

Checklist để viết Description đúng

1. 5+ trigger phrases — cả tiếng Việt lẫn tiếng Anh.

Anh chị em hay nói gì khi cần việc đó? Ghi lại đúng câu đó.

Vì user đâu có nói theo kiểu chung chung. Họ nói “coi giúp em file này”, “review bài viết này đúng policy fb chưa”, “so lại doanh thu tháng này”.

2. Mô tả TÌNH HUỐNG.. “khi user muốn...”

Không ghi “dùng để phân tích.” Ghi “khi user muốn so sánh doanh thu tháng này với tháng trước và tìm nguyên nhân chênh lệch.”

Mô tả tác vụ thì còn mơ hồ. Mô tả tình huống thì AI mới hiểu lúc nào nên nhảy vào.

3. Bắt đầu bằng “BẤT CỨ KHI NÀO user...”

Cho Claude biết trigger condition.. giống như cài công tắc.

Nó nghe đơn giản thôi, nhưng đây là cách biến 1 đoạn mô tả thành điều kiện kích hoạt rõ ràng.

4. Thêm ví dụ câu user có thể nói thật.

Lấy từ chat history thật. Không bịa.

Ví dụ thật luôn ăn đứt ví dụ tự nghĩ ra, vì nó phản ánh đúng cách user gọi việc trong đời thực.

5. Dưới 1024 chars.. và KHÔNG dấu tiếng Việt.

Nghe kì cục nhưng description không dấu Claude xử lý mượt hơn. Mình cũng không hiểu tại sao nhưng.. số liệu nó vậy đó.

Đừng tham nhét quá nhiều. Description không phải chỗ để kể hết mọi thứ skill biết làm. Nó chỉ cần đủ rõ để được gọi đúng.

Nói vậy thôi.. instructions bên trong skill cũng quan trọng (không cãi được)

Nhưng instructions hay mà description dở --> không ai (và không AI nào) tìm ra skill đó để dùng. Giống như sách hay mà bìa ghi “sách đọc”.. không ai mở.

Mình làm cả trăm mô tả giải pháp tối ưu conversion cho khách hàng. Bài học xuyên suốt: điểm tiếp cận đầu tiên vẫn quyết định 80% thành bại.

Và Description chính là điểm tiếp cận của skill với AI.

Anh chị em nào đã thử viết Agent Skill rồi.. description của anh chị viết gì? Quăng mình xem thử. Nhìn description là mình đoán được skill đó có tự bật nổi hay không. ^^

#voquoccuong #EGANY

Nguồn:

• The Complete Guide to Building Skills for Claude (Anthropic, 2026)

• Anthropic Engineering Blog: Equipping Agents for the Real World

• Có lấy cảm hứng thêm từ bài của em nữa hehe..