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 practical map for AGENTS.md / CLAUDE.md, skills, Cursor rules, and MCP. Originally published on clogmeter.vercel.app.
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
- 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.
- Is it a procedure ("when releasing, do these 8 steps")? Put it in a skill so the body loads only when that work starts.
-
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.mdto fake a tool. - Must it never fail? Markdown is advisory. Use a hook, linter, or CI check for true guardrails.
-
Does it only apply under `src/api/
?** Prefer a path-scoped Cursor rule or nestedCLAUDE.md` over stuffing the root file.
Where people usually go wrong
-
Procedures in the root file. A 30-line release checklist in
AGENTS.mdtaxes 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: trueand unscoped Claude rules behave like rootCLAUDE.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
- Paste your root
AGENTS.md/CLAUDE.mdand always-on Cursor rules into Clogmeter. - Cut anything the agent can discover by reading the repo (long architecture essays, pasted READMEs).
- Move multi-step workflows into skills; leave only pointers in the root file.
- Audit connected MCP servers: disable ones you are not using this session, and keep schemas lean.
- 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.
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.