# Claude Skills vs Projects vs MCP vs CLAUDE.md: Where Each Instruction Lives (2026) Source: https://lotsnotes.com/blog/claude-skills-vs-projects-vs-mcp-vs-claude-md Published: 2026-10-21T03:30:40.823009+00:00 `CLAUDE.md` holds the rules Claude Code reads at the start of every session. A skill is a `SKILL.md` folder Claude loads only when a task needs it, in chat, Claude Code and the API. A project gives chats in Claude shared knowledge and instructions. MCP isn't an instruction: it connects Claude to outside tools and data. People mix these up because all four end up "telling Claude something". They differ in where they live, when Claude reads them, and who else gets them. I work in Claude and Claude Code every day, and I read Anthropic's own docs and help center on 20 October 2026 to pin down what each does today. Everything below comes from those pages (links at the end). ## At a glance Checked on 20 October 2026 in the Claude Code docs, the Claude Help Center and the Claude API docs. | | `CLAUDE.md` | Skills | Projects | MCP | |---|---|---|---|---| | **What it holds** | Always-on rules and facts: build commands, conventions, "never do X" | A procedure or reference: instructions plus optional scripts and files | Background knowledge and instructions for one stream of work | A connection: tools and data from another service | | **Where it lives** | Files: `~/.claude/CLAUDE.md`, `./CLAUDE.md` or `./.claude/CLAUDE.md`, `CLAUDE.local.md`, a managed policy file | A folder with `SKILL.md`: `~/.claude/skills/`, `.claude/skills/`, a plugin, your Claude account, or the Skills API | Your Claude account | A server URL or local command, added as a connector or with `claude mcp add` | | **When Claude reads it** | Full content at session start, every session | Name and description at start; full content only when used | Every chat inside that project | Tool names at session start; full schemas when a tool is needed | | **Where it works** | Claude Code | Claude chat, Cowork, Claude Code, the Claude API | Claude chat (a new beta version starts in Claude Code) | Claude chat, Cowork, Claude Desktop, Claude Code | | **Shared with your team** | Commit the project file to the repository | Commit to `.claude/skills/`, share on Team and Enterprise, or publish to your organization | Team and Enterprise, with "Can view" or "Can edit" | Commit `.mcp.json`; on Team and Enterprise an owner adds the connector | | **Plans** | Any Claude Code user | Free, Pro, Max, Team and Enterprise, with code execution on | Every plan; Free is capped at five projects | Every plan; Free gets one custom connector | Short version: `CLAUDE.md` is what Claude should always know in a repo, a skill is what it should know how to do, a project is what it should know for one body of work in chat, and MCP is what it can reach. ## CLAUDE.md: always-on rules for Claude Code `CLAUDE.md` is a Markdown file Claude Code loads at the start of every session. Anthropic lists four places, loaded from broadest to most specific: - **Managed policy:** an organization-wide file IT deploys to each machine. - **User:** `~/.claude/CLAUDE.md`, your preferences for every project. - **Project:** `./CLAUDE.md` or `./.claude/CLAUDE.md`, shared with the team through source control. - **Local:** `./CLAUDE.local.md`, your own notes for one project, kept out of git. All levels add up; they don't replace each other. Files in subdirectories load when Claude works in them, and `@path` imports pull other files in (up to four hops deep). Anthropic's guidance is to keep each file under 200 lines, because the whole file costs context on every request, and to move anything that's a multi-step procedure or matters for only part of the codebase into a skill or a path-scoped rule in `.claude/rules/`. Two details people miss: - **It's context, not enforcement.** Anthropic says Claude treats `CLAUDE.md` as context, not enforced configuration. A rule that must hold every time belongs in a hook. - **Claude Code reads `AGENTS.md` too.** With an `AGENTS.md` and no `CLAUDE.md` in your working directory or above, Claude Code reads the `AGENTS.md`. With both, it reads only `CLAUDE.md` unless that file imports `AGENTS.md`. I went through the details in [AGENTS.md vs CLAUDE.md](https://lotsnotes.com/blog/agents-md-vs-claude-md). ## Skills: procedures Claude loads when it needs them A skill is a folder with a `SKILL.md` file: YAML frontmatter with a name and a description, then the instructions, plus any scripts, templates or reference files. Claude reads every skill's name and description up front, and loads the full content only when your task matches the description or you call it by name (`/deploy` in Claude Code). Bundled files cost nothing until Claude opens them. Where skills live depends on the surface: - **Claude Code:** personal skills in `~/.claude/skills//SKILL.md` (all your projects on that machine), project skills in `.claude/skills/` (commit them and the team gets them), and plugin skills. Custom slash commands have been merged into skills: a file in `.claude/commands/` still works, and a skill with the same name wins. - **Claude chat and Cowork:** Customize, Skills, then upload a ZIP of the skill folder. Anthropic's help center lists skills on Free, Pro, Max, Team and Enterprise, with code execution turned on. On Team and Enterprise you can share a skill with colleagues (they get a view-only copy that updates when you do), publish it to your organization's library, and owners can provision skills for everyone. - **Claude Code picks up your account's skills.** Skills enabled in your Claude account sync into Claude Code (v2.1.273 or later) when you sign in with that account. The sync is one-way, checks for changes about every 10 minutes, and doesn't run when Claude Code uses an API key or a cloud provider such as Amazon Bedrock. - **The other direction doesn't hold.** Personal skills in `~/.claude/skills/` don't load in Cowork or cloud sessions; those load the skills enabled for your Claude account, and cloud sessions also load project skills committed to the repository. - **Claude API:** upload through the Skills API (`/v1/skills`); custom skills there are shared across the API workspace and run in the code execution container. Skills uploaded to Claude chat aren't available on the API, and the reverse. Skills follow the Agent Skills open standard at agentskills.io, so the same folder format works in other tools that adopt it. ## Projects: knowledge and instructions for chats in Claude A project in Claude is a self-contained workspace with its own chats, **project knowledge** (documents, text and code you upload) and **project instructions** (tone, role, rules for that work). Every chat inside the project starts with them. - **Plans:** every plan, Free included, with Free capped at five projects. On Pro, Max, Team and Enterprise, when knowledge nears the context limit, Claude switches to retrieval (RAG) and can hold up to 10 times more. - **Sharing:** Team and Enterprise only, per person or with the whole organization, as "Can view" or "Can edit". - **Memory:** each project has its own memory, and Claude also brings in your account memory unless you turn off "Use account memory" on the project page. - **A new version is in beta.** Anthropic is rolling out projects as one conversation that Claude splits into parallel threads in the cloud, starting in Claude Code for some Pro and Max users. Each thread starts with the project's files, repositories, instructions and memory. Anthropic's own one-liner on the difference: projects provide static background knowledge that's always loaded in chats within them, while skills provide procedures that activate when needed and work everywhere across Claude. ## MCP: connections, not instructions The Model Context Protocol is an open standard Anthropic created for connecting AI apps to tools and data. An MCP server gives Claude tools (search this, create that) and the data behind them. It doesn't tell Claude how you want work done; that's what the other three are for. - **Claude chat, Cowork and Desktop:** remote servers are added as custom connectors on every plan; Free is limited to one custom connector. On Team plans only owners add a connector, then each member connects to it with their own sign-in. Anthropic notes the connection runs from its cloud, so the server must be reachable from the public internet. - **Claude Code:** `claude mcp add` in three scopes: local (this project, just you), project (a `.mcp.json` in the repository, shared through git), and user (all your projects). Connectors you added in your Claude account show up in Claude Code too, when you're signed in with that account. - **Context cost:** at session start Claude Code loads tool names and server instructions; full tool schemas wait until a tool is needed. Anthropic's own comparison: MCP connections give Claude access to tools, and skills teach Claude how to use those tools well. Their example pattern is MCP connecting your database and a skill documenting your schema and query patterns. ## Which one to use for which instruction | You want Claude to... | Put it in | |---|---| | Always use `pnpm`, run tests before committing, follow the folder layout | `CLAUDE.md` | | Follow your release checklist or brand-review steps when asked | A skill | | Answer every chat about one client or product from the same files | A project | | Read your database, CRM or notes app, or act in it | MCP | | Never edit `.env`, no matter what | A hook (Claude Code), not an instruction | | Apply your personal style in every chat | Custom instructions in your Claude settings | Anthropic's Claude Code docs give the same order of triggers: a mistake Claude makes twice goes into `CLAUDE.md`, a playbook you paste a third time becomes a skill, data you keep copying from a browser tab becomes an MCP server, and something that must happen every time becomes a hook. ## The other names you'll see - **Custom instructions:** account-wide, apply to all your conversations. Anthropic contrasts them with skills, which are task-specific and load only when relevant. - **Rules (`.claude/rules/`):** pieces of project instructions that load every session, or only when Claude works with matching files. - **Hooks:** scripts, HTTP calls or prompts that run at lifecycle events such as before a tool runs. They're the enforcement layer. - **Subagents:** isolated workers with their own context that return a summary; they can preload skills. - **Plugins:** the packaging layer. A plugin bundles skills, hooks, subagents and MCP servers into one install, with namespaced skills like `/my-plugin:review`. - **Output styles:** a role, tone and format for a whole Claude Code session. ## When the instructions need to reach more than Claude All four live inside Anthropic's products. If you also work in ChatGPT, Codex, Cursor or a cloud agent, the facts you wrote into a project or a `CLAUDE.md` stay behind. (I compared what ChatGPT and Claude each keep in [ChatGPT memory vs Claude Projects](https://lotsnotes.com/blog/chatgpt-memory-vs-claude-projects).) There are a few honest ways to share: - **A committed `AGENTS.md`.** Codex reads it, other coding agents follow the same convention, and Claude Code reads it when there's no `CLAUDE.md`. It only reaches agents working in that repository. - **Skills in the open format.** The same `SKILL.md` folder works in tools that adopt the Agent Skills standard, but you still copy the folder to each tool. - **An MCP server that holds your notes.** Every MCP client reads the same current copy, in any app. The third is what I built [LotsNotes](https://lotsnotes.com) for. Your business context (positioning, customers, voice, prices, decisions, each agent's playbook) lives once as notes in a workspace with folders. Claude, ChatGPT, Codex, Cursor and cloud agents read it over MCP or REST, and a note titled `AGENTS.md` holds the instructions agents read first. Private notes never reach agents, every save keeps a version, and you edit everything in the dashboard or from your agent. It's free for one person, and LotsNotes Pro is $99 once for teams, included with a Pro or Business plan of LotsSocial, LotsBlog, LotsTeam, LotsCRM, LotsInvoice, LotsBusiness or LotsStore ([pricing](https://lotsnotes.com/pricing)). It slots into the four Claude features rather than replacing them: - **MCP:** add `https://api.lotsnotes.com/mcp` as a connector in Claude, or `claude mcp add --transport http lots-notes https://api.lotsnotes.com/mcp` in Claude Code. Setup for each client is on the [connect page](https://lotsnotes.com/mcp). - **Skill:** our agent guide at [lotsnotes.com/skill.md](https://lotsnotes.com/skill.md) is written in the skill format (name and description frontmatter), so you can save it as `~/.claude/skills/lots-notes/SKILL.md` and Claude loads it when a task touches your notes. - **`CLAUDE.md` or project instructions:** one line, such as "For anything about the business, read the AGENTS.md note in LotsNotes, workspace Acme, folder Marketing, first." Code rules stay in `CLAUDE.md`, procedures in skills, and the business facts every agent needs in one place they can all read. For work in progress that has to pass between Claude Code, Codex and Cursor, the handoff note pattern is in [Claude Code Handoff](https://lotsnotes.com/blog/claude-code-handoff). ## FAQ ### What is the difference between Claude Skills and Projects? A project gives every chat inside it the same uploaded knowledge and instructions, and it lives in Claude chat. A skill is a folder of instructions and optional scripts that Claude loads only when a task calls for it, in chat, Cowork, Claude Code and the API. Anthropic puts it as static background knowledge versus procedures that activate when needed. ### Are Claude Skills the same as MCP? No. MCP connects Claude to external tools and data. A skill is procedural knowledge: how to do a task, which can include how to use an MCP server's tools well. Anthropic recommends using them together. ### Should I put instructions in CLAUDE.md or a skill? Put it in `CLAUDE.md` if Claude should always know it: build commands, conventions, project layout. Put it in a skill if it's reference material Claude needs sometimes or a workflow you trigger by name. Anthropic suggests keeping each `CLAUDE.md` under 200 lines and moving the rest into skills or `.claude/rules/`. ### Do skills I add in Claude work in Claude Code? Yes, from Claude Code v2.1.273 when you sign in with the same Claude account. The sync is one-way and checks for changes about every 10 minutes. It doesn't run when Claude Code uses an API key or a cloud provider such as Amazon Bedrock. ### Can my team share Claude Skills and Projects? Projects can be shared on Team and Enterprise with view or edit access. Skills can be shared with colleagues or published to the organization on Team and Enterprise, and in Claude Code a project skill committed to `.claude/skills/` reaches everyone who clones the repository. ### Are Claude Code slash commands the same as skills? Yes, they've been merged. A file at `.claude/commands/deploy.md` and a skill at `.claude/skills/deploy/SKILL.md` both create `/deploy`. Old command files keep working; skills add a folder for supporting files, frontmatter to control who invokes them, and automatic loading when relevant. ## Sources Checked on 20 October 2026: - Claude Code docs: [How Claude remembers your project](https://code.claude.com/docs/en/memory), [Extend Claude with skills](https://code.claude.com/docs/en/skills), [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp) and [Extend Claude Code](https://code.claude.com/docs/en/features-overview). - Claude Help Center: [What are skills?](https://support.claude.com/en/articles/12512176-what-are-skills), [Use skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude), [What are projects?](https://support.claude.com/en/articles/9517075-what-are-projects), [Get started with custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) and [Use Claude's chat search and memory](https://support.claude.com/en/articles/11817273-use-claude-s-chat-search-and-memory-to-build-on-previous-context). - Claude API docs: [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview). - LotsNotes: [pricing](https://lotsnotes.com/pricing), [connect page](https://lotsnotes.com/mcp) and [agent skill](https://lotsnotes.com/skill.md).