🧠 What Are Markdown (.md) Files in Claude? How to Create and Use Them

TL;DR — Too Long Didn’t Read

• .md files are plain text files written in Markdown format. Many LLM-based tools can read Markdown files when those files are included as context. In Claude’s ecosystem, certain .md files can be loaded automatically or used as working context at the start of a session.

• The most important one is CLAUDE.md — a special file Claude automatically picks up and treats as standing instructions.

• For Cowork users, context .md files like about-me.md, voice-and-style.md, and memory.md serve the same purpose: giving Claude persistent knowledge about who you are and how you work.

• These files don't require coding knowledge to create. They're plain text with some simple formatting.

• Keep each file under 200 lines. Specific, concrete instructions work significantly better than vague preferences.

• The files compound over time. The more you refine them, the less re-explaining you do and the better Claude's output becomes.

1. What Is a .md File and How Does Claude Use Them?

.md stands for Markdown, a lightweight plain-text format used across the web for notes, documentation, READMEs, and structured instructions. It is not specific to Claude. Many LLM tools can work with Markdown files because they are easy for both humans and models to read.

What makes .md files relevant in Claude is not the format itself, but how Claude products use them. In Claude Code and related workflows, certain Markdown files can be loaded as context at the start of a session so Claude begins with instructions, project information, or personal working preferences already available.

Think of it this way: every new Claude session starts with a blank slate.In many LLM workflows, Markdown files are a practical way to provide reusable context. In Claude, that often takes the form of CLAUDE.md or other context files. They're the written equivalent of onboarding a colleague — but one you only have to do once.

This applies across Claude's tools:

• In Claude Code, the file is called CLAUDE.md and it holds project instructions, coding standards, and workflow rules

• In Claude Cowork, context files like about-me.md and voice-and-style.md hold personal and professional context

• In both, the files load at session start and shape every interaction that follows

You don't need to be a developer to create or use them. They're plain text files. Any text editor — including Notepad on Windows or TextEdit on Mac — can create them.

2. What Is CLAUDE.md and How Does It Work?

CLAUDE.md is a specific file that Claude Code (and Claude Code-powered tools) automatically detects and reads at the start of every session. It is the primary way to give Claude persistent, project-level context without repeating yourself in every conversation.

How CLAUDE.md Loads Into Claude's Context

When you open a Claude Code or Cowork session, Claude walks up the directory tree from wherever you're working and loads every CLAUDE.md file it finds. It also picks up CLAUDE.md files in subdirectories when it reads files in those locations. The contents go into Claude's context window — effectively becoming part of the starting conversation before you've typed anything.

This means Claude enters every session already knowing what's in your CLAUDE.md. If your file says "always use 2-space indentation" or "our API handlers live in src/api/handlers/", Claude knows that before you say a word.

Where Can You Put a CLAUDE.md File?

CLAUDE.md files can live in three different scopes, each with a different reach:

More specific locations take precedence over broader ones. If your project CLAUDE.md says one thing and your personal CLAUDE.md says something different about the same behavior, the project-level instruction wins.

What Does CLAUDE.md Actually Do?

The contents become part of Claude's context for every session in that scope. Claude treats them as instructions — not enforced rules, but clear guidance that shapes its behavior. The more specific and concrete your instructions, the more consistently Claude follows them.

3. What Are Context .md Files in Claude Cowork?

Claude Cowork doesn't use CLAUDE.md by default the same way Claude Code does — but the principle is identical. You create plain .md files in your working folder, and Claude reads them as context when you give it access to that folder.

Cowork is an autonomous task-execution mode — not a better chat. (If you're still figuring out how Claude works at a system level, this guide explains what "computer access" actually means.)

The difference is that these files are oriented around you and how you work, not a software project. Three files cover most of what you need:

about-me.md

This file tells Claude who you are. It covers your role, your organization, your responsibilities, who your audience is, and what good work looks like in your context.

A useful about-me.md doesn't read like a LinkedIn bio. It reads like what you'd tell a new assistant on their first day. Example content:

I'm a content strategist at a B2B SaaS company that sells project management software to enterprise teams.
My main output is long-form content: guides, case studies, and newsletters.
My audience is senior ops and project leads at companies with 200-1000 employees.
I care about precision and clarity over length. I don't use jargon unless it's standard in enterprise software.
My primary tools: Notion for drafts, HubSpot for publishing, Slack for team communication.

voice-and-style.md

This file tells Claude how you communicate — and how you want Claude to communicate on your behalf. It covers tone, formatting preferences, phrases to use or avoid, and sentence style.

Tone: Conversational but professional. Direct. No filler phrases.
Sentence style: Short to medium length. Active voice. Cut adverbs.
Avoid: "Exciting", "innovative", "game-changing", "leverage" as a verb
Structure: Use headers for anything over 400 words. Lead with the point, not the setup.
Examples I like: [link to an example article or paste a paragraph you've written]

memory.md

This file tracks ongoing context that Claude needs across sessions but can't infer from your other files. It's the evolving record of your work: active projects, decisions already made, things in progress, context that would otherwise reset every session.

Current projects:
- Q2 content calendar (deadline: April 15)
- Redesigning onboarding email sequence
- Research for enterprise buyer personas (interviews scheduled in March)

Decisions already made:
- Dropped the monthly webinar series (low attendance)
- Using Canva for all visual assets (not the in-house designer)

Tools I'm working with this month: HubSpot, Notion, Clay

Update memory.md regularly — either yourself after sessions, or by asking Claude to update it before you close a session.

4. How Do You Create a .md File?

Step 1: Choose a Text Editor

You don't need special software. Any of these work:

• Mac: TextEdit (set to plain text mode) or VS Code (free)

• Windows: Notepad or VS Code (free)

• Any platform: Obsidian, Typora, or any Markdown editor

If you use VS Code, it will also preview how the Markdown renders, which is helpful when you're learning the format.

Step 2: Write Your Content in Plain Text

Markdown uses simple symbols for formatting. You only need a handful:

# This is a heading
## This is a subheading

- This is a bullet point
- Another bullet point

**This text is bold**

This is a regular paragraph.

You don't have to use any formatting if you don't want to — plain paragraphs work fine. The formatting just helps Claude scan the structure, the same way it helps human readers.

Step 3: Save the File With a .md Extension

When saving, name the file with .md at the end:

• CLAUDE.md

• about-me.md

• voice-and-style.md

• memory.md

Make sure your text editor saves it as plain text, not as a .docx or .rtf. In TextEdit on Mac, go to Format > Make Plain Text before saving.

Step 4: Put the File in the Right Place

For CLAUDE.md (Claude Code / Cowork):

• Place it in the root of your project folder, or in a .claude/ subfolder within it

• For personal context across all projects: save it to ~/.claude/CLAUDE.md (your home folder, in a folder called .claude)

For Cowork context files:

• Create a dedicated folder (e.g., _context or Claude Context) inside whichever folder you grant Cowork access to

• Place your about-me.md, voice-and-style.md, and memory.md files inside it

• When you start a Cowork session, Claude reads the contents of the folder it has access to

Step 5: For Claude Code — Use /init to Generate a Starting CLAUDE.md

If you're using Claude Code on a project, type /init in a session. Claude analyzes your codebase and generates a starting CLAUDE.md with build commands, test instructions, and project conventions it discovers. Treat this as a first draft and refine from there.

5. What Should You Put in Markdown Context Files for Claude?

The rule: include what Claude would get wrong without the file.

Claude already knows how to write, code, research, and structure content. You don't need to teach it those things. What it doesn't know is your specific context — your preferences, your constraints, your audience, and your project's particular decisions.

For CLAUDE.md (Project or Developer Context)

Include:

• Build and test commands: npm run build, pytest tests/, the exact commands your project uses

• Project structure: which folders hold what, especially anything non-obvious

• Coding standards: specific to your project, not general best practices Claude already knows (e.g., "we use snake_case for database columns but camelCase everywhere else")

• Architectural decisions and the reasoning: why certain choices were made, so Claude doesn't suggest reversing them

• Common workflows: how you handle PRs, deployments, migrations

• What to avoid: patterns the team has explicitly rejected and why

Don't include:

• API keys, credentials, or passwords (never)

• Things your linter or formatter handles automatically

• General coding advice Claude already knows

• Historical context that isn't relevant to current work

For Cowork Context Files (Non-Developer Context)

Include in about-me.md:

• Role, organization, industry

• What you're responsible for producing

• Who your audience is

• What "good output" looks like for your work

Include in voice-and-style.md:

• Tone (formal, conversational, technical, plain)

• Sentence style preferences

• Words and phrases to avoid

• Formatting preferences (headers, bullets, length)

• Examples of writing you like, if possible

Include in memory.md:

• Active projects with deadlines

• Decisions already made you don't want revisited

• Context specific to what you're working on right now

• Tools and platforms you're using this period

6. How Does Claude's Memory System Work Across .md Files?

In Claude workflows, these Markdown files are not memory in the human sense. Claude reads them as reusable context, typically at the start of a session or when the relevant files are brought into scope.

This is important because it means:

1. Your files are always current. If you update a .md file, Claude picks up the new version next session. Nothing is cached.

2. The order of loading matters. Claude reads files in a hierarchy — organization-wide instructions load first, then personal instructions, then project-level. More specific instructions override broader ones for the same behavior.

3. File size affects reliability. Files under 200 lines produce better adherence. Longer files consume more context budget, which can cause Claude to skip or underweight instructions later in the file.

4. Auto memory works alongside manual files. In Claude Code (v2.1.59+), there's also an auto memory system. Claude writes its own notes about your project — build commands it discovered, debugging patterns it recognized, preferences it observed — and stores them in ~/.claude/projects/[project]/memory/. The first 200 lines of this MEMORY.md file load at session start. You can view, edit, or delete these notes anytime by running /memory in a Claude Code session.

5. You can import files into other files. In CLAUDE.md, you can reference other files using @path/to/file syntax. This lets you keep the main file short while pulling in detailed content when needed. For example:

See @README for project overview.
Coding standards: @docs/standards.md
Git workflow: @docs/git-workflow.md

7. Best Practices for Writing Effective .md Files

Write Instructions That Are Specific Enough to Verify

Vague instructions get inconsistent results. Concrete instructions get consistent ones.

Keep Each File Under 200 Lines

Every line in a .md file consumes space in Claude's context window. Longer files don't just cost tokens — they reduce how reliably Claude follows instructions further down the file.

If you find yourself with a very long file, split it:

• Move detailed instructions into separate files and import them with @path/to/file

• Use the .claude/rules/ directory structure for project instructions (one file per topic: testing.md, api-design.md, code-style.md)

Use Structure to Make Instructions Scannable

Claude reads structured content more reliably than dense paragraphs. Use headers and bullet points to group related instructions.

markdown

## Output Formatting
- Use H2 headers for main sections
- No headers for responses under 200 words
- Always lead with the conclusion, not the setup

## Tone
- Conversational but precise
- No filler phrases like "It's worth noting that..."
- Active voice throughout

Don't Include What Claude Already Knows

You don't need to explain what a good paragraph structure looks like, what RESTful APIs are, or how to format a professional email. Claude knows these things. Your files should only cover what's specific to you, your project, or your organization.

Review and Update Your Files Regularly

These files drift. Projects evolve, your preferences shift, and context that mattered in January may be irrelevant in April. A monthly pass through your context files takes 10 minutes and keeps Claude's understanding current. Look for:

• Instructions that are now outdated

• Contradictions between files (if two instructions conflict, Claude may pick one arbitrarily)

• Things you keep correcting in sessions that aren't in any file yet

Never Put Sensitive Information in .md Files

CLAUDE.md and context files are plain text. Do not include API keys, passwords, credentials, or database connection strings. These files may be committed to version control, synced, or shared — and they're not encrypted.

8. Common Mistakes and How to Fix Them

• Saving the file in the wrong format. .md files need to be saved as plain text. If you use Microsoft Word or Google Docs and export as text, the formatting may include invisible characters. Fix: use a plain text editor. VS Code is free and reliable.

• Putting the file in the wrong location. If Claude isn't picking up your CLAUDE.md, it's usually a location issue. In Claude Code, run /memory to see which files are currently loaded. If yours isn't listed, it's not being found. Check the path against the scope table above.

• Writing instructions that are too vague. "Be concise" produces different results depending on the context. "Keep responses under 150 words unless I ask for more" does not. Rewrite vague instructions with a concrete, verifiable standard.

• Making the file too long. If your CLAUDE.md is 400+ lines, Claude may inconsistently follow instructions near the end. Split into smaller files using imports or .claude/rules/.

• Treating the file as a one-time setup. The file that works well on day one may not work as well in month three when your project has changed. Build a habit of updating context files after any major project shift or when you notice Claude making recurring mistakes.

• Including contradictory instructions. If your personal ~/.claude/CLAUDE.md says "always use tabs" and your project CLAUDE.md says "always use spaces," Claude may pick arbitrarily. Periodically review all your files together and remove conflicts.

• Relying on .md files for sensitive enforcement. CLAUDE.md files are context, not enforced rules. Claude reads them and tries to follow them, but they're not a hard constraint. For behaviors you need enforced reliably (like blocking certain file operations), use Claude Code's settings and permissions system, not a CLAUDE.md instruction.

FAQs

• Do I need to be a developer to create .md files for Claude? No. You're creating plain text files with some simple formatting. If you can write a bullet list in any app, you can write a .md file. The only technical step is saving the file with a .md extension instead of .txt.

• What's the difference between CLAUDE.md and other .md context files? .md is just the standard file extension for Markdown, and Markdown files can be used with many different LLM tools and workflows. CLAUDE.md is Claude’s specific convention: a specially named Markdown file that Claude Code automatically detects and loads as standing project context. Other files such as about-me.md or voice-and-style.md are ordinary Markdown files whose usefulness comes from their contents and where they’re placed, not from any special filename behavior.

• Can I have multiple CLAUDE.md files? Yes. Claude loads CLAUDE.md files from multiple locations — your home folder, your project folder, and subdirectories — and merges them. More specific locations override broader ones for the same instruction. This lets you have personal preferences that apply everywhere, plus project-specific instructions on top.

• What is auto memory and is it the same as a CLAUDE.md file? Auto memory is a separate system (available in Claude Code v2.1.59+) where Claude writes its own notes about your project. It's stored in ~/.claude/projects/[project]/memory/MEMORY.md. You write CLAUDE.md; Claude writes auto memory. Both load at session start and work together. You can view and edit auto memory files anytime by running /memory.

• Does updating a .md file take effect immediately? The next session. Claude reads the file fresh at the start of each session, so any update you make will be reflected the next time you open a new Claude Code or Cowork session. It doesn't update mid-session.

• Will Claude follow everything in my CLAUDE.md file? Claude reads the file and tries to follow the instructions, but they're context rather than enforced configuration. Vague or conflicting instructions produce inconsistent results. Specific, concrete instructions get followed reliably. If Claude isn't following something, rewrite the instruction to be more verifiable.

• Can I use a .md file in Claude Chat (browser)? Claude Chat projects have their own knowledge base where you can upload files, including .md files. This isn't the same as the automatic loading that happens in Claude Code and Cowork — you upload the files manually and they become part of the project's context. The principle is the same; the mechanism is different.

• How do I import one .md file into another? In CLAUDE.md, use @path/to/file syntax. For example: @docs/api-standards.md. Claude expands the import and loads the referenced file into context alongside your main file. You can import up to five levels deep.

• What happens to my CLAUDE.md files when Claude runs /compact to compress the conversation? CLAUDE.md files survive compaction. After /compact, Claude re-reads your CLAUDE.md from disk and re-injects it fresh. If an instruction seemed to disappear after compaction, it was given in conversation only — not in the CLAUDE.md file. Add it to the file to make it persist.