> Context engineering decides what a coding agent has in context: rules in AGENTS.md, procedures in skills, and when an MCP tool beats a shell command. > > Web page: https://balazscsorba.com/blog/agents-md-skills-mcp-cli-decision-matrix · Language: English · Also available in: [Deutsch](https://balazscsorba.com/de/blog/agents-md-skills-mcp-cli-decision-matrix.md) · [Magyar](https://balazscsorba.com/hu/blog/agents-md-skills-mcp-cli-decision-matrix.md) > Author: Balázs Csorba · Published: 2026-06-19 · Updated: 2026-07-16 · Keywords: context engineering, AGENTS.md, agent skills, MCP vs CLI, context rot, agent context window, token budget for AI agents, when to use MCP instead of a CLI, sub-agents for AI agents [Blog](https://balazscsorba.com/blog)/[AI agents](https://balazscsorba.com/blog/category/agents) # Context engineering for coding agents: AGENTS.md, skills, MCP or CLI? Context engineering decides what a coding agent has in context: rules in AGENTS.md, procedures in skills, and when an MCP tool beats a shell command. [Balázs Csorba](https://balazscsorba.com/about)·June 19, 2026·updated July 16, 2026·8 min read - [Context engineering](https://balazscsorba.com/blog/tag/context-engineering) - AGENTS.md - Agent Skills - [MCP](https://balazscsorba.com/blog/tag/mcp) ![AGENTS.md, skills, MCP or CLI: a robot at a crossroads reads a signpost with four arrows: page, toolbox, plug and terminal.](https://balazscsorba.com/images/blog/agents-md-skills-mcp-cli-decision-matrix/cover.webp?v=b94159da0a) ## Key takeaways - Context engineering is an attention budget rather than a token budget: what you put in front of the model competes with the code it needs to read. - Four layers do the work: always-on rules in AGENTS.md, procedures in skills fetched on demand, resident MCP tool schemas, and the shell. - Tool definitions are the expensive layer: 85 GitHub MCP tools measured at 26,644 tokens against 3,185 for a 15-tool server. - Tool search cut token use by 85% and raised accuracy at the same time, and code execution with MCP took a 150,000-token tool surface down to about 2,000. - A capability that already exists as a documented command belongs behind the shell, and credentials should reach the agent through the environment only. On this page 1. [What is context engineering?](https://balazscsorba.com/#what-is-context-engineering) 2. [Why long context degrades: context rot](https://balazscsorba.com/#context-rot) 3. [The four layers, and what each one costs](https://balazscsorba.com/#the-four-layers) 4. [MCP tools are the expensive layer](https://balazscsorba.com/#mcp-tools-are-the-expensive-layer) 5. [When to reach for a CLI instead of an MCP server](https://balazscsorba.com/#when-to-reach-for-a-cli) 6. [Compaction, notes files and sub-agents](https://balazscsorba.com/#compaction-notes-and-sub-agents) 7. [The decision matrix](https://balazscsorba.com/#decision-matrix) 8. [Context engineering checklist](https://balazscsorba.com/#checklist) 9. [Sources](https://balazscsorba.com/#sources) Listen to this article 0:00 **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](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-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](https://www.trychroma.com/research/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. ![Stacked diagram of the four context layers of a coding agent: AGENTS.md, skills, MCP tools and the shell](https://balazscsorba.com/images/blog/agents-md-skills-mcp-cli-decision-matrix/diagram-8.webp?v=aaa6425737) The four layers: rules and tool definitions are always resident, skills are fetched on demand, and the shell is free until it is used. ## 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. Layer Holds Loaded Typical cost Instruction file (AGENTS.md) Rules that always apply: build commands, conventions, refusals Every request 200 to 1,000 tokens Skills Procedures for a specific task, each in its own file Metadata only, then the file About 100 tokens per skill, body on demand MCP tools Names, descriptions and JSON Schemas of every exposed tool Every request, per server 85 tools: 26,644 tokens; 15 tools: 3,185 Shell Everything already on the machine Only when a command runs Zero, until output arrives [AGENTS.md](https://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](https://agentskills.io/specification) 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](https://balazscsorba.com/blog/coding-agent-skills-workflow) 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](https://www.anthropic.com/engineering/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. **Measure in your own session** Token counts per tool vary with the model and the serializer. Print the token count of your own tool block once and write it down; the ranking matters more than the absolute number. ## 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. Situation Reach for Why The command already exists and is documented Shell Zero resident tokens, and pipes compose The agent would have to guess flags or output shape MCP tool The schema documents both The output is huge but has a filter Shell Filter server-side instead of in context A secret must be used by the agent MCP tool, or a shell command reading only the environment Neither needs the token in the window One server would need more than about 20 tools Shells first, tool search second Resident tokens grow linearly with tool count The task is a one-off investigation Shell A skill file would be permanent overhead for a rare case ## 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](https://balazscsorba.com/blog/agent-loop-explained) 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. ![Decision tree for choosing AGENTS.md, a skill, an MCP tool or the shell for a coding agent capability](https://balazscsorba.com/images/blog/agents-md-skills-mcp-cli-decision-matrix/diagram-29.webp?v=8ce3074883) Route each capability by when it needs to be in the window: always, on demand, or not at all. 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 [AI engineering](https://balazscsorba.com/expertise/ai-engineer) page covers how it fits into a delivery process. ## Sources 1. [Anthropic: Effective context engineering for AI agents (Sep 2025)](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) 2. [Chroma: Context Rot (Jul 2025)](https://www.trychroma.com/research/context-rot) 3. [AGENTS.md: the open format for agent instructions](https://agents.md/) 4. [Agent Skills specification](https://agentskills.io/specification) 5. [Anthropic: Advanced tool use, tool search and programmatic tool calling (Nov 2025)](https://www.anthropic.com/engineering/advanced-tool-use) 6. [Blocks.ai: MCP vs CLI, the context window cost](https://blocks.ai/blog/mcp-vs-cli-context-window-cost) 7. [Thoughtworks Technology Radar: Context engineering (Adopt, Apr 2026)](https://www.thoughtworks.com/radar/techniques/context-engineering) ## Frequently asked questions What is context engineering in coding agents? It is deciding what a model has in its context window, when that content loads and in what form. Anthropic frames it as an attention budget rather than a token budget, because the tokens you add compete for attention with the code the agent needs to read. In practice it means keeping always-on rules small, putting procedures in on-demand skills, and being deliberate about how many tool definitions stay resident. Should I use AGENTS.md or skills? Use AGENTS.md for rules that must hold on every turn, such as the build command, the conventions and the things the agent must refuse. Use skills for procedures that apply to a class of task, because a skill's body is read only when the task calls for it, at roughly 100 tokens of metadata. If a rule needs a paragraph of explanation, it is a skill pretending to be a rule. How much do MCP tools cost in context? Tool definitions are sent on every request of a session, so the cost scales with the number of tools. Blocks.ai measured the GitHub MCP server's 85 tools at 26,644 tokens and a 15-tool server at 3,185. Anthropic's tool search loads definitions on demand and cut token use by 85% while accuracy rose, and code execution with MCP reduced a 150,000-token tool surface to about 2,000. When is a CLI better than an MCP server? A shell command is better when the capability already exists as a documented command, when the agent needs to pipe the output, or when the output is large but has a filter, since filtering outside the model keeps the tokens out of the window. An MCP server is better when the agent would have to guess a command's flags or output shape, and when a credential should stay inside one process instead of being read from a file. How do I stop an agent's context from filling up? Three mechanisms: compaction summarizes the oldest turns, notes files persist state on disk across sessions, and sub-agents spend their own context on exploration and return a short summary, typically 1,000 to 2,000 tokens. All three lose detail, so keep what you would not mind re-deriving, and prefer a file the agent writes itself over a summary the runtime produced. Written by Balázs Csorba Senior fullstack & AI engineer in Styria, Austria – 10+ years of Vue, Nuxt, Node.js and PHP, now building tooling for AI agents. [AI engineering & MCP servers →](https://balazscsorba.com/expertise/ai-engineer)[About me →](https://balazscsorba.com/about) ## More articles - [Claude skills: how to write a SKILL.md that loads at the right moment](https://balazscsorba.com/blog/claude-skills-guide) - [Designing tools for AI agents: names, descriptions, schemas and error messages](https://balazscsorba.com/blog/agent-tool-design-descriptions-errors) - [Context rot in long-running agents: clearing, compaction, memory and sub-agents](https://balazscsorba.com/blog/context-rot-compaction-long-running-agents) - [Browser agents for E2E testing: let agents write Playwright tests, not run them](https://balazscsorba.com/blog/browser-agents-e2e-testing-playwright) ## Sounds like what you need? Tell me about your project or role – I’d love to hear from you. [Get in touch](mailto:contact@balazscsorba.com) [Connect on LinkedIn](https://www.linkedin.com/in/balazs-csorba)