AGENTS.md, skills or MCP: where should agent instructions go?

Where you put an instruction decides when the agent sees it and what it costs every turn. Here is a...

title: "AGENTS.md, skills or MCP: where should agent instructions go?" published: true tags: ai, claude, cursor, productivity canonical_url: https://clogmeter.vercel.app/guides/agents-md-skills-or-mcp

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

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.