AGENTS.md, Skills or MCP: What Each One Is Actually For

AGENTS.md, Agent Skills and MCP keep appearing in the same sentence, as if they were three layers of one stack that you choose between. I read the primary documentation for each, and that framing breaks down quickly. They solve different problems, and the difference shows up in three questions: when does it load, what does it cost and does anything enforce it?

This is the sequel to my article on harness engineering. In that vocabulary, AGENTS.md and skills are guides that steer the agent before it acts, and MCP tools are one way it acts or senses. If you want the details of AGENTS.md across tools, my AGENTS.md article covers it, and my MCP article covers the current protocol.

Transcript

Your agent keeps forgetting the build command, so you write a rule. Then it skips the release steps, so you write a longer rule. Now every session pays for both, whether it needs them or not. Three tools, three jobs. My rule of thumb: the agents file says what's always true in your repo. It loads every session, so keep it short. A skill teaches a procedure. Only its name and a short description sit in context. The full steps load when the agent decides that job has come up. MCP connects the agent to something outside the repo. Your tracker, your database, your error logs. The agents file and a skill's text enforce nothing. They're context the model weighs. An MCP server only enforces its own limits. A rule that must never break needs a permission or a hook. One catch. In Vercel's own narrow test, a skill was never invoked in fifty-six per cent of cases. A skill only helps if the agent actually loads it. The full breakdown is in the video linked below.

Watch the full 8-minute video on YouTube: https://youtu.be/bemCNi2G46I.

The one-line version

This summary is my own framing, not a quote from any vendor:

• AGENTS.md says what is always true in this repository.
• A skill says how to do a kind of job, when that job comes up.
• MCP says what the agent can reach outside the repository.

What each one is

AGENTS.md is a plain Markdown file with no required fields. The nearest file to the one being edited wins, and an explicit instruction from you in chat overrides it. It is stewarded by the Agentic AI Foundation under the Linux Foundation. The agents.md site says it is used by over 60k open-source projects (its own figure). Codex reads it natively, Cursor supports it, and Claude Code reads it when there is no CLAUDE.md.

An Agent Skill is a folder with a SKILL.md: YAML frontmatter with a name and a description, then Markdown instructions, plus optional scripts/, references/ and assets/. The open specification limits the description to 1,024 characters. Anthropic announced the format on 16 October 2025 and published it as an open standard on 18 December 2025. Claude Code, Codex and Cursor all read it.

MCP, the Model Context Protocol, is an open protocol between an agent's application and a server that exposes live capabilities. In the 2026-07-28 revision, servers offer three kinds of thing, and who controls each is part of the design:

• Tools are functions the model discovers and calls.
• Resources are data the application chooses to attach as context.
• Prompts are templates the user picks, for example from a slash-command menu.

When each one loads, and what it costs

This is the table that answers most "which one" questions. It follows the Claude Code, Codex and MCP documentation, and where products differ I say so.

	AGENTS.md / CLAUDE.md	Skill	MCP tool
Enters context	At session start, every session	Name and description always. Body only when used. Extra files only when read	Tool definitions at start in many clients, deferred in Claude Code by default. Results arrive on each call
Who decides	Nobody per turn. It is simply there	The model, or you by name. An author can make a skill user-only	The model decides to call. A human should be able to deny
Cost shape	Paid every session, relevant or not	Small fixed cost per installed skill. Large content is free until used	Schema cost per tool, plus the size of each result
Enforced?	No	No for the text. A hook in the skill's frontmatter can enforce	The server enforces its own limits, not your rules for the agent

Three details behind the table:

• Size advice reflects the always-loaded cost. Claude Code's documentation suggests keeping each CLAUDE.md file under 200 lines. Codex stops reading at 32 KiB by default. Cursor advises under 500 lines per rule.
• A skill's cost is mostly its description. The Agent Skills specification puts the metadata at about 100 tokens per skill and recommends keeping the body under 5,000 tokens, with SKILL.md under 500 lines. Treat 100 as a guide, not a measurement. Claude Code gives the skill list a budget of about 1 percent of the context window (configurable) and drops the least-used skills' descriptions when it overflows. Codex caps its list at 2 percent.
• MCP cost depends on the client. Anthropic's own example, from November 2025, showed a workflow dropping from 150,000 tokens to 2,000 when an agent called tools through code instead of loading every definition and passing every intermediate result through the model. Anthropic does not say how it measured the baseline. Claude Code enables tool search by default (not with a custom base URL, with it switched off, or on some older models), so only tool names load at the start and definitions are fetched when needed. This is from its documentation as of 13 October 2026. Anthropic describes tool search as reducing this cost, but I have not repeated its figures because I did not read that post.

What goes where

This table is my synthesis of the documented behaviour, not an official rule. Claude Code's own documentation gives the same split: facts that apply to every session go in the instruction file, and multi-step procedures or rules tied to part of the codebase go in a skill or a path-scoped rule.

You want the agent to...	Put it in
Know the build and test commands, layout and conventions	AGENTS.md
Follow the same rules in Cursor, Claude Code and Codex	AGENTS.md, imported into CLAUDE.md
Run a repeatable multi-step procedure, like a release or a migration	A skill
Apply a rule only when editing certain files	A path-scoped rule, or in Cursor a skill with a paths filter
Read live tickets, errors or database rows	An MCP server
Take an action in an outside system, like opening an issue	An MCP tool with approval
Let the user choose a canned workflow from a menu	An MCP prompt, or a skill the user invokes
Never touch a folder or never run a command	A permission or a hook, none of the three

Where they overlap

The boundaries blur in practice, and that is where mistakes happen.

• A long section in AGENTS.md is a skill in disguise. If it describes a procedure that matters for one task in ten, it costs tokens in the other nine.
• Skills and MCP prompts both package instructions the user can invoke by name. Skills can also be picked by the model and can travel with your repository. Prompts are user-triggered and travel with the server.
• A skill can use MCP. Codex lets a skill declare an MCP server as a dependency, and Claude Code skills can reference MCP tool names in allowed-tools, which the open specification marks experimental. The skill is the playbook and MCP is the hands.
• A skill's script can replace a small MCP server. A script costs context only for its output, with no schema. But MCP gives you standard authentication, discovery and approval, and a script gives you none of that.

What the evidence says

Two studies pull in different directions, and both have limits.

• Vercel, 27 January 2026. On tasks involving Next.js 16 APIs that were outside the models' training data, the baseline passed 53 percent. A skill used by default also passed 53 percent. Telling the agent explicitly to use the skill raised it to 79 percent, and an 8 KB documentation index in AGENTS.md reached 100 percent. The skill was never invoked in 56 percent of cases. This is a vendor's own eval on one narrow task, and the authors call their explanation a working theory. The lesson is not that AGENTS.md beats skills in general. It is that a skill only helps when the agent actually loads it.
• ETH Zurich, arXiv 2602.11988. The researchers found that repository context files generally did not raise task success and increased inference cost by over 20 percent on average, across both model-written and developer-written files. They report that agents follow the instructions, that the files help most for non-standard practices, and that repository overviews do not help (abstract of version 3, 29 September 2026). This is one study, so read it as "keep it minimal", not "AGENTS.md doesn't work". I read the abstract and a summary, not the full paper.

Security

All three are instructions the model may follow, so all three are injection surfaces, and none is a sandbox.

• AGENTS.md is reviewed in pull requests like code. A hostile repository can ship a hostile one.
• Skills: Anthropic advises using them only from trusted sources, auditing bundled scripts, and being wary of skills that fetch external URLs. In Claude Code, a project skill's allowed-tools setting applies even in a claude -p run in a folder you have never trusted, so review those first. A February 2026 Snyk scan of 3,984 skills from the ClawHub and skills.sh registries reported 13.4 percent with a critical-level issue and 76 confirmed malicious. Snyk sells scanners and the sample was public registries, so treat it as a vendor figure.
• MCP: tool descriptions go to the model, but interfaces often show users a summary, so hidden instructions can ride along. Invariant Labs named this tool poisoning on 1 April 2025, including a "rug pull" where a server changes a description after you approve it. The specification says there should always be a human able to deny tool calls, and that clients must treat tool annotations as untrusted unless they come from a trusted server.

Real enforcement lives elsewhere: permissions, sandboxes and hooks. If a rule must never be broken, put it there.

A worked example

This is an illustration, not a real repository. The server names are placeholders.

The workflow: fix a bug from an error alert, open a reviewed pull request, update the ticket.

• AGENTS.md holds about 40 lines: the test and lint commands, TypeScript strict mode, never edit generated/, the pull request title format. The generated/ rule is also a permission or a hook, because the file alone cannot enforce it.
• A bugfix-pr skill holds the numbered procedure: reproduce, write a failing test, fix, open the pull request. It bundles a PR template and a script that runs only the affected tests. A separate release-notes skill is set to user-only because it publishes.
• MCP servers for the error tracker, GitHub and the ticket system handle live data and writes. Write tools sit behind approval.

The sequence: the session starts with AGENTS.md and the skill list in context. You paste an alert link. The model matches bugfix-pr and loads its body. It calls the error tracker through MCP. The steps in between use the shell and repository files under the AGENTS.md rules. You approve the pull request, and the ticket gets updated. Always-on cost is the instruction file and the skill list. On-demand cost is the skill body. Per-call cost is the tool results.

What I did not check

Only Claude Code documents re-attaching a skill's body after context compaction. I did not verify whether Codex or Cursor do the same, or whether they honour Claude-specific skill settings such as user-only invocation. I also did not find a first-party per-server MCP token cost, so I am not quoting one.

Further reading

• agents.md: the format and its stewardship.
• Agent Skills specification and Anthropic's announcement.
• Claude Code documentation: skills, memory and MCP.
• Codex documentation: AGENTS.md and skills.
• Cursor documentation: rules and skills.
• MCP specification, 2026-07-28 server features and security best practices.
• Anthropic, Code execution with MCP, 4 November 2025.
• Vivek Trivedy, The Anatomy of an Agent Harness, LangChain, 10 March 2026.
• Vercel, AGENTS.md outperforms skills in our agent evals, 27 January 2026.
• Gloaguen et al., arXiv 2602.11988, February 2026.
• Invariant Labs, MCP security notification: tool poisoning attacks, 1 April 2025.
• Snyk, ToxicSkills, 5 February 2026.