Where you put an instruction decides when the agent sees it and what it costs every turn. Here is a practical map for AGENTS.md / CLAUDE.md, skills, Cursor rules, and MCP.

Originally published on clogmeter.vercel.app.

Put always-on facts in AGENTS.md / CLAUDE.md, put procedures in skills, and put tools in MCP — not instructions. That is a cost decision, not a style preference.

What each layer actually loads

Place When it costs tokens Best for
Root AGENTS.md / CLAUDE.md Session start; stays for the whole session Build/test commands, layout, hard constraints the agent needs on every task
Path-scoped rules / nested instruction files When matching files are in context API-only or package-only conventions
Skills (SKILL.md) Name + description always; body only when triggered Deploy checklists, review playbooks, multi-step procedures
MCP servers Tool names / schemas (and often server instructions) while the server is connected Capabilities the agent must call — databases, browsers, APIs — not prose rules

Anthropic's Claude Code steering guide makes the same split: root CLAUDE.md is high context cost, skills load the body on demand, and hooks enforce "never" rules outside markdown. Cursor's rules docs mirror it with alwaysApply, globs, and description-based rules.

A simple decision rule

  1. Would you ask a new teammate to memorise this before their first PR? If yes, it can live in the root instruction file. If no, move it.
  2. Is it a procedure ("when releasing, do these 8 steps")? Put it in a skill so the body loads only when that work starts.
  3. Is it a capability ("query Postgres", "open a PR")? That is MCP (or a built-in tool), not an instruction file. Do not paste API docs into AGENTS.md to fake a tool.
  4. Must it never fail? Markdown is advisory. Use a hook, linter, or CI check for true guardrails.
  5. Does it only apply under `src/api/?** Prefer a path-scoped Cursor rule or nested CLAUDE.md` over stuffing the root file.

Where people usually go wrong

  • Procedures in the root file. A 30-line release checklist in AGENTS.md taxes every chat, including ones that never ship.
  • Instructions stuffed into MCP. MCP is for tools. Long server instructions and eager schemas are a silent token tax every turn the server stays connected.
  • Everything set to always-on. Cursor alwaysApply: true and unscoped Claude rules behave like root CLAUDE.md: paid whether relevant or not.
  • The same rule in three places. A "never commit secrets" line in AGENTS.md, a skill, and an MCP blurb wastes tokens and invites contradictions.

Rules that should "almost always" apply but are not worth a permanent tax belong in a skill with a tight description, or a Cursor rule with a clear description / globs — not in the root file "just in case."

How to migrate without guessing

  1. Paste your root AGENTS.md / CLAUDE.md and always-on Cursor rules into Clogmeter.
  2. Cut anything the agent can discover by reading the repo (long architecture essays, pasted READMEs).
  3. Move multi-step workflows into skills; leave only pointers in the root file.
  4. Audit connected MCP servers: disable ones you are not using this session, and keep schemas lean.
  5. Re-weigh. The always-on budget should shrink; skill bodies and MCP stay available when needed.

If you want to see where your own AGENTS.md, CLAUDE.md or Cursor rules spend tokens, I built a free browser-only checker that also flags duplicates and always/never conflicts: Clogmeter.