Agent Skills, MCP và AGENTS.md khác nhau thế nào?

Đặt ở đây những điều agent cần biết khi làm việc trong kho: lệnh test, cấu trúc thư mục, quy ước sửa mã và thao tác cần người dùng cho phép. Ví dụ sau là nội dung minh họa cho một repository dùng Python:

Use this layer for repository context: test commands, directory structure, coding conventions and operations requiring user authorization. This illustrative file describes a Python repository:

# Project instructions

- Run focused tests with the project Python environment.
- Keep generated artifacts out of source changes.
- Preserve public API behavior unless the task changes its contract.
- Report validation results before requesting a merge.
- Push or publish only when explicitly requested.

Codex có quy tắc khám phá AGENTS.md theo phạm vi và thư mục, được mô tả trong tài liệu OpenAI. Claude Code có cơ chế CLAUDE.md và cấu hình riêng. Không nên giả định mọi agent tự đọc cùng một tên tệp hoặc áp dụng cùng thứ tự ưu tiên.

Giữ hướng dẫn chung ngắn và cụ thể. Quy trình nhiều bước chỉ dùng cho một loại công việc có thể nằm trong skill để tránh đưa quá nhiều chi tiết vào mọi tác vụ.

Codex discovers AGENTS.md by scope and directory, as described in the OpenAI guide. Claude Code has its own CLAUDE.md and configuration mechanisms. Do not assume every agent automatically reads the same filename or applies identical precedence.

Keep shared instructions short and concrete. A detailed procedure used only for a particular task can live in a skill instead of adding that detail to every request.

Một skill có SKILL.md với tên, mô tả và hướng dẫn; có thể kèm scripts, references và assets. Agent dùng metadata để xác định mức phù hợp rồi đọc nội dung khi cần. Cách nhận diện và các trường mở rộng phụ thuộc ứng dụng.

Ví dụ, code-review hướng dẫn cách đối chiếu thay đổi với tiêu chuẩn và yêu cầu. Runbook giúp tổ chức quá trình review; nó không tự cấp quyền vào kho private hoặc chứng minh các test đã chạy.

A skill includes a SKILL.md with a name, description and instructions, optionally accompanied by scripts, references and assets. Agents use metadata to assess relevance and read the full procedure when needed. Discovery and extension fields depend on the application.

For example, code-review describes how to compare changes with standards and requirements. It organizes a review; it does not grant access to a private repository or establish that tests have run.

MCP chuẩn hóa giao tiếp giữa ứng dụng AI và các server cung cấp công cụ, tài nguyên hoặc prompt. Chẳng hạn, một tích hợp đã được cấu hình có thể cho phép đọc issue hoặc truy vấn dữ liệu phục vụ tác vụ. Khả năng thực tế còn phụ thuộc server, tài khoản, quyền và cách ứng dụng AI sử dụng giao thức.

Một skill nhắc đến công cụ MCP không tự cài hoặc xác thực công cụ đó. Ngược lại, có kết nối MCP chưa có nghĩa agent đã biết quy trình phù hợp để dùng nó. Nếu tác vụ chỉ cần đọc diff và chạy test local, các công cụ tích hợp sẵn có thể đã đủ.

MCP standardizes communication between an AI application and servers exposing tools, resources or prompts. A configured integration might allow reading an issue or querying task-relevant data. Actual capabilities depend on the server, account permissions and application support.

A skill mentioning an MCP tool does not install or authenticate that tool. A working MCP connection likewise does not provide a task-specific procedure by itself. Reading a local diff and running local tests may already be possible with built-in tools.

1. Hướng dẫn dự án xác định cách chạy test, phạm vi sửa và quy tắc không đẩy mã khi chưa được yêu cầu.
2. Skill review yêu cầu đọc diff, đối chiếu đặc tả và ghi phát hiện có bằng chứng.
3. Kết nối công cụ, nếu đã được phép, cung cấp issue chứa tiêu chí nghiệm thu hoặc dữ liệu kiểm tra cần thiết.
4. Agent thực hiện các bước trong quyền được cấp và báo rõ phần đã kiểm chứng, phần còn thiếu.

Nếu issue không truy cập được, có thể dùng bản đặc tả do người dùng cung cấp. Nếu test chưa chạy được, báo nguyên nhân; không suy diễn rằng có skill và MCP là mọi bước đã hoàn thành.

1. Project instructions define test commands, change scope and the rule against unrequested pushes.
2. The review skill asks for diff inspection, specification comparison and evidence-backed findings.
3. A tool connection, when authorized, provides an issue containing acceptance criteria or necessary test data.
4. The agent follows the workflow within its permissions and distinguishes verified results from missing evidence.

If the issue is inaccessible, use a specification supplied by the user. If tests cannot run, explain why. Having a skill and an MCP connection does not establish that the workflow has completed.

• Agent liên tục dùng sai lệnh test hoặc sửa nhầm thư mục: làm rõ hướng dẫn dự án.
• Cùng một tác vụ phải giải thích lại nhiều bước: đóng gói thành skill có phạm vi cụ thể.
• Agent thiếu dữ liệu hoặc thao tác từ hệ thống bên ngoài: kiểm tra tích hợp và quyền, trong đó MCP có thể là một lựa chọn.
• Skill đã cài nhưng không được nhận diện: kiểm tra đường dẫn và cơ chế discovery trước khi thêm tích hợp mới.

Bắt đầu từ một tình huống thật, giữ cấu hình nhỏ và kiểm tra kết quả từng lớp. Xem bài nền về Agent Skills và quy trình review PR để thực hành.

• The agent repeatedly chooses the wrong test command or directory: clarify project instructions.
• The same task requires repeatedly explaining a long procedure: package a focused skill.
• The agent lacks data or operations from an external system: check integrations and permissions; MCP may be one option.
• An installed skill is undiscoverable: investigate paths and discovery before adding another integration.

Start with a real task, keep configuration small and verify each layer. Continue with the Agent Skills introduction and the PR review workflow.