Bài 6 trong loạt Vibe Code A to Z — hướng dẫn vibe code bằng Claude Code cho người Việt. Bài 5: MCP là gì, kết nối thế nào.
Mỗi lần đăng một bài lên website, tôi phải làm bảy việc theo đúng thứ tự. Thêm dữ liệu bài vào file danh sách. Chèn ảnh đại diện vào thân bài. Đổi cái marker tài liệu thành component thật. Chép file tải về đúng thư mục. Chạy lệnh tự nối link nội bộ. Chạy lệnh kiểm tra nội dung. Rồi mới commit.
Bảy việc đó không khó. Chúng chỉ có một tính chất khó chịu: bỏ sót một bước thì bài lên vẫn trông bình thường, và tôi chỉ phát hiện ra vài ngày sau.
Nên tôi làm cái việc ai cũng làm — gõ lại bảy bước đó cho Claude Code, mỗi lần đăng bài. Đến lần thứ tư thì tôi nhận ra mình đang chép tay cùng một đoạn văn bản, tuần này qua tuần khác, cho một con AI vốn dĩ sinh ra để khỏi phải chép tay.
Đó chính xác là lúc nên viết một Skill.
Skill là gì, và vì sao nó không phải CLAUDE.md thứ hai
Skill là một thư mục có một file tên `SKILL.md` bên trong. Trong file đó bạn viết quy trình của mình bằng lời thường. Xong.
Câu hỏi hợp lý là: vậy khác gì viết thẳng vào CLAUDE.md?
Khác ở một điểm, và điểm đó quyết định tất cả. CLAUDE.md nạp vào đầu mỗi phiên, dù bạn có cần hay không. Skill chỉ nạp khi thật sự đến lúc dùng.
Nhớ lại nghịch lý ở bài 3: file dặn dò càng dài thì Claude càng ít nghe lời, khuyến nghị là dưới 200 dòng. Nghịch lý đó chỉ đúng với thứ nạp thường trực. Với Skill thì ngược lại — tài liệu chính thức nói thẳng rằng thân của một skill chỉ được nạp khi nó được dùng, nên tài liệu tham chiếu dài gần như không tốn gì cho tới lúc bạn cần đến nó.
Ranh giới vì thế rất gọn, và tôi dùng đúng một câu để chia: CLAUDE.md giữ sự thật, Skill giữ quy trình. Dự án chạy bằng gì, file nằm ở đâu, quy ước nào không được phá — đó là sự thật, luôn đúng, để ở CLAUDE.md. Còn "muốn đăng một bài thì làm bảy bước sau" là quy trình: chỉ đúng vào lúc bạn đăng bài, và chín mươi phần trăm thời gian còn lại nó chỉ ngồi chiếm chỗ.
Tài liệu còn đưa ra một dấu hiệu nhận biết mà tôi thấy chính xác đến mức hơi ngượng: khi một mục trong CLAUDE.md của bạn đã phình từ một điều-cần-biết thành một quy-trình-cần-làm, đó là lúc nó nên rời khỏi CLAUDE.md và thành một skill.
Cấu tạo một skill
Thư mục tên gì thì lệnh gọi tên đó. Thư mục `dang-bai` cho bạn lệnh `/dang-bai`. Bên trong, `SKILL.md` gồm hai phần, ngăn cách bằng hai dòng ba gạch ngang.
Phần trên là khai báo. Ví dụ thật từ skill `dang-bai` của chính website này: `description: Đăng một bài viết mới lên website. Dùng khi người dùng nói "đăng bài", "lên bài mới", hoặc đưa một file nội dung kèm ảnh.` Phần dưới là quy trình, viết bằng lời thường, bao nhiêu dòng cũng được — ở skill đó là chuỗi bước bắt đầu bằng thêm object vào đầu mảng `POSTS` trong `app/tai-viet/posts.ts`, rồi chèn ảnh đại diện vào thân bài, và tiếp tục cho tới bước cuối.
Trong tất cả các trường khai báo, chỉ có `description` là thứ đáng bỏ công. Mọi trường khác đều tùy chọn. Cơ chế thật sự đơn giản: Claude Code nạp sẵn danh sách tên và mô tả của mọi skill, rồi dựa vào mô tả đó để đoán xem yêu cầu của bạn có khớp cái nào không. Mô tả viết tốt thì skill tự nhảy vào đúng lúc. Mô tả viết dở thì nó nằm im mãi mãi.
Nguyên tắc viết mô tả: dùng đúng những từ mà bạn sẽ gõ ra khi cần nó, không dùng từ chuyên môn của người viết ra nó. Nhìn lại mô tả skill của tôi ở trên — đoạn `Dùng khi người dùng nói "đăng bài", "lên bài mới"` không phải cho đẹp. Đó là mồi để nó bắt đúng câu tôi thật sự gõ.
Vài trường khác đáng biết, không cần thuộc:
- `disable-model-invocation: true` — cấm Claude tự gọi, chỉ chạy khi bạn gõ `/tên-skill`. Dùng cho việc có hậu quả như deploy hay commit, thứ bạn muốn tự tay bấm nút.
- `allowed-tools` — cho phép trước một số lệnh để nó khỏi hỏi xin phép từng cái trong lượt đó.
- `context: fork` — chạy skill trong một phiên phụ riêng, kết quả trả về gọn, không làm rối phiên chính.
Để skill ở đâu
Ba chỗ, cùng logic phân tầng như file dặn dò ở bài 3:
- Cá nhân — `~/.claude/skills/tên-skill/SKILL.md`, dùng được ở mọi dự án trên máy bạn.
- Dự án — `.claude/skills/tên-skill/SKILL.md`, riêng dự án này, đi cùng git.
- Plugin — nằm trong thư mục plugin, dùng được ở nơi nào bật plugin đó.
Chọn chỗ theo một câu hỏi: quy trình này thuộc về bạn hay thuộc về dự án? Cách bạn muốn được báo cáo kết quả là của bạn — để tầng cá nhân. Bảy bước đăng bài lên website này là của dự án — để tầng dự án, vào git, ai mở dự án cũng có.
Một chi tiết dễ chịu: sửa file skill là có hiệu lực ngay trong phiên đang chạy, không phải khởi động lại. Nhưng nếu bạn vừa tạo mới cả thư mục `skills` lần đầu thì phải mở lại Claude Code, vì lúc phiên bắt đầu thư mục đó chưa tồn tại để nó theo dõi.
Cái bẫy trong chính dự án của tôi
Website của tôi có ba skill. Hai cái nằm trong file tên `SKILL.md`. Cái thứ ba, tôi đặt tên `skill.md` — chữ thường.
Trên máy tôi thì không sao cả. Windows không phân biệt chữ hoa chữ thường trong tên file, nên gọi kiểu gì nó cũng tìm ra. Vấn đề chỉ hiện ra khi dự án này chạy ở chỗ khác — máy Linux, phiên chạy trên đám mây — nơi `skill.md` và `SKILL.md` là hai file hoàn toàn khác nhau. Ở đó cái skill thứ ba của tôi đơn giản là không tồn tại.
Loại lỗi này có một đặc điểm khó chịu chung với cái bẫy AGENTS.md tôi kể ở bài 3: nó không báo lỗi. Không có dòng đỏ nào hiện ra. Bạn chỉ thấy Claude không làm cái việc lẽ ra nó phải biết làm, rồi bạn tự kết luận là "chắc tại AI nó không hiểu ý mình".
Hai bẫy còn lại, nói trước để bạn khỏi mất buổi chiều:
Skill không bao giờ được gọi. Chín trên mười lần là do mô tả. Cách kiểm tra nhanh nhất là hỏi thẳng nó: *"có những skill nào đang dùng được?"* — nếu skill của bạn không nằm trong danh sách thì vấn đề nằm ở chỗ đặt file, còn nếu có tên mà vẫn không tự chạy thì vấn đề nằm ở mô tả.
Có quá nhiều skill. Danh sách skill cũng có giới hạn chỗ chứa. Vượt ngưỡng thì phần mô tả bị cắt bớt, mà cắt mô tả nghĩa là cắt luôn mấy từ khóa dùng để nhận diện. Cái bị cắt trước là những skill bạn ít dùng nhất — nghe thì hợp lý, nhưng nó cũng có nghĩa là skill bạn viết xong rồi bỏ quên sẽ lặng lẽ mất tác dụng.
Chỗ Skill thật sự hơn hẳn một file dặn dò
Một skill không chỉ có `SKILL.md`. Nó là cả một thư mục, và bạn để được thêm gì vào đó cũng được: bản mẫu để điền, ví dụ mẫu về kết quả mong muốn, tài liệu tra cứu dài, và cả script chạy được.
Nhìn vào đúng thư mục `dang-bai` của website này: `SKILL.md` giữ quy trình chính, một file `vi-du-bai-mau.md` chỉ đọc khi cần đối chiếu, và một thư mục con `scripts/` chứa `publish.py` — thứ được chạy, không phải được đọc.
Cách bố trí này giải quyết đúng cái khó của mọi quy trình thật: phần cần nhớ thì ngắn, phần cần tra thì dài. `SKILL.md` đóng vai mục lục — ghi rõ file nào chứa gì và khi nào cần mở. Claude đọc mục lục trước, chỉ mở file nặng khi thật sự chạm tới việc đó.
Riêng script thì có một khác biệt đáng giá mà tôi chỉ hiểu sau khi dùng: script được chạy, không phải được đọc. Một đoạn kiểm tra bảy điều kiện, viết thành script thì lần nào chạy cũng cho ra đúng bảy kết quả đó. Còn viết thành bảy dòng dặn dò thì nó là bảy lời nhắc — và lời nhắc thì có thể bị bỏ sót. Việc nào sai một lần là hỏng, đừng giao cho trí nhớ, hãy giao cho script.
Tài liệu tải về
Tôi đóng gói một skill mẫu hoàn chỉnh, không phải đoạn code cắt ra từ tài liệu: đủ `SKILL.md` có chú thích từng dòng khai báo, một file tham chiếu phụ để bạn thấy cách tách phần dài ra, một script mẫu chạy được, và một bản hướng dẫn ghi rõ chép vào đâu thì nó chạy. Kèm theo là bảng đối chiếu "việc này nên để ở CLAUDE.md hay ở Skill" — dùng cho lúc phân vân.
📥 Tải miễn phí
Một Skill Mẫu Hoàn Chỉnh
Tài liệu do tôi biên soạn từ trải nghiệm thật, tham khảo tài liệu chính thức của Anthropic tại code.claude.com/docs. Công cụ này thay đổi rất nhanh — khi có nghi ngờ, bản gốc tiếng Anh luôn là nguồn đúng nhất. Còn cách nghĩ về việc nào nên giao cho công cụ, việc nào không, nằm ở phần nền trong khóa AI Fluency.
Điều tôi nhận ra
Viết skill đầu tiên xong, tôi tưởng mình vừa tiết kiệm được thời gian. Đúng, nhưng đó là phần nhỏ.
Phần lớn hơn là cái này: khi ngồi viết bảy bước đăng bài ra thành văn bản, tôi phát hiện bước thứ năm của mình bấy lâu nay vẫn làm sai thứ tự. Không phải Claude làm sai. Là tôi, trong đầu, vẫn nhớ nhầm. Suốt mấy tháng.
Buộc phải viết quy trình ra cho một cái máy đọc thì bạn không được phép mơ hồ chỗ nào cả. Máy không tự hiểu ý, không tự đoán bạn muốn gì, không tự bỏ qua chỗ bạn viết lộn. Cái kỷ luật đó, hóa ra, có lợi cho tôi trước khi có lợi cho nó.
Đến đây thì Claude Code đã có bộ não của dự án, hiểu cách bạn giao việc, nối được ra ngoài, và học được quy trình riêng của bạn. Nó làm việc tốt. Và chính vì nó làm việc tốt mà một câu hỏi mới xuất hiện, câu hỏi mà tôi nghĩ là khó nhất trong cả loạt bài này: bạn sắp gộp vào sản phẩm của mình một đống code mà bạn không tự viết ra, và cũng không đọc hiểu hết. Vậy dựa vào đâu để nói rằng nó ổn? Đó là chuyện của bài sau.
