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.
"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.
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
markdown
# 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.
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:
yaml
---name:code-reviewversion:1.0.0description:>-
Structured code review for TypeScript/Node.js PRs. Covers type safety,
architecture, security, and test coverage.
triggers:-codereview-reviewthisPR-reviewthediff-PRfeedbackauthor:YashThakker---
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
markdown
---
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:
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
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:
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:
text
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:
What you have
Where it goes
Coding style guide
CLAUDE.md
"Never use any"
CLAUDE.md
Commit message format
CLAUDE.md
20-step deploy procedure
SKILL.md
PR review checklist
SKILL.md
Onboarding guide for a service
SKILL.md
Live database schema
MCP (Postgres)
Current open GitHub PRs
MCP (GitHub)
Slack channel history
MCP (Slack)
File tree of a large monorepo
MCP (filesystem)
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:
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.
