What is a markdown file?

A text file with a tiny bit of formatting. The format every AI tool reads natively, which is why my whole AI stack is built on it.

I'm in the back of an Uber on the way to the airport. On my phone I'm reading three documents: my CLAUDE.md for the Headphones.com folder, the SKILL.md for the agent that drafts customer-service replies, and the draft of this article. All three are markdown files. None required Word, Google Docs, or any software that costs money. They open the same way in my notes app as they do in Claude.

That is the unlock. Markdown is the format the AI tools and I have agreed to use for almost everything that is not a spreadsheet.

What it is

A markdown file is a plain text file with a handful of formatting conventions. The file extension is .md. You open it in any text editor (TextEdit, VS Code, your notes app, whatever). It looks like text with a few extra symbols sprinkled in. When a website or an app renders it, those symbols turn into actual formatting.

Six conventions cover almost everything:

• # Heading becomes a big header. ## Subheading becomes a smaller one.
• **bold** becomes bold.
• *italic* becomes italic.
• [link text](https://example.com) becomes a clickable link.
• - item at the start of a line becomes a bulleted list.
• A blank line between paragraphs is a paragraph break.

That is the whole format you need to remember. There are a few more conventions (numbered lists, code blocks, tables), but if you can read and write those six, you can read and write 95% of every markdown file you will ever touch.

Markdown was invented by John Gruber in 2004 to make writing for the web painless. It became the format for engineering documentation. Then it became the format that AI tools were trained on. Now it is the lingua franca of the agent harness world: CLAUDE.md, SKILL.md, README.md, voice-profile.md, every prompt template I write is markdown.

Why it matters

Every AI tool reads markdown natively. When you write your business context in markdown, you can hand the same file to Claude, to GPT, to Gemini, and to whatever agent harness you run. All of them understand the structure: this is a header, this is a list, this is a bold claim, this is a link. The structure is meaningful to the model, not just decorative.

Word and Google Docs do not compose this way. Hand a model a .docx and the model reads the binary contents like a robot. Hand the model the same content as markdown and it reads the structure like a human. The difference is the difference between "the AI guessed what mattered" and "the AI knew what mattered."

The other unlock is durability. A markdown file from 2010 still opens cleanly in 2026. The format has not been deprecated. The file is four kilobytes, not four megabytes. Git tracks it cleanly. Backups are trivial. None of that is true for .docx or Google Docs.

What a good one looks like

A short markdown file in the wild looks like this:

# Q4 board update
*Drafted by the agent · reviewed by Andrew*

## Top line
Revenue **$2.4M**, up 18% vs Q3. ARR run-rate **$11.2M**.

## What I'm watching
- Pipeline coverage for Q1 is 1.6x quota. I want 2x.
- Two enterprise renewals slipping into early February.

## Decisions for the board
1. Pause the senior-AE hire until Q1 close.
2. Approve the Hetzner migration spend.

Open it in any text editor. Read it out loud. The structure carries the meaning. A reader who skims gets the headers; a reader who reads gets the bullets; a reader who studies gets the bold claims. The AI agent that wrote the draft sees the same shape.

Common mistakes

Using Word or Google Docs for AI-heavy work. If you find yourself pasting Word content into a Claude tab every week, the workflow is upside down. Save the document as markdown once; the next four sessions get free.

Over-formatting. Markdown is light by design. If your file is half bold and half italic, the bold and italic stop carrying weight. Use bold for the one load-bearing claim per section, not for every word that feels important.

Treating the file as private when it is not. Markdown is plain text. If you commit it to git, the secrets in it are in git history forever. CLAUDE.md, SKILL.md, anything that travels with your repo: no API keys, no passwords, no customer names you would not put in a public deck.

Forgetting it is just text. You do not need a special tool. Any text editor opens markdown. Any AI reads markdown. Stop searching for the "right" markdown editor on day one; the default text editor on your machine is fine.

Do this next

Open your favorite text editor. Create a new file. Save it as notes.md. Write three lines: a header, a bold claim, a bullet. Open the same file with Claude. The bridge is unceremonious. Within a week you will be putting things in markdown that used to live in a Word doc, and the AI will start being useful in places it was not before.