Câu hỏi CLAUDE.md vs AGENTS.md vs SKILL.md không phải là chọn file nào "thắng", mà là hiểu mỗi file được coding agent nạp vào ngữ cảnh theo cách nào — chính mô hình nạp (loading model) quyết định thứ gì nên nằm ở đâu.
Đây là quyết định bạn chỉ cần đưa ra một lần. CLAUDE.md và AGENTS.md là ngữ cảnh "luôn bật" (always-on) — được chèn thẳng vào system prompt ở đầu mỗi phiên; còn SKILL.md nạp theo cơ chế "cổng" (gated) — chỉ mở ra khi phần mô tả của nó khớp với việc bạn đang làm.
Nói ngắn gọn: AGENTS.md là tiêu chuẩn chung cho mọi công cụ; CLAUDE.md là lớp chỉ dẫn riêng để tinh chỉnh Claude Code; và SKILL.md là đơn vị đóng gói các quy trình phức tạp (procedural memory). Đặt sai chỗ không chỉ đội chi phí token mà còn gây nhiễu logic và tình trạng "mất trí nhớ" giữa các phiên làm việc.
Ba file, ba mô hình nạp ngữ cảnh
Cách ngành công nghiệp đi đến thế "chân vạc" này bắt đầu từ nửa cuối năm 2025. Tháng 8/2025, đặc tả AGENTS.md ra mắt như một bộ chỉ dẫn chung cho mọi trợ lý lập trình: một nơi để định nghĩa lệnh build, quy tắc kiểm thử và kiến trúc dự án mà Cursor, Copilot hay các agent độc lập đều đọc được. Hai tháng sau, tháng 10/2025, Anthropic giới thiệu Agent Skills — thay mô hình markdown phẳng bằng cấu trúc thư mục kỹ năng có metadata, script và tài liệu tham khảo riêng.
Đến tháng 12/2025, cả hai định dạng trở thành tiêu chuẩn mở: chuẩn skills công bố tại agentskills.io, còn đặc tả AGENTS.md chuyển về dưới Linux Foundation để làm nền tảng cho Agentic AI Foundation. Hơn 60.000 repository đã áp dụng và hàng chục công cụ đã hỗ trợ sẵn AGENTS.md. Hệ quả là nhiều đội kỹ thuật hiện viết cùng một bộ chỉ dẫn ở ba nơi — rồi thắc mắc vì sao agent chạy chậm và ngốn token.
Điểm mấu chốt để gỡ rối là một sự phân đôi kỹ thuật: ngữ cảnh được chèn (always-on) so với ngữ cảnh có cổng (just-in-time). File được chèn như CLAUDE.md và AGENTS.md tự động nối vào system prompt ngay khi phiên bắt đầu — nền tảng, nhưng luôn tốn một khoản chi phí cố định. Ngược lại, ngữ cảnh có cổng nằm im cho đến khi ý định của bạn khớp với metadata của một skill, lúc đó nội dung đầy đủ mới được nạp. Chính ranh giới này quyết định file nào nên chứa gì.
Vẫn còn một khoảng trống thực tế: tính đến hiện tại, Claude Code vẫn chưa đọc trực tiếp AGENTS.md, dù đã có hơn 4.300 kỹ sư yêu cầu. Giải pháp mà chính tài liệu của Anthropic đề xuất là dùng liên kết mềm (symlink) để giữ một nguồn sự thật duy nhất (source of truth) mà không phải nhân bản nội dung:
ln -s AGENTS.md CLAUDE.md