Claude Skills vs. MCP Servers: How to Give a Coding Agent Repository Context

Coding agents now have three separate mechanisms for loading project context, and teams keep reaching for the wrong one. CLAUDE.md and AGENTS.md hold always-on instructions. MCP servers expose live tools and data. Skills - the newest of the three - package a procedure the agent loads only when a task calls for it. They overlap enough to be confusing and differ enough that picking wrong costs you either a bloated context window or a stale answer.

This is a decision guide: what each mechanism actually is, what it is good at, and how to choose between a Skill and an MCP server when both look like they would work.

The three mechanisms, briefly#

Instruction files (CLAUDE.md, AGENTS.md). Plain Markdown at the repo root, loaded into context on every session. Best for the handful of facts that are true for every task: how to install, how to test, what the agent must never do. We cover writing these in How to Write the Perfect CLAUDE.md File for Claude Code and AGENTS.md Explained. The cost model is simple: every line you add is a line the agent carries through every conversation, relevant or not.

MCP servers. A running process that exposes tools, resources, and prompts to the agent over the Model Context Protocol. The agent calls a tool at runtime and gets back a fresh result - a database schema, a search hit, the current contents of a ticket. MCP is the only one of the three that can reach data that changes independently of your repository, and the only one that can take actions against external systems. Setup and trust review are real: a server is code you run, with a network surface and permissions, which is why MCP security is worth reading before you connect one.

Skills. A folder containing a SKILL.md file with a short YAML header (name, description) and a body of instructions, optionally bundled with scripts and reference files. The agent reads only the one-line description of every available Skill by default. When a task matches, it pulls the full SKILL.md into context - and only then. This "progressive disclosure" is the whole point: you can ship fifty detailed procedures and pay for none of them until one is actually needed.

Skill or MCP server? The question that actually comes up#

Instruction files are easy to place - they are for the small set of universal facts, full stop. The real decision is between a Skill and an MCP server, because both can carry a lot of detail the agent loads on demand.

The dividing line is static versus live.

A Skill is files in your repository. It can contain long procedures, decision trees, and executable scripts, but everything in it is fixed at the moment you commit it. It cannot look up the current state of anything. If the facts in a Skill change, someone has to edit the Skill.

An MCP server runs code at call time. It can query a live database, hit an API, search across repositories, read a value that was written five seconds ago. It can also write - open a pull request, file an issue, post a message. Nothing static can do that.

So:

• The context is a repeatable procedure with steps and maybe a script, and the facts rarely change - Skill. Examples: your release checklist, your "how we write a migration" runbook, a code-review rubric, the steps to regenerate a client SDK.
• The context is live data or an action against another system - MCP server. Examples: "what is the current schema of the orders table," "search every repo in the org for this pattern," "what conventions does this file fall under right now," "open a PR with this change."
• The context is a universal fact every task needs - instruction file, not either of these.

flowchart TD
  Start["Agent needs this context"] --> Universal{"True for every task in the repo?"}
  Universal -->|Yes| Instr["CLAUDE.md / AGENTS.md"]
  Universal -->|No| Live{"Does it need live data or an external action?"}
  Live -->|Yes| MCP["MCP server"]
  Live -->|No| Repeat{"A repeatable procedure or reference?"}
  Repeat -->|Yes| Skill["Skill"]
  Repeat -->|No| Inline["Just put it in the prompt"]

Side by side#

Where each one breaks down#

An instruction file that keeps growing stops being read carefully. Agents weight a 400-line CLAUDE.md unevenly, the same way a person skims the middle of a long page. If you are adding a fourth procedure to it, that content wants to be a Skill.

A Skill that encodes facts goes stale silently. "The payments service owns refund logic" is true until a refactor moves it, and the Skill will keep saying it with total confidence. Skills are for procedures - stable sequences of steps - not for facts about the current codebase.

An MCP server used for static reference is wasted overhead. If the information never changes, you are running a process and spending tool-definition tokens to serve something a committed file would serve for free. Reserve MCP for what genuinely has to be live. Our MCP documentation server guide goes deeper on when that tradeoff pays off, and 8 MCP Documentation Servers covers ready-made options.

They compose#

This is not a single-choice question per repo. A well-set-up project uses all three:

• AGENTS.md with the build command, the test command, and three hard boundaries.
• A Skill called cut-a-release with the exact sequence, plus a script it runs.
• An MCP server for the things that have to be current: the live database schema, cross-repo search, and - the case we care about - which conventions and docs apply to the file the agent is about to edit.

That last one is exactly why a Skill is the wrong container for repository conventions. "How this codebase names things, structures modules, and handles errors" is a fact set that drifts with every merge. Checked into a Skill, it is correct the day you write it and wrong a month later - the documentation drift problem, moved into a new file.

Moxie Docs serves that layer as an MCP server instead: moxie.get_conventions, moxie.get_doc_impact, and moxie.search_docs return what is true about the connected repository now, regenerated as the code changes, and its Cleanup PRs keep the human-readable docs in sync the same way. The Skill tells the agent how to do a task; the MCP server tells it what is currently true about your code. Point a coding agent at both.

See how the MCP context works on your own repository on the free plan - one repo, no card required.