CLAUDE.md vs SKILL.md vs MCP: The Modern Agent Stack Explained

Most developers discover CLAUDE.md, drop all their context into it, and call it a day. Then, six weeks later, the file is 800 lines long, the agent seems inconsistent, and prompts that used to work start misfiring.

The problem is not CLAUDE.md. The problem is treating it as the only layer in a system that has three.

Claude Code (and the broader Claude agent ecosystem) is built around a layered context architecture: always-on rules, on-demand skills, and live connectors. Each layer has a distinct job. When you use all three correctly, your agent gets sharper context, faster responses, and a configuration that is actually maintainable.

This guide walks through each layer in depth — what it is, what belongs there, what does not, and how the three fit together into a production agent stack.

The Three-Layer Stack at a Glance

Before diving in, here is the mental model:

Each layer answers a different question:

• "What should the agent always know about this project?" — Layer 1
• "What should the agent know about this specific task?" — Layer 2
• "What does the agent need to access right now?" — Layer 3

Layer 1: CLAUDE.md and AGENTS.md — Always-On Rules

What it is

CLAUDE.md is a markdown file that Claude Code reads at the start of every session. It is the equivalent of a system prompt scoped to your project. Anything in this file is always in context — you do not have to ask for it, and the agent cannot ignore it.

AGENTS.md is a functionally identical format used by some other agent runtimes (OpenAI's Codex CLI, for example). If you see both terms, they do the same job under different names. Claude Code reads CLAUDE.md; if you are building for multiple runtimes, you may maintain both files.

There are two scope levels:

• Project-level: CLAUDE.md at the root of your repository applies to that project only.
• Global-level: ~/.claude/CLAUDE.md applies to every Claude Code session across all projects.

Most teams put personal preferences (writing style, preferred language, formatting habits) in the global file, and project-specific rules (architecture decisions, framework choices, forbidden patterns) in the project-level file.

What belongs in CLAUDE.md

Think of CLAUDE.md as the things you would tell a new senior engineer on day one — the stuff that is not in the README but that everyone on the team knows.

Good candidates:

• Coding conventions — naming patterns, import ordering, preferred patterns
• Project structure — where things live, what the main entry points are
• Non-obvious constraints — "we do not use class components," "all database queries go through the service layer"
• Personas — "respond as a principal engineer reviewing for correctness and maintainability"
• Commit and PR standards — branch naming, commit message format
• Security rules — "never log PII," "never expose API keys in code"

What does not belong in CLAUDE.md

This is where most teams go wrong:

• Long tutorials — If you are writing a 50-step guide on how to deploy, that belongs in a SKILL.md (see Layer 2)
• Step-by-step task instructions — "When the developer asks you to review a PR, first do X, then do Y..." That is a skill, not a rule
• Tool configurations — Database connection strings, API endpoints, and external service configs belong in MCP (see Layer 3), not pasted as static text into CLAUDE.md
• Everything — If CLAUDE.md is your only layer, it will grow without bound and eventually hurt more than it helps

Example CLAUDE.md

# Project: Acme API

## Stack
- Runtime: Node.js 22, TypeScript 5.4 (strict mode, no `any`)
- Framework: Fastify 5
- Database: PostgreSQL 16, accessed only through `src/db/` service layer
- Testing: Vitest; all new code requires tests

## Conventions
- File names: kebab-case for files, PascalCase for components and classes
- Imports: absolute paths from `src/`, never relative `../../`
- Error handling: always use the custom `AppError` class from `src/errors/`
- Logging: `src/logger/` only — never `console.log` in production code

## Hard rules
- Never commit `.env` files or secrets
- Never use `DELETE` in database migrations — use soft deletes
- All endpoints must have Zod input validation before business logic

## PR reviews
When asked to review code:
1. Check for type safety violations first
2. Flag any direct database calls outside `src/db/`
3. Check test coverage for changed files
4. Suggest improvements, do not rewrite everything

## Writing style
- Comments should explain *why*, not *what*
- Prefer explicit over clever

Notice what is in there: conventions, hard rules, a short review checklist. Notice what is missing: a 40-step deploy guide (that is a skill), Postgres connection config (that is MCP).

Layer 2: SKILL.md — On-Demand Expertise

What it is

A SKILL.md is a markdown file that defines a specific capability the agent can load on demand. Unlike CLAUDE.md, it is not always in context. The agent loads it only when a trigger — a keyword, a task type, or an explicit invocation — matches.

This is the progressive disclosure principle applied to agent context. You do not flood the agent's context window with deploy instructions when the developer is just writing a function. The skill is there when needed, invisible when it is not.

Skills live in .claude/skills/ in your project, or in ~/.claude/skills/ globally. Each skill is a directory containing at minimum a SKILL.md file, and optionally supporting files: templates, reference docs, example outputs.

.claude/skills/
├── code-review/
│   ├── SKILL.md
│   └── checklists/
│       └── security.md
├── deploy/
│   ├── SKILL.md
│   └── templates/
│       └── rollback-checklist.md
└── database-migration/
    └── SKILL.md

What belongs in SKILL.md

Skills are for task-specific, step-by-step expertise. Good candidates:

• A code review workflow with specific checklists
• A deployment procedure with environment-specific steps
• A debugging guide for a specific class of errors (flaky tests, memory leaks)
• Onboarding steps for a new service your team owns
• A content writing guide for blog posts or documentation

The key test: would a developer only need this when doing a specific, named task? If yes, it is a skill.

Skill frontmatter

Every SKILL.md starts with YAML frontmatter that tells the agent what the skill is, when to load it, and how to use it:

---
name: code-review
version: 1.0.0
description: >-
  Structured code review for TypeScript/Node.js PRs. Covers type safety,
  architecture, security, and test coverage.
triggers:
  - code review
  - review this PR
  - review the diff
  - PR feedback
author: Yash Thakker
---

The triggers array is the key field. When the developer's message contains any of these phrases, the agent knows to load this skill's context before responding.

Full example: a code-review skill

---
name: code-review
version: 1.0.0
description: >-
  Structured PR review for TypeScript/Node.js. Produces a prioritized
  findings list with severity labels.
triggers:
  - code review
  - review this PR
  - review the diff
  - review these changes
---

# Code Review Skill

## Review order

Always review in this sequence:

1. **Correctness** — Does the code do what it claims? Are there logic errors?
2. **Type safety** — No `any`, no unchecked nulls, no unsafe casts
3. **Architecture** — Does it follow the layered structure in CLAUDE.md?
4. **Security** — Input validation, secret exposure, SQL injection vectors
5. **Tests** — Are changed code paths covered? Are tests meaningful?
6. **Style** — Only flag style issues that affect readability, not preference

## Output format

Produce a findings list grouped by severity:

### Critical (must fix before merge)
- [file:line] Description of issue

### Important (should fix)
- [file:line] Description of issue

### Suggestion (nice to have)
- [file:line] Description of issue

If there are no findings in a category, omit it.

## Tone
Direct and specific. Point to the line. Explain the risk. Suggest the fix.
Do not soften critical issues with excessive praise.

Installing community skills

You do not have to write every skill from scratch. The explainx.ai skills registry and the broader community publish ready-to-use skills you can install with one command:

npx skills install code-review
npx skills install deploy-vercel
npx skills install database-migration

The CLI downloads the skill directory into .claude/skills/ and Claude Code picks it up immediately. No restart required.

For more on the skills registry and how to publish your own, see the companion guide on npx skills install.

Layer 3: MCP — Live Connections to Tools and Data

What it is

MCP (Model Context Protocol) is an open protocol that lets Claude connect to external tools and data sources at runtime. Instead of pasting a database schema into CLAUDE.md (static, stale, expensive), you connect Claude to Postgres and it queries the schema live. Instead of copying a GitHub PR into chat, you connect Claude to GitHub and it fetches the PR diff itself.

MCP servers run as local processes or remote services. Claude Code acts as an MCP client, calling tools exposed by these servers during a session.

What belongs in MCP

MCP is the right choice whenever Claude needs:

• Live data — current database state, real-time API responses, file system access
• External tool access — GitHub, Slack, Linear, Notion, browser automation
• Action execution — running shell commands, writing files, triggering deploys
• Search — querying a vector database, searching internal docs, web search

If you are currently pasting things like database dumps, API responses, or file trees into your chat to give Claude context, those are MCP opportunities. You are spending context window tokens on data that could be fetched directly.

Key difference from CLAUDE.md

CLAUDE.md gives Claude knowledge — static facts that are true about your project.

MCP gives Claude access — the ability to retrieve current data and take actions.

A CLAUDE.md might say: "Our main database is PostgreSQL, running on AWS RDS, with tables for users, orders, and products."

An MCP connection to Postgres lets Claude run SELECT * FROM information_schema.tables and see the actual current schema, including columns you added last week that CLAUDE.md does not mention yet.

Configuration

For Claude Code, MCP servers are configured in .claude/settings.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${POSTGRES_CONNECTION_STRING}"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

For Cursor, the equivalent is the mcp_servers block in your Cursor settings JSON.

Note the ${ENV_VAR} syntax — secrets are pulled from environment variables, not hardcoded. Never put connection strings or API keys directly in settings.json.

Example: connecting to Postgres

After configuring the MCP server above, Claude can:

Developer: What tables do we have in the public schema, and which ones have
           a `deleted_at` column?

Claude: [Calls postgres MCP tool: query information_schema]

        Tables in the public schema:
        - users (has deleted_at: yes)
        - orders (has deleted_at: yes)
        - products (has deleted_at: no)
        - sessions (has deleted_at: no)
        - audit_log (has deleted_at: no)

No copy-paste. No stale schema in CLAUDE.md. Live data, correct answer.

The Decision Framework: Which Layer for What?

When you are deciding where something belongs, work through these questions in order:

1. Should this be true in every session, regardless of what the developer is working on?

Yes → CLAUDE.md

No → continue

2. Is this step-by-step expertise for a specific named task?

Yes → SKILL.md

No → continue

3. Does Claude need live data or does it need to take action in an external system?

Yes → MCP

No → It probably does not need to be in the agent stack at all. Good documentation in the repo is still the right place for some things.

A quick reference:

Building the Stack for a Real Team

When you move from a personal setup to a shared team configuration, a few practices keep things maintainable:

Commit CLAUDE.md and the skills directory to the repo. They are project configuration — treat them like code. Code review changes to CLAUDE.md the same way you would review changes to a linter config. These files shape every interaction your team has with the agent.

Use environment variables for all MCP secrets. Your .claude/settings.json can be committed safely as long as secrets are referenced as environment variables. Set the actual values in .env.local (gitignored) or in your team's secrets manager.

Lock skill versions. If you use npx skills install, pin to a specific version:

npx skills install [email protected]

This prevents community skill updates from silently changing agent behavior in production workflows.

Global vs project split. Establish a team norm: the global ~/.claude/CLAUDE.md is for personal preferences (writing style, language), the project CLAUDE.md is for project rules. This prevents one person's global config from leaking into code reviews or PRs.

Document your MCP topology. Add a short section to your project README listing which MCP servers are expected and how to set them up locally. New team members should not have to reverse-engineer .claude/settings.json.

Common Mistakes

Putting tool configs in CLAUDE.md

This is the most common mistake. CLAUDE.md is loaded into the context window every session. Pasting a database connection string, a list of API endpoints, or a Slack webhook URL into CLAUDE.md wastes tokens and leaks implementation details into every conversation. Use MCP for live tool access; use environment variables for secrets.

Writing SKILL.md like a CLAUDE.md

Skills that are too broad never trigger cleanly. A skill called "general-backend-development" with 600 lines of instructions is not a skill — it is a second CLAUDE.md. Skills should be narrow, named, and triggered by specific task phrases. If you cannot write three clear trigger phrases for a skill, it probably belongs in CLAUDE.md instead.

Skipping MCP and pasting database dumps into context

It is tempting to just paste your schema, your API docs, or your file tree into chat when you need Claude to have context. This works once. At scale, it wastes context window tokens, the data gets stale, and you end up with a fragile workflow that breaks whenever something changes upstream. Set up the MCP connection once and let Claude query fresh data on every session.

Not separating global from project config

A common early mistake is putting everything in the global CLAUDE.md because it is convenient. Then you join a new project and the agent is still following rules from your previous job. Keep project-specific rules in the project. Keep personal preferences global.

What Comes Next

If you have been operating with only CLAUDE.md, the clearest first step is to audit what is in it. Pull out anything that is task-specific (a skill) or anything that is trying to describe live data (an MCP candidate). What remains — the always-true rules and conventions — is what actually belongs there.

Then build your first skill. Pick the task you ask Claude to help with most often. Write a SKILL.md with a clear name, two or three trigger phrases, and a concrete step-by-step guide. Run it for a week and see how much tighter the responses get.

Then wire up one MCP connection. Start with whatever data source you paste into chat most often — usually a database schema or a GitHub repo. Once you have seen the difference between static context and live access, you will not go back.

If you want to build this stack properly in a structured setting — with hands-on time building a real skill library and wiring up live MCP integrations — the AI Skills & MCP workshop at explainx.ai runs September 12–13, 2026 as two live two-hour sessions. It covers rules (CLAUDE.md), skills (SKILL.md), and live connections (MCP) for developers and technical builders using Claude Code and Cursor. You leave with a working production skill library and two MCP integrations configured.

There is also a related option — the AI Skills workshop — running the same dates with a slightly different focus if skills are your primary interest.

The agent stack is not complicated once you have the mental model. Each layer has a job. Use the right layer for the right job, and the whole system gets faster, more accurate, and much easier to maintain.

Frequently Asked Questions

Can I have multiple CLAUDE.md files in a project?

Claude Code supports CLAUDE.md at multiple directory levels — the project root, subdirectories, even individual package directories in a monorepo. Files are merged at session start. This is useful for monorepos where different packages have different conventions: shared rules go in the root CLAUDE.md, package-specific rules go in the package directory.

What happens when CLAUDE.md and a SKILL.md conflict?

CLAUDE.md rules take precedence as baseline constraints. A skill can extend or add specificity to those rules for a particular task, but it cannot override hard constraints set in CLAUDE.md. If your CLAUDE.md says "never use any" and a skill's example code includes any, the agent should flag it.

How large can SKILL.md files get?

There is no hard limit, but practical degradation starts around 4,000–5,000 tokens per skill file. If a skill is getting very large, it is usually a sign that it covers too many distinct tasks. Split it into multiple focused skills with clear trigger phrases.

Do MCP connections cost extra?

MCP itself is a protocol, not a paid service. The cost depends on the MCP server you connect to — most open-source servers (filesystem, Postgres, GitHub) are free to run locally. Some commercial MCP providers charge for access to their services. The Claude API cost depends on how many tokens the MCP tool responses add to context.