Context is a budget

Verified against Claude Code 2.1.263, Codex CLI 0.153.4

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 files in those folders. Path-scoped rules in .claude/rules/ load when matching files are open.

Skills follow the spec: name and description stay in a listing, the body waits. That listing has a budget of about 1% of the model context window. If you overflow it, low-use descriptions get trimmed and the skill stops matching.

MCP servers add their tool lists to the same prompt. A chatty MCP is 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 ~/.codex/AGENTS.md (or AGENTS.override.md if that file exists), then walks from the project root to your cwd and concatenates one instruction file per directory. Closer files appear later. I did not find a /cost or skill-doctor equivalent on the Codex pages I opened, so I do not claim one.

If the combined instruction text is large, you feel it as ignored rules, not as a meter. 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 skill context cost. The control is 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, MCP tool lists.
  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