Every .md file Claude Code reads, and what each one is for

Why markdown files?

Claude Code has no complicated settings screen for how it should work. You write instructions in ordinary .md (markdown) files, the same simple text format used for README files, and Claude reads them. Because they are text, you can commit them to git, review changes and share them with your team.

The files fall into two groups:

• Loaded at the start: instructions Claude always has, such as CLAUDE.md.
• Loaded when needed: skills, subagents and folder-specific rules, which only take up room when they are used.

Most files can live in two places: in the project (for example .claude/, shared with everyone through git) or in your home folder under ~/.claude/ (only you, in every project).

CLAUDE.md and CLAUDE.local.md: standing instructions

• CLAUDE.md in the project root (or .claude/CLAUDE.md): your team's instructions, such as how to build, test and name things. Commit it.
• ~/.claude/CLAUDE.md: your personal preferences for every project.
• CLAUDE.local.md in the project root: your personal notes for this project only. Add it to .gitignore so it is not shared.
• CLAUDE.md in a subfolder: loads the first time Claude works on a file in that folder. Handy for a frontend/ or api/ with its own rules.

Claude combines these files rather than replacing one with another. You can pull another file in with @path/to/file, for example @docs/style-guide.md.

# Build and test
- Run npm test before committing
- Use 2-space indentation
- Never edit files in /generated

Keep each one short: Anthropic suggests under 200 lines. Run /init to create one, /memory to edit it, and remember that Claude treats it as guidance, not enforced rules. For things that must always happen, use hooks or permission rules.

Rules, auto memory and AGENTS.md

.claude/rules/*.md lets you split instructions into small files, such as testing.md and api.md. A rule file with no settings loads at the start like CLAUDE.md. Add a paths line and it only loads when Claude works on matching files:

---
paths:
  - "src/api/**/*.ts"
---
- All API endpoints must validate their input

Auto memory is notes Claude writes for itself as it learns about your project, kept in ~/.claude/projects/<project>/memory/ with a MEMORY.md index. It stays on your machine and is not committed. Saying "remember that we use pnpm" goes here; saying "add this to CLAUDE.md" puts it in the shared file instead. You can review or turn it off with /memory.

AGENTS.md is the file some other AI coding tools use. Recent versions of Claude Code read it when a project has no CLAUDE.md. If you have both, put @AGENTS.md inside CLAUDE.md so Claude reads it too.

Skills, commands, subagents and output styles

• Skills: .claude/skills/<name>/SKILL.md (or ~/.claude/skills/). A recipe for a repeatable job. Only its short description is loaded until it is used, either when you type /name or when Claude decides it fits. Keep each under about 500 lines.
• Custom commands: .claude/commands/<name>.md is the older format and still works, but commands have been merged into skills, so use skills for anything new.
• Subagents: .claude/agents/<name>.md (or ~/.claude/agents/). A specialist helper with its own instructions and tools, running in its own context. It needs a name and a description at the top.
• Output styles: .claude/output-styles/<name>.md. Changes how Claude writes its replies. Built-in styles include Explanatory and Learning; switch with /output-style.

---
name: code-reviewer
description: Reviews code for quality. Use after big changes.
tools: Read, Glob, Grep
---
You are a careful code reviewer. List issues by severity.

Which file should I use?

• A fact or rule everyone should follow: CLAUDE.md.
• A personal preference for one project: CLAUDE.local.md.
• Rules that only apply to some folders: .claude/rules/ with paths.
• A job you repeat: a skill.
• A specialist that does a whole task and reports back: a subagent.
• A different tone or format for replies: an output style.

To see what Claude has loaded in a session, run /context.

Check yourself

Three quick questions to check it stuck.

Ask the tutor

Frequently asked