Skill cho AI agent: biến quy trình lặp lại thành thứ dùng lại được
Team mình có một bộ quy ước cho mỗi API endpoint: không trả entity ra ngoài mà map sang DTO, validate input, lỗi trả về theo một định dạng chung, log có mã request, và phải có integration test. Mỗi lần nhờ AI thêm endpoint, mình lại dán nguyên đoạn quy ước đó. Một lần quên dán, AI trả thẳng entity User ra API, kéo theo cả trường PasswordHash. Review bắt được, nhưng suýt nữa thì không.
Nên mình đóng gói bộ quy ước đó thành một skill. Từ lúc đó, mình chỉ cần nói "thêm API lấy danh sách đơn của khách", AI tự nạp đúng quy ước, đúng endpoint mẫu, mà mình không phải nhắc gì.
Đọc xong bài này, bạn sẽ hiểu skill là gì, khác prompt ở đâu, và tự làm được skill đầu tiên cho việc bạn hay lặp lại.
Skill khác prompt ở đâu
| Prompt | Skill | |
|---|---|---|
| Nằm ở đâu | Trong đầu bạn, trong file note, trong lịch sử chat | Một thư mục trong máy hoặc trong project |
| Khi nào được dùng | Khi bạn nhớ ra và dán vào | AI tự nạp khi gặp đúng loại việc |
| Dùng chung | Phải gửi qua lại cho nhau | Cả team cùng dùng một bản, cập nhật một chỗ |
| Cập nhật | Sửa xong dễ thất lạc bản cũ, bản mới | Sửa file, lần sau AI dùng bản mới |
Nói đơn giản: prompt là lời dặn miệng, skill là quy trình được viết thành văn bản và đặt đúng chỗ người làm sẽ tìm đến.
Bên trong một skill có gì
Với Claude Code (và các công cụ theo chuẩn Agent Skills), một skill là một thư mục, trong đó có file SKILL.md:
them-api-endpoint/
├── SKILL.md ← hướng dẫn chính
└── references/
├── endpoint-mau.md ← một endpoint đã review kỹ, dùng làm mẫu
└── dinh-dang-loi.md ← định dạng lỗi trả về và mã lỗi
Phần đầu file SKILL.md có một đoạn mô tả, và đây là phần quan trọng nhất của cả skill:
---
name: them-api-endpoint
description: Thêm hoặc sửa API endpoint trong project ASP.NET Core này theo
quy ước của team (DTO, validation, định dạng lỗi, log, integration test).
Dùng khi được nhờ thêm endpoint, thêm API, sửa controller, hoặc "làm API
cho màn hình X".
---
AI đọc phần mô tả của mọi skill đang có để quyết định nên dùng skill nào. Mô tả mơ hồ thì AI không biết khi nào nên dùng. Mô tả rõ "dùng khi nào" thì nó tự nạp đúng lúc.
Phần còn lại của file là hướng dẫn: các bước làm, những gì cần tránh, cách tự kiểm tra trước khi báo xong. Endpoint mẫu và những hướng dẫn dài được tách ra thư mục references/, AI chỉ đọc khi cần, đỡ tốn chỗ trong "trí nhớ ngắn hạn" của nó (mình đã nói về chuyện này ở bài về context window).
Một skill tốt viết thế nào
Giải thích lý do, đừng chỉ ra lệnh. "KHÔNG ĐƯỢC trả entity" là một mệnh lệnh. "Không trả entity trực tiếp vì entity có thể chứa trường nhạy cảm như PasswordHash, và đổi entity sẽ làm vỡ API của client" là một lý do. AI hiểu lý do thì xử lý được cả những trường hợp skill không nhắc tới, ví dụ một entity mới có trường InternalNote.
Có ví dụ thật. Một endpoint đã review kỹ trong references/ làm được việc mà mười dòng mô tả không làm được: AI nhìn vào là biết đặt file ở đâu, đặt tên thế nào, viết test ra sao.
Ngắn thôi. Skill dài cả nghìn dòng thì phần quan trọng bị lấp mất. Thứ gì chỉ cần trong vài trường hợp thì tách ra file tham khảo.
Có bước tự kiểm tra. Cuối skill của mình là vài việc AI phải làm trước khi báo xong: chạy integration test, gọi thử endpoint và xem response có trường nào thừa không, input sai có trả đúng định dạng lỗi không.
Skill là tài liệu sống
Đây là phần mình thấy giá trị nhất. Skill không phải viết một lần là xong. Mỗi lần gặp một lỗi mới, mình thêm một dòng:
| Lúc đó chuyện gì xảy ra | Dòng được thêm vào skill |
|---|---|
| API trả thời gian theo giờ máy chủ, app di động hiển thị lệch 7 tiếng | "Thời gian trả về luôn là UTC, kiểu DateTimeOffset", kèm lý do |
| Endpoint danh sách không phân trang, màn hình admin tải cả chục nghìn dòng | "Endpoint danh sách bắt buộc phân trang, mặc định 20, tối đa 100" |
| Integration test ghi dữ liệu vào database dùng chung của team | "Test chạy trên database tạo riêng cho test, xoá sau khi chạy" |
Lỗi nào đã gặp một lần thì không gặp lại lần hai, vì nó đã nằm trong skill. Giống một tài liệu onboarding mà mỗi bạn mới vào đều đọc, và mỗi lần ai đó vấp thì tài liệu dày thêm một dòng.
Khi nào không cần làm skill
- Việc chỉ làm một lần. Prompt là đủ.
- Việc mà quy trình còn đang thay đổi liên tục. Làm vài lần cho ổn định đã rồi mới đóng gói.
- Việc mà một dòng trong file
CLAUDE.mdcủa project là đủ nói hết.
Quy tắc mình dùng: việc gì phải dán cùng một đoạn hướng dẫn lần thứ ba thì đến lúc làm skill.
Mẫu skill đầu tiên
---
name: [ten-viec-viet-lien-khong-dau]
description: [Skill làm gì]. Dùng khi [những tình huống, cụm từ người dùng
hay nói khi cần việc này].
---
# [Tên việc]
## Mục tiêu
[Kết quả tốt trông như thế nào, và vì sao]
## Cách làm
1. [Bước 1, kèm lý do]
2. [Bước 2]
## Tránh
- [Lỗi đã gặp] vì [lý do]
## Kiểm tra trước khi giao
- [Câu hỏi tự kiểm 1]
- [Câu hỏi tự kiểm 2]
Thử ngay: nghĩ xem đoạn hướng dẫn nào bạn đã dán cho AI từ ba lần trở lên. Viết nó thành skill theo mẫu trên, đặt vào thư mục skill của công cụ bạn dùng (Claude Code là .claude/skills/ trong project hoặc ~/.claude/skills/ cho mọi project), rồi giao việc như bình thường xem AI có tự dùng nó không.
Bài sau là bài cuối của series: AI có thật sự làm mình nhanh hơn không, và cách tự đo thay vì đoán theo cảm giác. Bạn đã làm skill nào cho AI chưa, cho việc gì? Comment chia sẻ với mọi người nhé.
P.S. Bài này đúng chủ đề với PrimeKit, bộ skill mình tự làm và chia sẻ miễn phí cho Claude Code, Codex, Cursor, Gemini CLI. Trong đó có một skill để viết skill: skill-builder-studio. Nó giúp bạn viết phần mô tả sao cho AI kích hoạt đúng lúc, giữ phần hướng dẫn ngắn gọn, tách tài liệu tham khảo ra file riêng, và kiểm tra skill bằng tình huống thật. Cài cả bộ bằng npx @lovehlmmm/primekit init, rồi gõ /pk:skill-builder-studio kèm mô tả việc bạn muốn đóng gói. Skill tốt hay không vẫn phụ thuộc vào kinh nghiệm bạn đưa vào nó, phần đó không AI nào viết thay được.
Series khác của mình
- SQL thực chiến: Những bài học mình ước đã biết sớm hơn: viết query dễ đọc, đọc execution plan, lỗi NULL và N+1 không báo lỗi, schema và transaction, phân trang bằng con trỏ.
- Backend .NET thực chiến: những case hay gặp trên production: async/await làm treo API, HttpClient hết socket, EF Core kéo cả bảng, idempotency, outbox, caching, bảo mật API.
All rights reserved