Hướng dẫn: Dùng Skill, CLAUDE.md và AGENTS.md trong VS Code, ví dụ skill đọc số tiền thành chữ (copy chạy được ngay)
Nhiều bạn cài Claude Code (hoặc Codex) vào VS Code rồi chỉ dùng như một khung chat. Thực ra có 3 thứ giúp AI làm việc "đúng ý" dự án của bạn hơn rất nhiều: CLAUDE.md, AGENTS.md và Skill. Bài này giải thích từng thứ, rồi làm một ví dụ hoàn chỉnh: skill đọc số tiền thành chữ tiếng Việt (1.250.000 - "Một triệu hai trăm năm mươi nghìn đồng"), dùng khi viết hoá đơn, phiếu thu chi, hợp đồng. Toàn bộ nội dung file bên dưới đều copy dán là chạy được. ==================== PHẦN 1: HIỂU ĐÚNG 3 THỨ NÀY ==================== 1. CLAUDE.md - File hướng dẫn dành cho Claude Code, đặt ở thư mục gốc dự án. - Được nạp vào MỌI phiên làm việc, ngay từ đầu. - Nên chứa: "sự thật" về dự án như ngôn ngữ, quy ước code, lệnh chạy test, những điều cấm. - Nên ngắn gọn, vì nó luôn chiếm chỗ trong ngữ cảnh của AI. - Mẹo: gõ /init trong Claude Code để AI tự đọc dự án và tạo bản CLAUDE.md đầu tiên. 2. AGENTS.md - Cùng vai trò với CLAUDE.md, nhưng là chuẩn chung cho nhiều công cụ AI coding (Codex của OpenAI và nhiều công cụ khác đọc file này). - Nếu team dùng cả Claude Code và Codex: viết nội dung chính vào AGENTS.md, còn CLAUDE.md chỉ cần một dòng @AGENTS.md để "nhúng" nội dung đó vào. Sửa một chỗ, hai công cụ cùng dùng. 3. SKILL - Một "quy trình đóng gói": thư mục chứa file SKILL.md (hướng dẫn) và có thể kèm script, tài liệu tham khảo. - KHÁC CLAUDE.md ở chỗ: skill chỉ được nạp đầy đủ KHI CẦN. Có 20 skill cũng không làm AI chậm hay rối. - Nên chứa: các quy trình lặp lại (đọc số tiền, tạo báo cáo, deploy, viết test theo mẫu...). Cách nhớ nhanh: - CLAUDE.md / AGENTS.md = nội quy dự án, AI luôn mang theo. - Skill = sổ tay nghiệp vụ, AI chỉ mở ra khi gặp đúng việc. ==================== PHẦN 2: CÁC THÀNH PHẦN CỦA MỘT SKILL ==================== Một skill là một thư mục: vnd-to-words/ <- tên thư mục = tên skill ├── SKILL.md <- BẮT BUỘC, đúng tên viết hoa này ├── scripts/ <- tuỳ chọn: code để AI chạy │ └── vndtowords.py ├── references/ <- tuỳ chọn: tài liệu tham khảo, AI đọc khi cần └── assets/ <- tuỳ chọn: file mẫu, template File SKILL.md gồm 2 phần: (1) Phần đầu (frontmatter), nằm giữa 2 dòng --- --- name: vnd-to-words description: Mô tả skill làm gì và KHI NÀO cần dùng. --- (2) Phần thân: hướng dẫn chi tiết bằng ngôn ngữ tự nhiên (markdown), giống như viết hướng dẫn cho một nhân viên mới. AI ĐỌC VÀ NẠP SKILL THẾ NÀO? (PHẦN QUAN TRỌNG NHẤT) Skill được nạp theo 3 tầng: Tầng 1 - Khi mở phiên làm việc: AI chỉ đọc name và description của TẤT CẢ skill. Đây giống như "mục lục". Phần thân SKILL.md và script chưa hề được đọc. Tầng 2 - Khi bạn yêu cầu một việc: AI so yêu cầu của bạn với các description trong mục lục. Nếu thấy khớp, AI mới mở và đọc toàn bộ phần thân SKILL.md. Tầng 3 - Khi làm việc: theo hướng dẫn trong SKILL.md, AI chạy script hoặc đọc thêm file trong references/. Với script, AI chỉ nhận kết quả chạy, không cần đọc hết code. = Hệ quả: description viết dở thì AI KHÔNG BAO GIỜ biết để dùng skill, dù phần thân viết hay đến đâu. name: - Chữ thường, số, dấu gạch ngang. Ví dụ:…