CLAUDE.md, SKILL.md and MCP: Which Layer Holds Which Instructions

New users of Claude Code and similar coding agents tend to repeat one mistake during the first month. They open CLAUDE.md and keep typing: style guides, deployment steps, review checklists, raw database schemas, until the file runs to 600 or 900 lines. The assumption is that more context up front makes the agent smarter.

It does the opposite. Working memory gets crowded, answers become less accurate, and prompts that used to behave stop working. Something feels off and it is hard to say what. On every simple request the model first has to wade through hundreds of lines of irrelevant instructions before it reaches a single line of code. The model is not at fault, and neither is the prompt. A single text file was simply asked to do three different jobs.

Modern coding agents do best when instructions are split into three clean layers: project rules that are always on, task skills loaded on demand, and live tool connections through MCP. With those layers kept apart, the model receives only what it needs, at the moment it needs it.

Why three layers

It is fair to ask why three and not one big file, or ten small specialized ones. Each layer addresses a different problem, and the problems overlap less than expected.

• CLAUDE.md handles things that must always be true.
• SKILL.md handles things that matter only sometimes.
• MCP handles data that goes stale the moment it is written down.

These are three distinct failure modes and not three flavors of one. Fold skills into CLAUDE.md and the result is one bloated file loaded in full every session, whether or not a deployment checklist is needed. Any further layer turns out to be a subdivision of one of the three and not a new job.

What belongs in CLAUDE.md or AGENTS.md

Picture CLAUDE.md as a note left for an engineer on day one. It is not the full onboarding document, just the few unwritten things everybody on the team already knows, such as no class components here, or never touch the database directly and go through the service layer.

The file sits in the project root, and Claude Code reads it automatically at the start of each session. Nobody calls it or asks for it. It is simply present, the way a person's memory of team conventions is present when they sit down to code.

Good candidates are coding conventions, project structure, hard constraints, security rules such as never exposing API keys in code, and the persona the agent should adopt while reviewing work.

Poor candidates are a 40-step deployment guide, a database schema, and anything relevant only one day in ten. That second group is where most people go wrong. If something is not true in every session, it probably does not belong there. A CLAUDE.md that tries to be everything ends up as a slow, bloated version of nothing.

A global version also exists at ~/.claude/CLAUDE.md and applies across every project. People usually keep personal habits there, such as preferred commit message style or the language for replies, and leave project-specific rules in the project file.

A file that does its job looks like the following, adapted from a widely shared set of behavioral guidelines.

# CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

## 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

## 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

## 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

---

**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

It is short and specific, and nothing in it needs revising next week. Here is what it looks like when it has gone wrong, a pattern common in early versions.

# Project Notes

Our database has these tables: users, orders, products, sessions,

audit_log (schema pasted below, 340 lines)...

To deploy, first SSH into staging, then run these 47 commands...

Here's our Slack webhook URL for notifications: hooks.slack.com/...

When reviewing PRs, check for: [12 paragraphs of instructions]

Every item in that second example is wrong for CLAUDE.md, each for a different reason. A schema is out of date once anyone adds a column. Deployment steps describe one named task. A webhook URL is a secret and should live in an environment variable, not in committed markdown. The PR review instructions are a skill wearing CLAUDE.md's clothes.

A handy test: would this line still be true if read again in three months, on a random Tuesday, while doing something unrelated? If not, it does not belong in the file.

SKILL.md: expertise that appears only when needed

Agent Skills came from Anthropic in October 2025, designed so that instructions for a particular task could sit in a folder and be loaded when needed instead of occupying context all the time. In December 2025 the format was opened up as an independent standard, and other tools adopted it quickly. VS Code, Cursor, Google's Antigravity IDE, Gemini CLI, Goose and several other coding agents now support the same SKILL.md format that Claude Code uses. It is the same playbook that turned MCP into the industry-wide standard for tool connections.

The idea is useful once it clicks: not all knowledge needs to sit in the agent's head all the time. Most of what an engineer knows becomes relevant only for a particular task. Nobody recalls the deployment checklist while writing a helper function. Skills follow that logic. A folder holding a SKILL.md waits unused until a request such as review this PR comes in, and at that point Claude pulls in the actual review checklist.

A skill file begins with a short description, called frontmatter, stating what the skill does and when it should trigger. When a message matches, Claude loads the rest. When it does not, none of that content occupies any space in the conversation. That is why skills feel lighter than stuffing everything into CLAUDE.md. A skill for pull request reviews, another for database migrations and another for release notes do not compete for room unless that exact task is underway.

.claude/skills/
├── code-review/
│   └── SKILL.md
├── pr-description/
│   └── SKILL.md
└── anti-sycophancy/
    └── SKILL.md

Project-level skills live in .claude/skills/ inside the repository. Personal skills that should follow a user everywhere live in ~/.claude/skills/. The split mirrors CLAUDE.md: project versus global. A real one, trimmed:

---
name: production-code-validation-checklist
description: "Run this checklist before pushing code to GitHub"
---

# Production Code Validation Checklist

**Run this checklist before pushing code to GitHub.**

This is not optional. This is how you prevent broken repositories.

## Secrets Audit
- [ ] Searched for: password, secret, token, key, api_key, credential
- [ ] All secrets are in environment variables or .env, not in code
- [ ] .env file is in .gitignore

## Failure Scenario Testing: Deliberately Break It
This is the most important step. Production code breaks. Can your code
handle it?
- [ ] Run without a required environment variable, does it fail with a
      clear error?
- [ ] Simulate a timeout on any HTTP request, does the code handle it?
- [ ] Feed it empty input, null input, and malformed input, one at a time

## Final Production Readiness Assessment
Choose ONE:
- [ ] PROTOTYPE: concept proven, not production ready
- [ ] DEVELOPMENT READY: works for development, not production
- [ ] PRODUCTION CANDIDATE: ready for real-world testing
- [ ] PRODUCTION VERIFIED: tested in a real environment, known to work

**If you cannot check a box, you are not done.**

Notice what it avoids. It does not also hold coding conventions or a database schema. It has one named job, triggered by one kind of moment, and that is what makes it a skill and not a smaller CLAUDE.md. The plain test is whether something is only needed while doing one specific, named job. If so, it is a skill and not a rule.

MCP: access, not just knowledge

CLAUDE.md and SKILL.md are both markdown files that somebody wrote. MCP is different. It links Claude, as it runs, to a resource outside the chat, whether a database, GitHub, Slack, the file system or anything else that has been connected.

For a RAG-heavy project, connecting Chroma directly is a typical case. The official chroma-mcp server exposes collections as tools that Claude can query.

{
  "mcpServers": {
    "chroma": {
      "command": "uvx",
      "args": [
        "chroma-mcp",
        "--client-type", "persistent",
        "--data-dir", "/path/to/your/chroma/data"
      ]
    }
  }
}

Inside Claude Code, setup is a single command with no manual JSON editing.

claude mcp add --scope project chroma \
  -- uvx chroma-mcp --client-type persistent --data-dir ./chroma-data

It registers the server and writes the configuration to .mcp.json in the project, which can be committed so the whole team gets the same connection without configuring it by hand. Claude Code offers three scopes: local, meaning one user on one machine; project, meaning checked into the repository and shared; and user, meaning every project a person touches. The same project-versus-global pattern appears a third time, which makes it easy to remember once noticed.

The protocol has grown quickly enough that the growth is part of the story. The official server registry lists well over 9,000 servers, and monthly downloads of the reference SDK rose from roughly 2 million to nearly 100 million in about 16 months, according to figures Anthropic has shared. That is no longer a niche feature. Anyone still pasting a schema or a GitHub PR into a prompt is doing by hand what an MCP connection does live, and the pasted copy goes stale as soon as anything changes upstream.

A decision tree

1. Should this be true in every session, whatever the task? If yes, put it in CLAUDE.md. If not, continue.
2. Is it a specific, named, repeatable task with its own steps? If yes, make it a SKILL.md. If not, continue.
3. Does Claude need current data, or need to act somewhere outside the conversation? If yes, use MCP. If not, it may not belong in the agent's setup at all. Some things are better left as documentation that nobody asks an AI to memorize.

A naming trap

Anyone switching between tools will be caught by this at some point. Claude Code and Cursor read CLAUDE.md, while Codex CLI and a few other runtimes read AGENTS.md, which serves the same purpose under a different name. Google's Antigravity, built by the former Windsurf team after Google's deal with them in mid-2025, also uses its own AGENTS.md convention. Yet all of them, Claude Code, Cursor, Codex and Antigravity, read the same SKILL.md format for skills. So the rules layer splits by tool, but the skills layer stays uniform. That matters before assuming that a skill written for one agent has to be rewritten for another.

The habit that fixes it

Before adding a paragraph to CLAUDE.md, ask which of the three buckets it belongs in. A lot of the material crammed into CLAUDE.md is really a skill that never received its own folder. The habit is context engineering by a different label: choose what the agent sees and at what moment, in place of pouring everything into whichever file was opened first and hoping the model sorts it out. Open a CLAUDE.md and count how many paragraphs are really skills wearing the wrong file extension. The number is usually higher than expected.