Markdown: a simple format AI reads and writes well

What it is

Markdown is a simple way to add structure to plain text. Instead of clicking buttons for bold or headings, you type a few symbols:

# Main heading
## Section heading
- a bullet point
1. a numbered step
**bold words**

That is almost all you need. A Markdown file is a plain text file, usually ending in .md. It opens in any text editor, on any computer, and many tools display it neatly formatted.

AI assistants work naturally with Markdown. Many of them answer in it (that is why their replies often have headings and bullets), and they read it easily, because the structure is plain to see: this is a heading, this is a list, this is a step.

Think of it as a tidy filing system for words. A formatted document hides its structure in formatting; Markdown shows it in the text itself.

Why it matters

• Clearer context. Headings and lists tell the AI what each part is, so it is less likely to mix up your instructions, your examples and your source material.
• Less clutter. A pasted PDF or heavily formatted document can bring page numbers, headers and stray characters with it. Clean Markdown uses less of the AI's limited working space (its "context window") on noise.
• Reusable. Saved instructions, skills and context packs (guides 05 and 11) are often stored as Markdown files. Some assistants read an instructions file in Markdown automatically when they start a task.
• Portable. Plain text works in every tool and stays readable for years. It is easy to share, compare between versions and convert into a formatted document, a web page or a slide.

How to do it

1. Open any plain text editor (or a note app that supports Markdown).
2. Start with one heading that says what the file is for: # Context: monthly sales report.
3. Split the content into sections with ## headings, such as Goal, Audience, Rules, Examples.
4. Use bullets for lists and numbers for steps that must happen in order.
5. Mark fill-in parts with [square brackets] so they are easy to spot.
6. Save the file with a clear name and the .md ending, for example context_sales_report.md.
7. Paste it into your assistant, or upload it to a project, whenever you do that task.

Example

Before: a two-page formatted document with the background to a monthly report, copied in with its tables, headers and page numbers. The AI mixes up last month's figures with this month's instructions.

After: a short Markdown context file.

# Context: monthly sales report

## Goal
A one-page summary for the leadership team, ready by the 5th.

## Audience
Directors. They want the headline, the reasons and one decision.

## Rules
- Use only the figures in the attached table.
- Compare with last month and the same month last year.
- Flag any figure that moved more than [10]%.
- No jargon. Under 300 words.

## Example of a good summary
[paste last month's approved summary]

The AI now knows which part is the goal, which part is a rule and which part is an example to copy.

Common mistakes

• Pasting formatted documents straight in. Fix: copy the text, then add simple headings yourself, or ask the AI to "convert this into clean Markdown" first, and check the result.
• One long paragraph of instructions. Fix: break it into short bullets under clear headings.
• Too many heading levels. Fix: # and ## are usually enough.
• Keeping confidential data in shared Markdown files. Fix: treat these files like any other document; follow your data rules.

Try it this week

1. Pick a task you give to AI at least once a week.
2. Write a Markdown context file for it with four sections: Goal, Audience, Rules, Example.
3. Use it the next three times you do the task.
4. Improve it each time the AI gets something wrong, then share it with a colleague.

Going further

• Ask the AI to answer in Markdown, then paste the result into a document tool that converts it into formatted text.
• Keep a small folder of Markdown files: one context file per recurring task, one file of house style rules, one glossary of company terms.
• Some assistants and agent tools let you keep a standing instructions file in Markdown in a project or folder, which they read at the start of each session or task.
• Simple tables also work in Markdown, using | between columns.

Key words

• Markdown: plain text with a few symbols (#, -, **) that mark headings, lists and emphasis.
• .md file: a text file written in Markdown.
• Context file: a saved file of background, rules and examples for one recurring task.
• Plain text: text with no hidden formatting, readable by any tool.

Examples and figures in this guide are illustrative. AI tools change often: check what your organisation's approved tools offer today. Use approved tools only, and a person checks and decides.

Prefer to print or share it? Download this guide as a PDF (253 KB), or the complete AI Field Guide (1.7 MB).