Every Claude Code project has a file that shapes how the agent behaves. That file is CLAUDE.md. It sits at the root of your project and acts as a persistent instruction set that Claude Code reads at the start of every session. If you have ever wondered how some developers get Claude Code to follow specific coding standards, remember context between sessions, or run structured workflows without repeating themselves, this is how.

And if you have used agent skills, you have already interacted with CLAUDE.md whether you realized it or not. Skills install themselves into this file. Understanding how it works makes every skill you add more effective.

What CLAUDE.md actually does

When Claude Code starts a session in a project directory, it looks for a CLAUDE.md file. If it finds one, it loads the contents into the agent’s context before you type anything. Every instruction, constraint, and preference in that file applies to the entire session.

This is not a prompt template or a configuration schema. It is freeform markdown that Claude Code interprets as project-level instructions. You can put anything in it:

  • Coding conventions (“use single quotes, never semicolons”)
  • File structure rules (“tests go in __tests__/ next to the source file”)
  • Technology constraints (“use Bun, not npm”)
  • Workflow instructions (“run lint before committing”)
  • Security rules (“never write secrets to markdown files”)

Claude Code treats these instructions as persistent context. They survive session restarts, context compression, and tool calls. Unlike a system prompt you paste into a chat window, CLAUDE.md stays loaded automatically.

The file hierarchy

Claude Code actually checks multiple locations for instruction files, and they stack:

  1. ~/.claude/CLAUDE.md — Global instructions. Applies to every project on your machine.
  2. ./CLAUDE.md — Project root. The most common location. Applies to everything in this repo.
  3. ./.claude/CLAUDE.md — Project-scoped, tucked into the .claude/ directory. Same scope as the root file, cleaner file tree.

All three load if they exist. Global instructions apply first, then project instructions layer on top. If they conflict, the project-level file wins. Most developers use only the project root file. Power users add a global file for cross-project preferences like editor settings or commit message formats.

How skills plug into CLAUDE.md

When you install an agent skill, the installation process appends structured instructions to your CLAUDE.md file. A code review skill, for example, might add a block like this:

## Skill: Code Reviewer

Trigger: /review or "review this code"
Steps:
1. Read the current git diff
2. Check each changed file for bugs, security issues, and readability
3. Return a structured report with severity ratings
4. Suggest specific fixes for anything rated high severity

Claude Code reads this on session start, just like your own instructions. When you type /review, the agent matches the trigger and follows the steps. The skill is not a plugin with its own runtime. It is a set of instructions that the agent follows using the tools it already has: file reading, code execution, search, and editing.

This is why skills are lightweight. Installing one does not add dependencies, start background processes, or require API keys. It adds text to a file. The agent does the rest.

What makes a good CLAUDE.md

After working with hundreds of skill configurations and project setups, a few patterns stand out.

Be specific, not general. “Write good code” does nothing. “Use TypeScript strict mode, prefer const over let, and never use any as a type” gives the agent something to follow.

Use structure. Headers, bullet points, and numbered lists parse better than long paragraphs. Claude Code processes markdown natively, so lean into the format.

Separate concerns. Group instructions by topic: coding standards in one section, security rules in another, workflow steps in a third. When skills add their own sections, the file stays readable.

Keep it under control. A CLAUDE.md file that grows past a few hundred lines starts competing with your actual prompts for context space. If your instructions are that complex, split them into separate files and reference them. Some teams use a docs/agent/ directory for extended guidelines and keep CLAUDE.md as the index.

Do not duplicate skill instructions. If you install a security auditor skill that already knows how to check for OWASP Top 10 patterns, do not add your own OWASP checklist to the file. Let the skill handle it.

CLAUDE.md vs MCP servers

This distinction trips up a lot of developers. MCP servers give an agent new tools. A Postgres MCP server lets Claude Code query a database it otherwise could not access. A GitHub MCP server adds pull request management capabilities.

CLAUDE.md does not give the agent new tools. It tells the agent how to use the tools it already has. A skill installed via CLAUDE.md might instruct the agent to “read all .test.ts files and check for uncovered edge cases,” but the agent is using its built-in file reading and code analysis to do that work.

The two work together. A skill might reference an MCP server: “use the Postgres MCP server to query the users table and validate the schema against the migration files.” The skill provides the workflow. The MCP server provides the capability.

Common questions

Q: Can I have multiple CLAUDE.md files in subdirectories? A: Claude Code only loads from the three locations listed above (global, project root, and .claude/ directory). Subdirectory files are not picked up automatically. If you need different instructions for different parts of a monorepo, put conditional logic in the root file.

Q: Do skills modify CLAUDE.md permanently? A: Yes. Installing a skill appends to the file, and uninstalling removes the relevant section. The changes persist in your repo. If you use version control, you can see exactly what each skill added and revert if needed.

Q: What happens if CLAUDE.md gets too long? A: Claude Code loads the full file into context every session. A very long file reduces the context available for your actual work. Keep project instructions concise. Move detailed reference material to separate files that the agent can read on demand rather than loading automatically.

Q: Is CLAUDE.md specific to Claude Code? A: The CLAUDE.md convention started with Claude Code, but the pattern of agent-level instruction files is spreading. Other AI coding tools are adopting similar approaches. Skills that target multiple agents often include instructions for each agent’s configuration format. The AgentNDX skills directory lists compatible agents for every skill.