Context is a budget

Verified against Claude Code 2.1.311, Codex CLI 0.164.0, Cursor 3.27 · Updated

I treat context like money. Every always-on file spends it. Every unused skill description spends it. A 400-line instruction file does not make the agent smarter. It makes the next rule easier to miss.

This page is the entry point. When you finish it, write the lean file in Your AGENTS.md is too long.

What loads on every turn

The pattern is the same across tools. Metadata stays in the prompt. Bodies and reference files load when the agent decides they matter.

The Agent Skills spec names three tiers:

  1. Metadata (name and description), loaded at startup for every installed skill. About 100 tokens each.
  2. Instructions, the SKILL.md body, loaded when the skill activates. Keep this under 5000 tokens. The spec also says keep the file under 500 lines.
  3. Resources in scripts/, references/, and assets/, loaded only when the skill points at them.

Instruction files and rules sit above that. They are not progressive. If the tool marks them always-on, you pay for every line on every turn.

In Claude Code

Claude Code loads CLAUDE.md (and CLAUDE.local.md) at session start. Nested CLAUDE.md files under the working directory wait until Claude reads, writes, or edits a file in those folders. Path-scoped rules in .claude/rules/ load when Claude reads, writes, or edits a matching file. Since 2.1.309, an on-demand file over its per-file limit loads only its start. On a 200K window that limit is 40,000 characters. On a 1M window it is 200,000 characters for Claude Opus 4.6 and Claude Sonnet 4.6, and 150,000 characters for later models.

Skills follow the spec: name and description stay in a listing, the body waits. That listing has a budget of 1% of the model context window. If you overflow it, Claude Code drops descriptions for the skills you use least, and those skills stop matching.

MCP tool search is on by default, so the prompt gets tool names and server instructions. Full definitions load when Claude searches for a tool. A chatty MCP is still an always-on tax.

Measure it:

  • /usage (alias /cost) shows session tokens and an estimated dollar figure. On Pro, Max, Team, and Enterprise it also breaks usage down by skill, subagent, plugin, and MCP server.
  • /skill-doctor shipped in 2.1.261. It shows which loaded skills go unused and what they cost in context.
  • /context lists what is in the window, including memory files.

I run /skill-doctor after I install a pile of skills. If a skill never fires, I hide it or delete it. I do not leave it “just in case.”

In Codex

Codex reads the first non-empty file in ~/.codex, AGENTS.override.md before AGENTS.md. It then walks from the project root to your cwd and takes one non-empty file per directory, in that same order. Closer files appear later. It stops adding files once the combined text reaches project_doc_max_bytes (32 KiB by default). I did not find a /cost or skill-doctor equivalent on the Codex pages I opened, so I do not claim one.

Past that cap, the rest of the instructions never load. /status shows token usage and remaining context capacity, not the byte cap or a per-skill cost. Keep AGENTS.md short and put depth in files the agent can open on demand.

In Cursor

Cursor always includes AGENTS.md. Project rules in .cursor/rules/*.mdc load when alwaysApply is true, when globs match a file in context, or when the agent picks a description. Skills in .cursor/skills/ and .agents/skills/ list metadata at startup and load the body when relevant.

I did not find a Cursor command that prints per-skill context cost. Click the context ring next to the prompt and the breakdown lists a Skills total for the descriptions in the window. The control is still the frontmatter. alwaysApply: true is a recurring bill. globs and skills are cheaper because they stay out of the prompt until they match.

How I measure

  1. Open the tool’s context view if it has one (/context in Claude Code).
  2. List always-on files: instruction files, always-apply rules, skill descriptions, and the MCP names and server instructions that stay in the prompt.
  3. Cut anything that is not a rule you would enforce this week.
  4. Move procedures into skills. Move architecture into docs/ and link it.

The budget is not “how much the model can hold.” It is “how much still gets followed.” Five rules the agent hits beat fifty rules it skims.

When the always-on file is under about 100 lines, go write the AGENTS.md.

Sources