Separating the Roles of AGENTS.md, Skills, and MCP

As an AI agent setup grows, it becomes difficult to decide whether a rule is needed every time, whether a procedure belongs in a Skill, or where an external connection should be declared. Putting everything in AGENTS.md solves one problem and creates another: every task receives a larger context.

I compared the official Codex concepts with OpenCode’s corresponding configuration. A useful boundary is to put project rules that always apply in AGENTS.md, conditional procedures in Skills, and access to external systems in MCP. Personal defaults should not become team contracts.

Start with four responsibilities

Location	When it applies	Put here	Keep out
AGENTS.md	Every task in the project	Structure, commands, prohibitions, completion checks	Long specialist procedures, secrets
Skill	A matching kind of request	Inputs, steps, verification, templates	Short rules shared by every task
MCP	External data or actions are needed	GitHub, databases, browsers, internal APIs	Coding conventions
Personal settings	Only your environment	Tone, display, defaults	Required team policy

AGENTS.md, Skills, and MCP are described as separate extension points in Codex. OpenCode has rules, skills, and MCP servers as well, but file discovery and configuration syntax are not identical.

The table is useful because it classifies information by when it is needed, rather than by filename.

Keep AGENTS.md as a short project contract

Put information here when an agent must know it on every task to avoid a dangerous or confusing result:

• Responsibility of each directory
• Node.js and package-manager versions
• Lint, test, and build commands
• Generated files that must not be edited directly
• Approval boundaries for destructive operations and publication
• Verification conditions after a change

Move detailed background and long procedures to separate documents and link to them from AGENTS.md. A short entry point makes important constraints less likely to disappear inside an explanation.

A repository AGENTS.md describes a team-reproducible policy and is therefore a natural version-controlled file. A home-directory configuration is a personal default, not a substitute for a required project rule.

Make a Skill a conditional procedure

A Skill is a good home for knowledge that is repeated for one class of work but unnecessary for every task. It can contain more than prose: templates, verification scripts, and references are useful parts of the package.

At minimum, document:

1. When to use it and when not to
2. Its inputs and expected outputs
3. The order of operations
4. Stop conditions and a safe response to failure
5. Checks required before completion

For example, “create a PDF and check its links” is a Skill-shaped task. “Use pnpm in this repository” is a short always-on contract and belongs in AGENTS.md.

Treat MCP as a permissioned external connection

MCP is an entry point to data or actions outside the local project. Reading GitHub issues, querying a database, and operating a browser have a different risk profile from a local procedure in a markdown file.

The question is not only whether the connection works:

• Are read and write capabilities separated?
• Do deletion, publication, sending, and billing require approval?
• Are credentials kept out of settings files and Skill text?
• Do failures avoid logging secrets and personal data?

“The agent can perform an action through MCP” is not the same as “the agent may perform it without confirmation.” Decide on least privilege and approval boundaries first.

Do not treat @file as a common standard

Syntax such as @file is often a UI feature that adds a file to one harness’s context. It is not a shared standard for AGENTS.md, Skills, or MCP and should not become a persistent dependency without checking the target tool.

Keep long-lived information in real files and link to it with the format supported by each tool. Do not make team operations depend on an attachment notation that is resolved only inside one conversation.

Decide what to share

Naming rules, coding conventions, representative verification commands, and publishable text templates are usually easy to share across harnesses.

Keep these tool-specific instead:

• Credentials and MCP execution commands
• Product-specific permissions and sandbox settings
• Caches and session history
• Skill installation locations and discovery order

If a common source generates thin adapters for each tool, document the conversion rules and generated paths so the diff can be reviewed. An implicit network of symbolic links can make a change in one harness affect another unexpectedly.

Use a fixed decision order

When deciding where new information belongs, ask:

1. Is it needed for every task? Use AGENTS.md.
2. Is it repeated for a particular kind of work? Use a Skill.
3. Does it require external data or an external action? Use MCP.
4. Is it only your preference? Use personal settings.

Keep one source of truth instead of copying the same rule into multiple locations. This boundary controls context growth, configuration contradictions, and unnecessarily broad external permissions at the same time.