Context engineering for coding agents: AGENTS.md, skills, MCP or CLI?

Context engineering is deciding what a coding agent has in its context window, when it gets it and in what form. An agent never reads your repository; it reads a window that your tooling assembles from instruction files, tool definitions, skills and command output. Assemble that window badly and the agent works with a stale rule, a missing procedure, or 26,000 tokens of tool schemas and no room left for the code it was asked to change.

This article breaks the window into four layers, puts a rough token price on each, and works out when an MCP server is worth its cost and when a plain shell command is the better interface. It ends with a decision matrix you can apply to a new tool in five minutes, and a checklist for auditing a setup you already have.

What is context engineering?

Context engineering is the practice of curating the input a model works from. Anthropic's guide to context engineering for agents (September 2025) frames it as an attention budget rather than a token budget: what you put in front of the model competes for its attention, so relevance matters more than completeness. The same post recommends writing the smallest possible set of high-signal tokens for the smallest possible set of steps.

The word entered the mainstream faster than the practice did. Thoughtworks' Technology Radar put context engineering at Adopt in April 2026, which is a fair summary: the pattern is settled, the implementations are still inconsistent. The interesting engineering is not the prompting. It is deciding, per situation, which of four layers should be resident, which should be fetched on demand, and which should not be in the window at all.

Why long context degrades: context rot

Context rot is the observed loss of accuracy as input grows, and it is not a smooth curve. Chroma's Context Rot study (July 2025) ran 18 models over needle-in-a- haystack style tasks of growing input length and found performance falls off non-uniformly: some models degrade sharply partway through a long input, some hold up much longer, and the ranking of models changes with length.

Two practical consequences. A 1M-token window is a capacity number, not an accuracy number, and the middle of a long context is the worst place to put an instruction you need followed. And because the degradation is model-specific, "it fits" is not a reason: you have to test with the model you actually run.

The four layers, and what each one costs

Almost every agent setup I know is a variation on four layers, and the useful question is not which one to use but how much of each stays resident. The layers differ in when they are loaded, which is the whole game: a layer that is resident costs attention on every request, including the many requests where it is irrelevant.

AGENTS.md is the closest thing to a shared standard: an open file format that the Agentic AI Foundation stewards, used by more than 60,000 projects. Its value is that it is always loaded and always the same, so a rule in it cannot be forgotten by the runtime. Its cost is that it is charged on every turn, which is why it should hold rules and not knowledge.

Skills are the progressive-disclosure layer: a directory of small Markdown procedures where the agent first sees only a name and a description, and reads a file when the task calls for it. The specification caps the name at 64 characters and the description at 1,024, and the convention is to keep a SKILL.md under 500 lines. My own setup keeps about twenty of them in one master folder synced across three agents; the skills workflow post covers how that folder is structured.

MCP tools are the expensive layer

Tool definitions are pure overhead until a tool is called, and they are the layer where people add tools fastest. A measured comparison by Blocks.ai put the GitHub MCP server's 85 tools at 26,644 tokens and a 15-tool server at 3,185 tokens. Both numbers go into every request of that session, on every turn, including the turns where the agent is only reading a file.

Two approaches reduce that without deleting capability. Tool search, in Anthropic's advanced tool use work (November 2025), loads tool definitions on demand and cut token use by 85%, while accuracy rose from 49% to 74% on one model and from 79.5% to 88.1% on another. Code execution with MCP, from the same year, went the other way: instead of describing tools, give the model code that calls them, and the tool surface shrinks from about 150,000 tokens to 2,000, a 98.7% reduction.

The practical rule is the one the tool-design literature keeps arriving at: one capability per tool, and a name that says when to use it. A server that mirrors a REST API one-to-one gives the model 85 ways to do four things. The lessons from a 20-tool Jira server cover how I consolidated mine.

When to reach for a CLI instead of an MCP server

A shell command and an MCP tool can do the same job, and the interface you pick changes the context bill and the security surface. The CLI wins when the capability already exists as a command, when the agent needs to chain it with pipes, and when the result is large but filterable with flags. The MCP server wins when the agent would otherwise have to guess at the command syntax, and when credentials should live in one place instead of on every machine.

Credential custody is the reason MCP still wins in a lot of setups, including mine. My rule is that credentials come only from the environment: the agent never reads a credential file and never prints a token. An MCP server holds the token in its own process, so a tool call carries a short-lived capability instead of a path to a long-lived secret. A shell command can be just as safe if the environment is the only source, and less safe if the command is curl against a token the agent had to read first.

Compaction, notes files and sub-agents

The context window fills up in every long session, and the fix is not a bigger window. Three mechanisms handle it: compaction (summarizing the oldest turns), notes on disk, and sub-agents. All three trade resident tokens for indirection, and all three lose detail, so what you keep must be what you would not mind re-deriving.

Anthropic's context engineering post describes sub-agents as the tool for expensive searches: the sub-agent burns its own context on exploration and returns a summary of roughly 1,000 to 2,000 tokens instead of the raw pages. That is a good trade whenever the intermediate output is bulky and the conclusion is small. It is a bad trade for a task where the detail itself is the deliverable.

Notes files are the third mechanism and the most underrated. State that matters across sessions belongs in a file the agent writes and re-reads, not in a summary the runtime produced. The agent loop is the reason this matters: a long loop that keeps state in the window keeps paying for it on every iteration.

The decision matrix

Put the four layers side by side and the choice is mostly about load timing. Rules that must hold on every turn belong in AGENTS.md. Procedures that apply to a class of task belong in a skill, so their body is paid for only when used. Capabilities against a live system belong in an MCP tool when the agent would otherwise guess the interface. Everything else belongs in a shell command.

The trade-off to know about: every layer you add has a maintenance cost. Rules rot when they contradict the code. Skills rot when the procedure changes. Tool schemas rot when the API moves, and a stale tool description is worse than no tool, because the agent trusts it. Keep each layer small enough that you can read the whole thing when you review it, and prefer deleting a layer to growing it.

Context engineering checklist

1. Print your resident token count once per session: rules, skill metadata, tool schemas. You cannot manage what you have not measured.
2. Keep AGENTS.md to rules that hold on every turn, and move procedures into skills.
3. Give every skill a name and description that say when to use it, and keep the body under a few hundred lines.
4. Consolidate tools so that each one is a capability, not an endpoint; aim well under 20 tools per server.
5. Use tool search or code execution once a server's schema passes about 10,000 tokens.
6. Reach for the shell first when a documented command already does the job.
7. Pass credentials by environment only, never by a file the agent reads and never in a prompt.
8. Send bulky exploration to sub-agents and keep conclusions in the main context.
9. Persist state in notes files rather than in summaries that the runtime will compact away.
10. Re-read the rules on every change to the build. A rule that contradicts the code teaches the agent to ignore rules.

If you are setting this up for a team, the skills post covers the file layout and the tool-design post covers the tool side; the AI engineering page covers how it fits into a delivery process.

Sources

1. Anthropic: Effective context engineering for AI agents (Sep 2025)
2. Chroma: Context Rot (Jul 2025)
3. AGENTS.md: the open format for agent instructions
4. Agent Skills specification
5. Anthropic: Advanced tool use, tool search and programmatic tool calling (Nov 2025)
6. Blocks.ai: MCP vs CLI, the context window cost
7. Thoughtworks Technology Radar: Context engineering (Adopt, Apr 2026)