Cách viết một Claude Skill: cấu trúc SKILL.md

Một Claude Skill là một thư mục có tệp SKILL.md ở trong. Tệp này mở đầu bằng phần YAML gồm name và description, phía dưới là hướng dẫn cho Claude làm theo.

Claude Skill là gói hướng dẫn Claude chỉ đọc khi cần

Trang hướng dẫn tạo skill của Claude Help Center, cập nhật ngày 22/07/2026, cho biết skill có trên các gói Free, Pro, Max, Team và Enterprise. Tính năng này cần bật chạy code (code execution).

Skill có thể chỉ là vài dòng hướng dẫn, hoặc là cả gói nhiều tệp kèm code chạy được. Trang trợ giúp liệt kê đặc điểm của một skill tốt. Skill đó giải một việc cụ thể và lặp lại, có hướng dẫn rõ, có ví dụ khi cần, nói rõ lúc nào dùng và chỉ tập trung vào một quy trình.

Tài liệu Agent Skills cho lập trình viên so sánh skill với một bản hướng dẫn nhập môn cho nhân viên mới. Bạn viết cách làm một lần, Claude đọc lại mỗi khi gặp đúng việc đó.

Tệp SKILL.md có hai phần: YAML phía trên, hướng dẫn phía dưới

Mỗi skill bắt buộc có tệp SKILL.md với phần YAML frontmatter (khối thông tin đầu tệp, nằm giữa hai dòng ---). Hai trường bắt buộc là name và description. Phía dưới là phần thân viết bằng Markdown: các bước làm và ví dụ.

Tài liệu Agent Skills quy định trường name tối đa 64 ký tự, chỉ gồm chữ thường, số và dấu gạch nối. Tên không được chứa thẻ XML hay hai từ dành riêng "anthropic" và "claude". Vì vậy một tên như claude-helper sẽ không hợp lệ.

Trường description không được để trống và không chứa thẻ XML. Tài liệu cho lập trình viên ghi giới hạn 1.024 ký tự. Trang trợ giúp cho người dùng claude.ai lại ghi tối đa 200 ký tự. Để skill chạy được ở mọi nơi, bạn nên giữ mô tả dưới 200 ký tự.

Description quyết định Claude có gọi skill hay không

Tài liệu nói rõ: Claude so yêu cầu của bạn với description để quyết định có dùng skill hay không. Vì vậy mô tả phải nói được cả hai điều: skill làm gì, và dùng khi nào.

Trang Skill authoring best practices khuyên viết mô tả ở ngôi thứ ba, như "Processes Excel files and generates reports". Tránh kiểu "Tôi có thể giúp bạn..." vì mô tả được chèn vào lời nhắc hệ thống, đổi ngôi dễ làm Claude chọn sai skill.

Tài liệu cũng nêu ví dụ mô tả nên tránh: "Helps with documents" hay "Processes data". Mô tả mơ hồ thì Claude khó chọn đúng, trong khi số skill để chọn có thể hơn 100. Với tên, trang này gợi ý dạng động từ thêm -ing như processing-pdfs, và tránh tên chung chung như helper hay utils.

Một tệp SKILL.md mẫu bằng tiếng Việt

Dưới đây là một skill nhỏ viết chú thích sản phẩm. Mô tả dài 166 ký tự, nằm trong giới hạn 200 ký tự.

```

---

name: writing-product-captions description: Viết chú thích sản phẩm tiếng Việt cho bài đăng bán hàng theo giọng thương hiệu. Dùng khi người dùng nhờ viết caption, mô tả ngắn hoặc nội dung đăng kèm ảnh sản phẩm.

---

Viết chú thích sản phẩm

Quy trình

1. Nếu thiếu tên sản phẩm, giá hoặc ưu điểm chính, hỏi lại trước khi viết.
2. Viết 3 phương án, mỗi phương án dưới 60 chữ.
3. Kết bằng một lời mời mua ngắn.

Ví dụ

Xem examples.md để biết giọng văn mong muốn. ```

Phần thân nên ngắn. Best practices khuyên giữ phần thân SKILL.md dưới 500 dòng, và chỉ thêm thông tin Claude chưa biết. Nội dung dài hơn thì tách sang tệp riêng, như dòng "Xem examples.md" ở trên.

Vì sao skill không làm Claude chậm đi?

Câu trả lời nằm ở cơ chế progressive disclosure (nạp dần). Tài liệu Agent Skills chia nội dung skill thành ba cấp, mỗi cấp được nạp vào ngữ cảnh ở một thời điểm khác nhau.

Cấp 1 là name và description, luôn được nạp lúc khởi động, khoảng 100 token mỗi skill. Cấp 2 là phần thân SKILL.md, chỉ nạp khi skill được kích hoạt, dưới 5.000 token. Cấp 3 là tệp kèm và script, chỉ tốn token khi Claude đọc tới.

Với script, Claude chạy qua bash và chỉ nhận kết quả, code của script không vào ngữ cảnh. Nhờ vậy bạn cài nhiều skill mà không tốn ngữ cảnh, miễn mỗi skill có mô tả đúng.

Đóng gói và thử skill trước khi dùng thật

Muốn tải skill lên claude.ai, trang trợ giúp hướng dẫn: đặt tên thư mục trùng tên skill, nén thư mục thành tệp ZIP. Trong ZIP, thư mục skill phải nằm ở gốc, không để các tệp nằm trực tiếp ở gốc ZIP.

Sau khi tải lên, bật skill trong Customize > Skills, rồi thử vài câu lệnh khác nhau mà lẽ ra phải gọi skill. Nếu Claude không dùng skill khi bạn mong đợi, hãy sửa lại phần mô tả trước tiên.

Bốn lỗi hay gặp khi viết SKILL.md

Mô tả chỉ nói skill làm gì, quên nói khi nào dùng. Claude dựa vào mô tả để chọn skill. Thiếu phần "dùng khi" thì skill dễ bị bỏ qua.

Đặt tên có chữ "claude" hoặc chữ hoa. Tên chỉ nhận chữ thường, số, gạch nối và không chứa từ dành riêng.

Dồn mọi thứ vào một tệp. Phần thân quá dài làm tốn ngữ cảnh mỗi lần skill chạy. Tách tài liệu tham khảo ra tệp riêng và trỏ tới từ SKILL.md.

Dùng skill không rõ nguồn. Tài liệu Agent Skills cảnh báo skill độc hại có thể khiến Claude chạy công cụ hay code sai mục đích. Chỉ dùng skill bạn tự viết hoặc từ nguồn tin cậy, và đọc hết các tệp trước khi cài.

Không muốn tự viết từ đầu, bạn có thể chọn skill dựng sẵn trong kho skill của văn phòng: skill nhẹ 49.000đ, skill video 199.000đ, cài giúp tận máy 299.000đ. Xem trước skill chạy trên máy cần gì và cách cài skill vào Codex.

Nguồn tham khảo (4) · đọc ngày 09/10/2026

• Claude Help Center: How to create custom skills
• Claude Platform Docs: Agent Skills overview
• Claude Platform Docs: Skill authoring best practices
• Ảnh minh hoạ: Unsplash (Akinyemi Gbadamosi, Camille TINON, Vitaly Gariev), giấy phép Unsplash.

Linh SEO Agent