Xây Skill Đầu Tiên Cho Claude Code: 5 Bước Từ Số 0

Lần đầu nghe "viết Skill cho Claude Code", mình tưởng phải biết lập trình mới làm được. Hoá ra không. Một Skill về bản chất chỉ là một file văn bản mô tả rõ ràng: khi nào Claude nên dùng, và làm theo quy trình nào. Không cần biên dịch, không cần deploy.

Skill là gì và khi nào cần

Skill là một gói hướng dẫn có cấu trúc, gồm ít nhất một file SKILL.md, đặt trong thư mục riêng để Claude Code tự nạp khi phát hiện yêu cầu khớp với mô tả trong file đó. Khác với việc gõ lại quy trình vào mỗi lần chat, Skill lưu quy trình một lần và Claude tự gọi lại đúng lúc.

📌 Chưa chắc nên chọn gì? Đọc trước Học AI: Dùng Claude, ChatGPT, Gemini Đúng Việc — hướng dẫn tổng hợp của Kudomax về học ai.

Nên viết Skill khi bạn thấy mình lặp lại cùng một hướng dẫn dài từ 3 lần trở lên: quy trình review code theo chuẩn riêng của team, cách viết báo cáo theo mẫu công ty, hay quy trình deploy có nhiều bước cố định.

5 bước dựng một Skill

• 1. Tạo thư mục riêng trong .claude/skills/ten-skill/, đặt tên bằng chữ thường và dấu gạch ngang, không dấu tiếng Việt.
• 2. Viết phần frontmatter ở đầu SKILL.md: name (trùng tên thư mục) và description mô tả rõ skill làm gì và khi nào nên dùng, đây là phần Claude đọc để quyết định có gọi skill hay không, viết mơ hồ là skill sẽ không bao giờ được gọi tới.
• 3. Viết quy trình bên dưới frontmatter bằng Markdown thường, giống hướng dẫn viết cho một người mới vào việc: mục tiêu, các bước theo thứ tự, ví dụ đầu ra mong muốn.
• 4. Test bằng chính câu hỏi thật mà bạn nghĩ sẽ trigger skill, xem Claude có tự gọi đúng skill không.
• 5. Sửa lại description nếu skill không được gọi hoặc bị gọi nhầm lúc không cần. 90% lỗi Skill không chạy nằm ở bước này, chứ không phải ở nội dung quy trình.

Lỗi hay gặp nhất: description quá chung chung

Viết "Giúp viết code tốt hơn" thì gần như không bao giờ được gọi, vì quá rộng để Claude quyết định đây có phải đúng lúc không. Viết cụ thể: "Dùng khi user yêu cầu review pull request theo chuẩn TypeScript strict mode của team, kiểm tra type an toàn và test coverage". Càng cụ thể, tỷ lệ gọi đúng lúc càng cao.

Cấu trúc thư mục của một Skill

Một Skill tối thiểu chỉ cần một thư mục chứa file SKILL.md. Nếu quy trình cần thêm script hỗ trợ, ví dụ một file kiểm tra tự động, có thể đặt thêm file đó cùng thư mục và gọi tới trong phần hướng dẫn. Không cần build hay cài đặt gì thêm, Claude Code đọc trực tiếp nội dung Markdown khi quyết định gọi Skill.

Ví dụ một SKILL.md thật

Một Skill review pull request theo chuẩn TypeScript strict mode có thể bắt đầu đơn giản như sau, đặt trong .claude/skills/review-pr-typescript/SKILL.md:

---
name: review-pr-typescript
description: Dùng khi user yêu cầu review pull request theo chuẩn TypeScript strict mode của team, kiểm tra type an toàn và test coverage trước khi merge.
---

# Quy trình review PR TypeScript

1. Đọc diff, liệt kê các file .ts/.tsx thay đổi.
2. Kiểm tra strict mode: không dùng "any" trần trụi, không tắt strict check bằng comment.
3. Kiểm tra test đi kèm: mỗi hàm logic mới phải có ít nhất 1 test case.
4. Báo cáo theo format: file, dòng, mức độ (critical/warning), đề xuất sửa.

Chỉ với phần frontmatter và 4 bước ngắn gọn này, Claude Code đã đủ thông tin để tự gọi Skill đúng lúc và làm theo đúng quy trình, không cần người dùng giải thích lại từ đầu mỗi lần review.

Nên test ngay sau khi viết xong bản nháp đầu tiên, thay vì viết một lèo nhiều Skill rồi mới quay lại kiểm tra hàng loạt — cách làm từng bước một giúp dễ xác định chính xác Skill nào đang gọi sai và sửa description ngay lúc còn nhớ rõ ý định ban đầu.

Cách test một Skill mới viết

• Gõ đúng câu hỏi thật mà bạn nghĩ người dùng sẽ hỏi, ví dụ "review giúp mình PR này theo chuẩn TypeScript của team" — xem Claude có tự gọi đúng Skill không.
• Thử thêm 2-3 cách diễn đạt khác cho cùng ý định, để chắc chắn Skill vẫn được gọi đúng dù không gõ chính xác một câu duy nhất.
• Thử một câu hỏi gần giống nhưng KHÔNG nên trigger Skill này, để kiểm tra description có đang quá rộng hay không.

Skill khác Subagent ở điểm nào?

Skill là một gói hướng dẫn được nạp vào ngay trong phiên làm việc hiện tại, còn Subagent là một tiến trình riêng chạy độc lập, có thể dùng bộ công cụ khác và trả kết quả về sau khi hoàn tất. Nên dùng Skill cho quy trình cần chạy ngay trong luồng chat đang có, và cân nhắc Subagent khi tác vụ đủ lớn để tách biệt, chạy song song hoặc cần một bộ quyền công cụ riêng.

Nếu bạn đang định viết Skill cho một quy trình nội dung, ví dụ kiểm tra bài viết trước khi AI trích dẫn, có thể tham khảo thêm góc nhìn ở bài GEO là gì và cách tối ưu cho AI search để biết nên đưa tiêu chí nào vào quy trình Skill của mình.

Xem thêm 60+ slash command hữu ích cho Claude Code nếu bạn muốn kết hợp Skill với lệnh tuỳ biến cho quy trình lặp lại thường xuyên hơn.