AGENTS.md, skills or MCP: where should agent instructions go?
Put always-on facts in AGENTS.md / CLAUDE.md, put procedures in skills, and put tools in MCP —
not instructions. Where you park a line decides whether you pay for it on every turn or only when it is relevant.
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.mdover 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.
Quick check
Count the always-on files with the AGENTS.md / CLAUDE.md token counter or the Cursor rules token counter. Related reading: SKILL.md token cost and CLAUDE.md vs AGENTS.md vs Cursor rules.
Open Clogmeter and weigh your instruction files → Free, browser-only. Token counts, duplicates, conflicts, trimmed export — nothing uploaded.