A .md file is a Markdown file: an ordinary text document that uses a few symbols for formatting. A line starting with # is a heading, **words** are bold, and a line starting with - is a bullet point. Any app that can open text can open it. An app that understands Markdown shows it as a formatted document instead of showing the symbols.
If you did not choose Markdown, an AI tool probably chose it for you. ChatGPT, Claude, Cursor, Claude Code and Codex all write in Markdown, so their plans, summaries and notes arrive as .md files. GitHub uses it for every project's README. It is popular because it stays readable even when nothing formats it.
What a .md file looks like
This is the whole file, as plain text:
# Launch plan
We ship on **Thursday**. Three things left:
- [x] Final copy review
- [ ] Update the pricing page
- [ ] Tell support
| Owner | Task |
| ----- | ------------ |
| Ana | Pricing page |
| Ben | Support note |In a Markdown viewer, that becomes a page with a title, a bold word, a checklist with one item ticked, and a two-column table. Same file, two ways of seeing it.
How to open a .md file
- To see the text: any text editor. On a Mac that is TextEdit, which is already installed. You will see the symbols.
- To see the formatted document: a Markdown viewer, or Quick Look (select it in Finder and press
Space) with a Markdown preview extension installed. macOS has no Markdown viewer of its own. - To edit it: any text editor works, because it is plain text. An editor that hides the symbols and shows the formatting is easier if you are used to Word or Google Docs.
Step-by-step instructions, including how to make every .md file open in the same app: how to open a .md file on a Mac.
The .md files AI tools create
A week of working with a coding agent and the folder looks like this:
README.md
CLAUDE.md
AGENTS.md
PLAN.md
IMPLEMENTATION.md
SPEC.md
HANDOFF.md
CHANGELOG.mdThey are all the same kind of file, so the extension tells you nothing about which one to open. The name does, because most of these names are conventions borrowed from software projects, and the agent is following them whether or not anyone told you.
Here is the map.
README.md — the front door
The oldest convention on the list, and the one file every project is expected to have. It answers: what is this, what does it do, how do I run it. GitHub renders it automatically underneath the file list, which is why it is the one document in a repository that anyone actually reads.
Worth reading: yes, first, if you have just been handed a project. It is the only file written on the assumption that the reader knows nothing.
CLAUDE.md — standing instructions for Claude Code
Not documentation. CLAUDE.md is a memo to the agent: the conventions of this project, the commands to run, the things not to touch. Claude Code reads it at the start of a session, so it behaves like a set of house rules that apply automatically to every future conversation.
Worth reading: yes, and worth editing. If the agent keeps doing something you do not want, a line in CLAUDE.md is the fix — and it is a document written in ordinary sentences, not code. This is the file where a non-engineer has the most leverage.
AGENTS.md — the same idea, tool-neutral
A convention several tools converged on so that a project's instructions are not tied to one vendor. Content is the same shape as CLAUDE.md: how this project works, what to do and avoid. Projects sometimes carry both, and sometimes one is a stub pointing at the other.
Worth reading: yes, same reason.
PLAN.md, TASKS.md, TODO.md — work in progress
Generated. An agent asked to do something substantial will often write down the plan first and tick items off as it goes, usually as a Markdown task list:
- [x] Audit the existing checkout flow
- [x] Draft the new states
- [ ] Wire up the error handling
- [ ] Write the testsWorth reading: this is the status report, and the most useful file in the folder for anyone managing rather than building. It is also the one that changes most often — it is being rewritten while you read it. A viewer that lets you tick a box and have it written back to the file turns it into a shared to-do list rather than a printout.
SPEC.md, DESIGN.md, ARCHITECTURE.md, RFC.md — decisions
What is being built and why, written before or during the work. A spec describes behaviour; an architecture document describes shape; an RFC ("request for comments") proposes a change and expects argument. Often the best writing in the project, because these are the documents produced when someone was thinking rather than typing.
Worth reading: yes, if the decision affects you. These are the ones worth exporting to PDF and sending round.
IMPLEMENTATION.md, HANDOFF.md, NOTES.md, SESSION.md — agent scratch
Working memory. An agent running out of room in a conversation will write down where it got to so the next session — or the next agent — can pick up. Useful to them, rarely interesting to you.
Worth reading: only when something went wrong and you want the trail.
CHANGELOG.md — what changed, by version
A dated, reverse-chronological list of changes. Increasingly written by the tooling rather than by hand.
Worth reading: when you need to know what shipped, and when.
CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md — project policy
Boilerplate for open-source projects: how to submit a change, how to behave, how to report a vulnerability. Templates, mostly.
Worth reading: only if you are about to contribute.
If you only open two
Open README.md to learn what the thing is, and the plan file to learn where it has got to. Everything else you can read when a question sends you there.
Reading them without opening a code editor
All of these render into ordinary documents — headings, tables, checkboxes, diagrams. You do not need the project, the terminal or an IDE to read one; you need something on your Mac that renders Markdown. The fastest route is Quick Look: select the file in Finder, press Space, and read it in place. macOS does not do that for Markdown on its own, and the setup takes about a minute.
nicemd
nicemd is a Markdown viewer and editor for Mac. It opens any of these files as a document: outline in the sidebar, tables and Mermaid diagrams drawn, checkboxes clickable and written back to the file. It adds Quick Look so Space previews Markdown in Finder, and it keeps up when an agent rewrites the file underneath you. Reading, Quick Look, Save as PDF and Copy as HTML are free; edit mode, split view and export to HTML and Word are a one-time unlock, and you can try editing free for 3 days. Get it on the Mac App Store.
Questions
What does .md stand for?
Markdown. The format was created in 2004 as a way to write formatted text that still reads well as plain text.
Is a .md file safe to open?
Yes. It is plain text and cannot run anything on its own. Treat links inside it like links in any email.
How do I turn a .md file into a PDF or Word document?
Open it in an app that shows the formatted document, then use ⌘P → Save as PDF. For Word, use an app that exports .docx; nicemd does both from the File menu.
Can I open a .md file on a Mac without installing anything?
Yes, in TextEdit, but you will see the raw text with its symbols. To read it formatted you need a Markdown viewer or a Quick Look extension.