AGENTS.md, Skills, or MCP: Where Should Review Rules Live?
A practical placement guide for code-review rules: separate repository constraints, reusable procedures, and live tool access, then verify the boundaries with a small pilot.
2026-09-09
保留发布时的原文,未自动翻译。
Start with the review failure, not the integration
A team asks an agent to review a database migration. The answer discusses style but misses the rollback requirement, checks the wrong test command, and says that continuous integration passed without consulting the current run. Adding another tool will not solve all three failures.
They involve different missing inputs: a repository rule, a repeatable review procedure, and current evidence. Our recommendation is to assign each input an explicit home before changing the agent configuration. That makes it easier to diagnose an incomplete review without copying an entire instruction manual into every prompt.
Methodology: compare responsibilities, not popularity
This is a documentation-based comparison checked on September 9, 2026, not a benchmark of agents or review quality. We selected three mechanisms because they answer different questions: what is special about this repository, how should this task be performed, and how can the agent obtain external context or take an authorized action?
The examples below are proposed team practices. We did not execute the integrations, inspect a private repository, or measure token savings. Treat the placement rules as an architecture proposal to validate in your own agent host.
Put repository-specific facts in project instructions
The AGENTS.md project describes a Markdown location for agent-facing repository guidance, including setup, testing, conventions, and contribution context. It is a suitable place to document facts that change when the repository changes.
For our migration example, we would put the database test command, migration directory, and required rollback documentation in project instructions. A reviewer should not have to infer these from a generic review skill.
A useful placement test is: would this statement remain correct if the same review procedure ran in a different repository? If not, keep the statement with the project. Give the team an owner for maintaining it. A stale test command is still stale even when an agent reads it consistently.
Do not turn a project instruction into an authorization shortcut. A rule explaining how deployments work does not mean every review request authorizes a deployment.
Put the repeatable procedure in a skill
The Agent Skills specification defines a skill directory around SKILL.md, with required name and description metadata and optional supporting scripts, references, and assets. Skills can therefore package more than a short prompt.
For this review task, a portable procedure could ask the agent to inspect the diff, identify affected behavior, locate supporting tests, distinguish observed defects from questions, and produce findings with evidence. It should obtain repository-specific commands from project guidance instead of embedding one team's paths.
Our proposed output contract has four fields per finding:
- Location: the file and relevant code or change.
- Failure: the concrete behavior that could go wrong.
- Evidence: the diff, test, or documented requirement supporting the finding.
- Confidence and next step: what is known and what still needs verification.
This contract is a team design choice, not a guarantee supplied by the skill format. Inspect any bundled executable resources separately before allowing them to run.
Use MCP for capabilities and current context
The MCP architecture documentation describes hosts connecting through clients to servers that expose capabilities such as tools, resources, and prompts. It provides a connection mechanism; it does not determine your team's definition of an acceptable review.
In the migration example, an authorized integration might retrieve the current CI result or issue context. Local project instructions describe the requirement, the skill describes how to reason about it, and the integration supplies evidence that can change between runs.
We recommend starting with read-only access for review tasks. Posting a comment, editing a branch, or merging a change should remain a separate action with its own authorization. Retrieved issue text and repository content should be treated as task data, not permission to expand the workflow.
Pilot the separation with three explicit checks
Choose a small, non-production change and write down the expected observations before involving the agent. The following is a proposed acceptance exercise, not a test we have performed.
First, introduce a harmless repository-specific constraint in the review fixture, such as requiring a rollback note for a migration. Check whether the report identifies the missing note and cites the actual requirement rather than inventing a general best practice.
Second, ask for findings in the evidence format above. Reject a report that offers only broad advice such as adding more tests. The useful question is whether a teammate can reproduce or investigate each finding.
Third, make current CI evidence unavailable in the fixture. The report should say that CI could not be verified. It should not convert an inaccessible tool, an old status, or a repository instruction into a claim that tests passed.
Record the host version, enabled integrations, instruction locations, and any actions actually taken. These details make a later regression understandable.
Limitations and a maintenance rule
Instruction discovery, precedence, tool permissions, and skill loading vary across hosts. Verify those behaviors in the client you use; this article is not a universal precedence specification. A well-placed instruction also does not guarantee model compliance or code correctness.
Avoid maintaining the same rule in three places. Keep the repository fact with the repository, reference it from the procedure, and preserve the origin and time of external evidence. If a pilot fails, fix the missing layer rather than enlarging every prompt.
When exploring the OpenAgentSkill directory, evaluate a review skill by its procedure and dependencies, not its title alone. Use the integration documentation to understand the registry surface, then confirm the actual package and host behavior before adoption.