What Is an MD File? How to Open It and Why AI Tools Use It
What the .md format is, how to open and create one, and why AI coding agents read CLAUDE.md and AGENTS.md.

An MD file is a plain-text file written in Markdown, a lightweight markup language where # makes a heading and **two asterisks** make text bold. Any text editor opens it, and apps like GitHub, Obsidian and VS Code display it as formatted text.
MD files have also become how people hand context to AI tools: CLAUDE.md, AGENTS.md, the context.md you keep pasting into ChatGPT. Below: how to open one, what goes inside, and where the format stops working for AI.
What is an MD file?
An MD file is a Markdown file: plain text saved with the .md file extension (sometimes .markdown), whose content follows Markdown syntax. John Gruber created Markdown in 2004, with Aaron Swartz, so people could write for the web in something as readable as an email (Daring Fireball). Unlike HTML, the other markup language most people have seen, the raw file stays readable as is; a renderer turns the symbols into headings, lists, links and code blocks.
The core syntax fits in a few lines:
# Heading
## Smaller heading
**bold** and *italic*
- a bullet point
1. a numbered step
[a link](https://unabyss.com)
`inline code`
Gruber's original description left edge cases open, so two specs now pin the details down: CommonMark and GitHub Flavored Markdown, which adds tables, task lists and strikethrough. The MD file most people meet first is the README.md file, the page GitHub shows when you open almost any repository.
How do you open an MD file?
Any free text editor on any of the major operating systems opens an MD file, because it's just text. The only question is whether you see the raw symbols or the formatted result.
- Windows: Notepad opens it. Newer Windows 11 versions of Notepad also render basic Markdown (headings, bold, lists, links), a feature Microsoft started rolling out in 2025 (Windows Insider Blog, 2025).
- Mac: TextEdit opens it as plain text. For a formatted view, use a Markdown editor such as Obsidian or VS Code.
- VS Code: open the file and press
Ctrl+Shift+V(Cmd+Shift+Von Mac) for a rendered preview, orCtrl+K Vto see a live preview side by side with the source while you type. - Google Docs: since July 2024 you can import an .md file with File > Open and export any doc with File > Download > Markdown (Google Workspace Updates, 2024).
- Microsoft Word: Word shows the raw symbols instead of formatting. Convert first with Pandoc (
pandoc notes.md -o notes.docx), or go through Google Docs. - Phone: most file apps show the plain text. Obsidian on iOS and Android renders it.
- GitHub: every .md file in a repository renders automatically in the browser.
To turn an MD file into a PDF or HTML page, Pandoc handles both from the command line, and the VS Code preview can be printed to PDF.
How do you create an MD file?
Open any text editor, write your text with Markdown syntax, and save it with a .md extension, for example notes.md. On Windows, set "Save as type" to "All files" in Notepad so it doesn't append .txt. In TextEdit on a Mac, switch to plain text first (Format > Make Plain Text), then save. Editors like VS Code and Obsidian create .md files directly, and Google Docs can export any document as one.
What's the difference between MD and TXT?
Both are plain text; the difference is convention. In a .txt file, # is just a character. In an .md file it means "heading", and any tool that understands Markdown renders the structure. Rename notes.md to notes.txt and not a single byte changes, only how apps treat it. Use .md when the text has structure that people or tools will read, and .txt for logs and throwaway notes.
Is an MD file safe to open?
Yes. An MD file is plain text and can't run code on its own, so opening it in an editor is as safe as opening a .txt file. Two caveats are worth knowing. A rendered file can contain links and images pointing anywhere, so treat its links the way you'd treat links in an email. And for AI agents, an MD file is a set of instructions: a CLAUDE.md or AGENTS.md from a repo you don't trust can tell an agent to run commands, so read it before you point an agent at that project.
What does MD mean in AI?
In AI tools, MD still means Markdown, and it shows up in two places. ChatGPT and Claude write their answers in Markdown, which is why replies arrive with headings, bold text and bullet lists. And coding agents read their instructions from MD files at the start of every session: CLAUDE.md for Claude Code, AGENTS.md for Codex, Cursor and a growing list of other agents.
What is a context file (AGENTS.md, CLAUDE.md)?
A context file is a Markdown file at a project's root that tells an AI agent what it can't work out from the code. The AGENTS.md spec calls it "a README for agents". It stopped being a niche habit a while ago: AGENTS.md is used by more than 60,000 open-source projects, and in December 2025 it became one of the founding projects of the Linux Foundation's Agentic AI Foundation, alongside Anthropic's Model Context Protocol and Block's goose (Linux Foundation, 2025).
A good context file covers four things:
- Build and test commands: how to run, build and verify the project
- Conventions: code style, naming and patterns the team follows
- Architecture and rationale: why decisions were made, so the agent doesn't refactor against them
- Constraints: files not to touch, checks to always run
Claude Code's version has its own guide: What Is CLAUDE.md?
Should you let the agent write its own context file?
Use the generated file as a draft, then cut it hard. Researchers at ETH Zurich tested context files on real coding tasks from GitHub repositories: files written by an LLM slightly lowered task success and raised inference cost by about 20%, while files written by developers improved success only marginally (Gloaguen et al., 2026). Generated files mostly restate what the agent could already read from the code, so they add tokens without adding signal. Running /init in Claude Code gives you a starting point; then delete everything a new teammate could figure out on their own.
Where do MD files break down for AI context?
They break down when one file turns into many and keeping them current turns into a job.
A context file describes a project. It doesn't describe you: your role, the client you're building for, what changed in last week's planning call. That's personal context, and people usually handle it by writing more files: a CLAUDE.md per repo, a context.md for ChatGPT, another one for Cursor, each maintained by hand. They drift as soon as a project wraps or priorities move, and stale context is worse than none, because the model applies it with full confidence.
Delivery is the other gap. A file on your laptop doesn't reach Claude.ai in the browser or ChatGPT on your phone, so you end up copying and pasting it. The portability that made Markdown appealing only goes as far as your patience for moving files around.
What's the alternative to hand-written MD files?
Keep the plain text and drop the upkeep. A context layer builds your context from the apps where it already lives (Gmail, Calendar, Notion, Slack), keeps it current, and serves it to Claude, ChatGPT and Cursor over MCP.
The difference shows up in numbers. In an August 2026 Unabyss benchmark, adding a hand-written CLAUDE.md to an assistant with connected tools barely moved cost, time or quality. Adding Unabyss instead cut cost by 36% and time by 38%, and the quality of accepted output rose from 7.7 to 8.9 out of 10 (What Structured AI Context Is Worth). A file says what was true when you wrote it; a context layer says what's true now.
For one repo with stable rules, a CLAUDE.md is still the right tool, and you don't need anything more. For context about you that changes every week and has to reach every AI tool you use, compare the options in MD File Alternatives for AI Context, or connect your apps to Unabyss and stop maintaining the file yourself.