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.mdCLAUDE.md nên chứa gì?
CLAUDE.md là lớp chỉ dẫn "luôn bật" dành riêng cho Claude Code, hoạt động theo cơ chế
xếp chồng (stacking): chỉ dẫn được nạp nối tiếp
từ Managed/Enterprise Policy, xuống User (~/.claude/CLAUDE.md), rồi Project (./CLAUDE.md) và cuối
cùng là Local (./CLAUDE.local.md). Vì lớp cục bộ được nối sau cùng, nó nằm ở cuối cửa sổ ngữ cảnh —
đúng "điểm vàng" mà mô hình tuân thủ mạnh nhất. Cũng vì "luôn bật", file này rất dễ bị "béo phì" do lập
trình viên copy-paste nguyên cả bộ quy tắc chung vào.
Nội dung CLAUDE.md chỉ nên tập trung vào những thứ "non-obvious" — thứ agent không thể tự suy ra từ
package.json hay cấu trúc thư mục:
- Danh tính dự án: mục đích cốt lõi và các rào cản kỹ thuật đặc thù.
- Quy ước code: các quy tắc thực thi (ví dụ: cấm dùng default export).
- Lệnh chính xác: chuỗi lệnh build/test/deploy đúng của dự án.
- Quyết định kiến trúc: các mẫu thiết kế không hiển thị rõ trong code.
Để xử lý các thất bại về phán đoán, nhiều đội áp dụng 4 nguyên tắc hành vi của Karpathy: không giả định (hỏi khi chưa rõ), code tối giản (không trừu tượng hóa thừa), thay đổi chính xác (surgical diffs), và xác định tiêu chí thành công rõ ràng. Bốn nguyên tắc này hoạt động như lan can cứng, buộc AI làm việc với độ chính xác của một kỹ sư cấp cao thay vì "vẽ" thêm cho một sửa đổi đơn giản.
Một cảnh báo quan trọng: Claude chỉ tuân thủ tốt trong khoảng 150–200 chỉ dẫn. Vượt ngưỡng này, khả năng tuân thủ cả quy tắc cũ lẫn mới đều suy giảm đồng loạt — hiện tượng Uniform Decay. Vì system prompt mặc định đã ngốn khoảng 50 chỉ dẫn, phần "always-on" của riêng dự án có ngân sách khá chật. Khi cần một quy trình bắt buộc phải chạy, hãy ghi đè "cổng liên quan" (relevance gate) của Claude bằng thẻ điều kiện, và import phần chung thay vì chép lại:
@AGENTS.md
<important if="environment == 'production'">
Luôn chạy script `check_reversibility.py` trước khi thực hiện bất kỳ migration nào.
</important>AGENTS.md nên chứa gì?
Được ví như "README dành cho máy", AGENTS.md chỉ
nên chứa "gap content" — thông tin agent không thể tự khám phá bằng ls hay find: cờ lệnh không mặc
định, cấu hình CI/kiểm thử đặc thù, và các ràng buộc kiến trúc. Đây là bản "briefing" nền tảng mà mọi
công cụ, từ Cursor, Copilot đến Claude Code, đều đọc được.
Nhưng thêm file không tự động khiến agent thông minh hơn — chất lượng và nguồn gốc dữ liệu mới quyết định. Dữ liệu từ nghiên cứu của ETH Zurich cho thấy file do người viết giúp tăng khoảng 4% tỷ lệ thành công, trong khi file do AI tự tạo lại làm giảm 0,5–2% hiệu suất, gần như luôn vì cùng một lý do: sự trùng lặp. File auto-generated hay chép lại thông tin đã có sẵn trong repo, tạo nhiễu ngữ nghĩa và làm rối suy luận của agent.
Lạm dụng AGENTS.md dẫn tới nghịch lý thăm dò (Exploration Paradox): agent đọc thêm nhiều file và sinh thêm token suy luận, nhưng lại tốn thêm 2–4 bước mà không định vị bug nhanh hơn. Mỗi token bị chèn vào file always-on là một khoản "thuế phí suy luận" — trung bình trên 20% cho mỗi lượt chạy. Vì vậy, phải cân nhắc kỹ thứ gì xứng đáng "luôn bật".
Với monorepo, AGENTS.md dùng quy tắc "nearest-file-wins": file nằm trong thư mục con được đọc trước và ghi đè quy tắc chung ở gốc. OpenAI vận hành một cấu trúc 88 file theo cách này để giữ cửa sổ ngữ cảnh luôn cô đọng — agent sửa lỗi CSS ở frontend không bị nhồi các quy tắc backend không liên quan.
SKILL.md và cơ chế "cổng" của description
SKILL.md đại diện cho bộ nhớ quy trình (procedural memory): thay vì nạp mọi thứ vào cửa sổ ngữ cảnh, nó dùng cơ chế tiết lộ tăng dần (progressive disclosure) theo ba tầng:
- Tầng 1 — Khám phá: ở đầu phiên, agent chỉ nạp metadata (name + description) của từng skill, tốn khoảng 50–100 token mỗi skill.
- Tầng 2 — Kích hoạt: chỉ khi ý định của người dùng khớp với mô tả, nội dung đầy đủ của SKILL.md mới được nạp.
- Tầng 3 — Thực thi: script và tài liệu tham khảo chỉ được nạp khi quy trình thực sự chạy.
"Người gác cổng" của toàn bộ hệ thống là trường description trong YAML frontmatter. Đây là một
giao diện lập trình thực thụ: tác giả mã hóa logic kích hoạt vào đó bằng quy ước
TRIGGER/SKIP viết bằng ngôn ngữ tự nhiên (không phải trường schema cứng). Nếu người dùng hỏi về Postgres
mà mô tả không khớp, agent sẽ không bao giờ mở phần thân skill.
---
name: db-migration
description: |
TRIGGER khi người dùng yêu cầu thay đổi schema Postgres hoặc chạy migration.
SKIP với các truy vấn SQL chỉ đọc hoặc báo cáo dữ liệu thông thường.
---Một lưu ý an ninh cần cân nhắc trước khi đưa dữ liệu nhạy cảm qua skill: Agent Skills không thuộc diện Zero Data Retention (ZDR) — dữ liệu đi qua tính năng này được lưu theo chính sách tiêu chuẩn. Trong môi trường tài chính hay y tế yêu cầu ZDR, đó là một ràng buộc thật sự cần tính đến.
Bảng quyết định: đặt một chỉ dẫn mới vào đâu?
Khi đã nắm rõ mô hình nạp, việc đặt một chỉ dẫn mới trở nên gần như cơ học: cứ hỏi "quy tắc này có cần chạy ở mọi lượt không?".
| Tiêu chí | AGENTS.md | CLAUDE.md | SKILL.md |
|---|---|---|---|
| Đối tượng | Đa công cụ (Cursor, Copilot, agent) | Chỉ Claude Code | Quy trình chuyên biệt |
| Cơ chế nạp | Always-on (luôn bật) | Always-on (luôn bật) | Gated (có điều kiện) |
| Nội dung | Build/test, ngữ cảnh chung dự án | Memory import, quy tắc riêng Claude | Workflow nhiều bước, từ vựng chuyên ngành |
| Điểm mạnh | Giảm 28,64% runtime | Tối ưu cho terminal CLI | Tiết kiệm token, giảm nhiễu |
Quy tắc phải chạy ở mọi lượt (lệnh build/test, quy ước style, kiến trúc chung) thuộc về AGENTS.md. Chỉ dẫn chỉ có nghĩa với Claude Code thuộc về CLAUDE.md. Còn quy trình chuyên biệt chỉ áp dụng cho tác vụ cụ thể (ví dụ "cách xoay vòng API key") phải nằm sau một cổng SKILL.md.
Vì sao phải bảo vệ ngân sách ngữ cảnh always-on?
Lợi ích hiệu suất của AGENTS.md chỉ giữ được khi ngữ cảnh vẫn liên quan tới tác vụ hiện tại. Nếu bạn nhét một quy trình migration dài 500 từ vào AGENTS.md gốc, agent phải đọc về cơ chế khóa Postgres ngay cả khi đang sửa một bug state ở frontend — cửa sổ ngữ cảnh bị chiếm dụng và cơ chế chú ý (attention) bị pha loãng vào thứ không liên quan.
Cách bảo vệ ngân sách này rất trực tiếp: chuyển các quy trình tình huống vào SKILL.md để phần gốc luôn gọn. Nhờ đó agent vẫn hưởng lợi ích runtime của ngữ cảnh chung mà không phải trả "thuế attention" cho các chỉ dẫn không liên quan. Và tuyệt đối đừng phát hành một file ngữ cảnh do AI tự sinh mà chưa biên tập lại bằng tay — chính bước cắt tỉa thủ công mới loại được phần trùng lặp gây nhiễu.
Nên dùng file nào, khi nào?
Nếu bạn chỉ dùng Claude Code, hãy bắt đầu bằng một CLAUDE.md tối giản có @AGENTS.md, và dồn mọi quy tắc
chung vào AGENTS.md. Trong môi trường đa công cụ, hãy làm giàu AGENTS.md như nền tảng — nhưng giữ nó dưới
ngưỡng ~150 chỉ dẫn để tránh Uniform Decay, và áp dụng "nearest-file-wins" cho dự án lớn. Mọi quy trình
lặp lại hoặc đòi hỏi độ chính xác cao thì đóng gói thành SKILL.md, để nó nằm im sau cổng cho tới khi tác
vụ thực sự cần.
Nguyên tắc vàng chỉ có một: nếu agent có thể tự tìm ra thông tin bằng ls hoặc đọc README.md, đừng đưa
nó vào file cấu hình. Chọn file không phải là câu hỏi về sở thích, mà là một bài toán tối ưu kiến trúc
ngữ cảnh — đặt mỗi chỉ dẫn đúng theo cách nó được nạp, và bạn trả tiền token cho đúng thứ mình cần.
Tài liệu tham khảo
- CLAUDE.md vs AGENTS.md vs SKILL.md: Which File Owns What in 2026 — Towards AI
- AGENTS.md — Open Format for Guiding Coding Agents
- Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
- Repository-Level Context Files for Coding Agents (arXiv:2601.20404)
- Agent Skills Overview — AgentSkills.io
- Agent Skills — Claude Docs
- How Claude Remembers Your Project — Claude Code Docs