Skills của Claude Code: cách hoạt động, SKILL.md và khi nào agent nạp chúng

Skills trong Claude Code là gì

Skill (kỹ năng) là một thư mục có file SKILL.md, trong đó ghi hướng dẫn cho một loại tác vụ cụ thể: cách deploy dự án, cách review, cách phát hành bản mới. Agent biết skill tồn tại ngay từ đầu phiên, nhưng chỉ đọc toàn bộ khi tác vụ thực sự cần.

Skills của Claude Code giải quyết một vấn đề quen thuộc với ai từng duy trì CLAUDE.md lâu: file hướng dẫn phình to. Quy trình deploy dài 80 dòng chỉ cần một lần mỗi tuần, nhưng nó vẫn chiếm chỗ trong ngữ cảnh của mọi phiên — kể cả khi bạn chỉ sửa một lỗi chính tả trong README. Skill đưa các quy trình như vậy ra khỏi ngữ cảnh thường trực và chỉ gắn vào khi cần.

Một skill gồm những gì

Skill tối thiểu là một thư mục và một file. Skill của dự án nằm trong repository, skill cá nhân nằm trong thư mục home của người dùng:

.claude/skills/deploy/SKILL.md      # skill của dự án, dùng chung cho nhóm qua git
~/.claude/skills/review/SKILL.md    # skill cá nhân, dùng được trong mọi dự án

Bên cạnh SKILL.md có thể đặt các file hỗ trợ: mẫu, script, tài liệu tham khảo. Agent sẽ mở chúng chỉ khi nội dung chính của skill có tham chiếu tới và chúng thực sự cần:

.claude/skills/deploy/
├── SKILL.md           # hướng dẫn chính
├── checklist.md       # checklist chi tiết, đọc theo tham chiếu
└── rollback.sh        # script hoàn tác

Frontmatter: name và description

File bắt đầu bằng khối YAML giữa hai dòng ---. Hai trường quan trọng nhất là name — tên ngắn của skill, và description — mô tả skill làm gì và khi nào nên dùng.

---
name: deploy
description: Deploy website lên hosting qua FTP. Dùng khi cần đẩy thay đổi lên máy chủ, kiểm tra chênh lệch với máy chủ hoặc hoàn tác deploy.
---

# Deploy

1. Trước tiên chạy thử: `./deploy.sh -n`.
2. Kiểm tra danh sách file: không được có bí mật và script thử nghiệm.
3. Đẩy lên: `./deploy.sh`.
4. Mở các trang đã thay đổi và xác nhận chúng trả về 200.

Hoàn tác — xem rollback.sh trong thư mục này.

Dưới phần frontmatter là Markdown thông thường: các bước, lệnh, ràng buộc, liên kết tới file lân cận. Hãy viết nó như cách bạn viết hướng dẫn cho một đồng nghiệp mới lần đầu làm việc này.

Khi nào agent nạp skill

Đầu phiên, ngữ cảnh chỉ nhận tên và mô tả của từng skill có sẵn. Đó chỉ vài dòng cho mỗi skill, nên có thể giữ hàng chục skill. Khi yêu cầu của người dùng hoặc bước hiện tại khớp với mô tả, agent gọi skill — và chỉ lúc đó nội dung đầy đủ của SKILL.md mới được nạp vào ngữ cảnh.

Từ đây suy ra quy tắc thực tế quan trọng nhất: skill được kích hoạt theo mô tả. Agent không thấy thân của skill cho đến khi quyết định mở nó. Nếu trong description chỉ viết «Skill phụ trợ», agent sẽ không biết khi nào cần đến. Nếu viết «Deploy lên hosting; dùng khi cần đẩy thay đổi lên máy chủ hoặc hoàn tác deploy» — agent sẽ biết.

Ngoài lựa chọn tự động, có thể gọi skill tường minh theo tên qua dấu gạch chéo, ví dụ /deploy. Cách này tiện khi bạn biết chắc cần quy trình nào và không muốn phụ thuộc vào việc agent tự khớp yêu cầu với mô tả.

Cách viết description để skill được kích hoạt

• Làm gì — một câu, bằng động từ: «Deploy website», «Review thay đổi trước khi commit».
• Khi nào dùng — liệt kê những cách diễn đạt mà người dùng thực sự yêu cầu tác vụ: «đẩy lên máy chủ», «đưa lên mạng», «hoàn tác».
• Khi nào không dùng, nếu skill dễ nhầm với skill bên cạnh: «không dùng để deploy bot, chỉ dùng cho website».
• Tránh các từ chung chung như «kỹ năng hữu ích» và «hỗ trợ công việc» — chúng không mang tín hiệu nào.

Progressive disclosure

Skills được xây dựng theo nguyên tắc progressive disclosure: thông tin được cung cấp theo từng lớp, và mỗi lớp tiếp theo chỉ được nạp khi cần.

Đây là cùng ý tưởng với việc dùng bảng định tuyến thay vì một đống văn bản trong file hướng dẫn: một bản đồ ngắn luôn sẵn sàng, chi tiết nằm sau liên kết. Khác biệt là skill biến việc nạp này thành cơ chế chuẩn, chứ không phải hy vọng agent tự mở đúng tài liệu. Thêm nữa, script ở lớp thứ ba agent có thể chạy trực tiếp mà không cần nạp toàn bộ mã vào ngữ cảnh.

Skills, CLAUDE.md và slash-command: khác nhau ở đâu

Cả ba cơ chế đều truyền hướng dẫn cho agent, nhưng vào những thời điểm khác nhau và với chi phí ngữ cảnh khác nhau.

Quy tắc chọn đơn giản: nếu hướng dẫn cần cho gần như mọi tác vụ, nó thuộc về CLAUDE.md. Nếu nó cần cho các tác vụ thuộc một loại nhất định, đó là skill. Nếu bạn tự gõ đi gõ lại cùng một yêu cầu dài, đó là ứng viên cho slash-command hoặc skill được gọi thủ công.

Đừng chuyển các cấm đoán cứng vào skill. Skill có thể không được nạp, còn quy tắc «không bao giờ commit bí mật» phải luôn có hiệu lực. Những bất biến như vậy nên ở lại CLAUDE.md và, nếu có thể, được đảm bảo bằng cơ chế: hook, quyền truy cập, kiểm tra trong CI.

Cách tạo skill cho Claude Code: từng bước

1. Tìm quy trình lặp lại. Dấu hiệu tốt: bạn đã giải thích cùng một việc cho agent ba lần, hoặc trong CLAUDE.md có một mục chỉ cần trong một tác vụ trên mười.
2. Tạo thư mục .claude/skills/<tên>/ và file SKILL.md bên trong.
3. Viết frontmatter với name và description, nói rõ khi nào áp dụng skill.
4. Mô tả các bước bằng lệnh cụ thể và tiêu chí hoàn thành: cần kiểm tra gì, kết quả nào được coi là thành công.
5. Chuyển phần dài sang file lân cận và tham chiếu tới chúng từ nội dung chính.
6. Xóa phần trùng trong CLAUDE.md, chỉ để lại một dòng trỏ tới: «Deploy — skill deploy».
7. Kiểm tra: trong phiên mới, hãy nêu tác vụ bằng lời của bạn, không nhắc tên skill, và xem agent có tự nhận ra không. Nếu không — viết lại mô tả.

Ví dụ về skill

Skill deploy

Ứng viên điển hình: quy trình hiếm dùng, dài và nguy hiểm, sai sót rất tốn kém. Trong skill cần cố định thứ tự các bước (chạy thử trước, rồi mới đẩy lên), những gì không được đưa lên, cách kiểm tra kết quả và cách hoàn tác. Agent không cần giữ tất cả trong đầu khi sửa code thông thường — chỉ khi công việc liên quan tới máy chủ.

Skill review

---
name: review
description: Review thay đổi hiện tại trước khi commit. Dùng khi được yêu cầu kiểm tra diff, tìm lỗi trong các sửa đổi hoặc chuẩn bị thay đổi để commit.
---

# Review thay đổi

1. Lấy diff: `git diff` và `git diff --staged`.
2. Với mỗi file đã sửa, kiểm tra:
   - dữ liệu đầu vào của người dùng được escape khi hiển thị;
   - truy vấn SQL dùng tham số hóa;
   - không còn đầu ra debug và file tạm.
3. Chạy test và linter của dự án (lệnh xem trong CLAUDE.md).
4. Báo cáo: danh sách vấn đề kèm file và dòng, từ nghiêm trọng đến nhỏ.
   Nếu không có vấn đề nào — nói thẳng như vậy, không bịa thêm nhận xét.

Skill như vậy biến «xem giúp mọi thứ có ổn không» thành một kiểm tra có thể lặp lại, với cùng một bộ điểm kiểm tra qua mỗi lần.

Skill kết thúc phiên

Một loại hữu ích khác là nghi thức cuối phiên: dừng môi trường cục bộ, xóa file tạm, ghi vào nhật ký tiến độ những gì đã làm và còn lại gì, rồi commit với mô tả chi tiết. Điều này trực tiếp khắc phục việc mất ngữ cảnh giữa các phiên: phiên sau bắt đầu từ trạng thái repository được cập nhật, chứ không phải từ phỏng đoán.

Lỗi thường gặp

• Mô tả mơ hồ. Skill có đó nhưng agent không gọi. Khắc phục bằng cách viết lại description với các tín hiệu cụ thể.
• Skill quá dài như một bản văn. Toàn bộ mục cũ dài 400 dòng được chuyển vào SKILL.md. Vấn đề ngữ cảnh phình to quay lại, chỉ là muộn hơn. Giữ nội dung chính ngắn, chi tiết để ở file lân cận.
• Trùng lặp với CLAUDE.md. Cùng một quy trình được mô tả ở hai nơi và dần lệch nhau. Nguồn sự thật phải chỉ có một.
• Skill chồng chéo. Hai skill có mô tả gần giống nhau — agent chọn ngẫu nhiên giữa chúng. Hãy phân tách rõ bằng «dùng khi / không dùng khi».
• Lệnh đã lỗi thời. Script đã đổi tên nhưng skill vẫn tham chiếu tên cũ. Skill là một phần của code dự án: hãy sửa nó trong cùng commit với quy trình.

Khi nào nên chuyển một mục sang skill

Nên định kỳ đọc lại CLAUDE.md và với mỗi mục tự hỏi: trong bao nhiêu phần tác vụ thông thường mục này thực sự cần? Nếu gần như luôn luôn — nó đúng chỗ. Nếu chỉ trong một tác vụ trên mười — đó là ứng viên cho skill.

Dấu hiệu thứ hai là độ dài. Mục không vừa một màn hình gần như chắc chắn mô tả một quy trình chứ không phải một quy tắc. Quy trình dễ đọc trọn vẹn vào lúc thực hiện hơn là giữ nền suốt phiên.

Dấu hiệu thứ ba là những lời giải thích lặp đi lặp lại. Nếu bạn cứ nhắc agent cùng những điều chỉnh cho cùng một tác vụ, hãy ghi chúng một lần vào skill. Sau một tuần, xem số lần bạn phải sửa tay có giảm không: đó chính là phép kiểm tra skill có hiệu quả hay không.

Tổng kết

Skills của Claude Code là cách giữ các quy trình ngay trong dự án và không phải trả giá bằng ngữ cảnh ở mỗi phiên. Mô tả skill luôn hiển thị, thân skill được nạp khi cần, file hỗ trợ còn nạp muộn hơn nữa. CLAUDE.md giữ bản đồ dự án và các quy tắc cứng, còn các tác vụ theo loại như deploy, review, phát hành được chuyển sang skill. Cấu trúc file hướng dẫn và cách mở rộng ngữ cảnh dần theo từng lớp được chúng tôi trình bày thực hành trong khóa học về harness engineering.