Key takeaways

• Markdown (.md) is a file format that you use when you work with agents: Most instructions and context files for AI agents are stored in Markdown because the format is easy to read and write for agents and humans. Additionally, Markdown is the main format LLMs use to output formatted text in their responses.
• You write markdown in any text editor (Notepad), IDE (VS Code), or notetaking app (Obsidian): Markdown has a simple syntax for formatting text, so it’s easy to use. You’ll probably use it to write instructions, documentation, AI skills, and other context files that are important to get good results with agents.
• Markdown is the text format used around code to enhance documentation: It’s common to find Markdown in code repos and notebooks in order to store and format documentation. This is because it’s easy to write and use with source control. It’s also common in notetaking applications like Obsidian and Notion.
• Markdown files for data projects can be stored in various places: Some Markdown files you write will be temporary, but many will persist as context and should live in and be distributed via Git repositories, including inside a definition folder like .Report or .SemanticModel.

This summary is produced by the author, and not by AI.

Why you should use Markdown files

When performing agentic development, most of your time will be spent either writing prompts or context files in Markdown (.md) files. This is a simple format used for documentation and notetaking, but which is also easy to read or write for humans and agents. You have almost certainly encountered Markdown before, but you may not have known it. Markdown is used by AI agents, in code documentation, and in some chat programs. Even Microsoft Teams supports a subset of Markdown.

In this article, we give you a brief introduction to the Markdown format and why it’s relevant to use when you work with agents.

What is Markdown and why do we use it?

In the history of computing, it’s been useful to take simple plain text and add details around the text indicating how the text should be rendered or how the pieces interrelate. This is often done with a markup language, the name being inspired by when editors would mark up paper manuscripts. At this very moment, you are interacting with the most famous markup language ever invented, the Hypertext Markup Language (HTML), simply by reading this blog post which is served as HTML.

If you’ve ever worked with data stored in the Extensible Markup Language (XML), that is another place where you may have used a markup language. It’s also possible you have used YAML files to modify configuration settings. YAML originally stood for Yet Another Markup Language (yes, really). In 2000, it was renamed to YAML Ain’t Markup Language. It’s all a bit silly but now you know.

While HTML is powerful, writing HTML isn’t very intuitive for most people and feels more like programming. Markdown was invented as a way of writing that is ergonomic and intuitive, inspired by how people naturally used punctuation to format plain text emails.

How do you write Markdown?

Writing markdown is straightforward; you use a few pieces of punctuation to change the format of nearby text. For instance:

• Double asterisks surrounding text mark it as bold, so **bold** renders as bold
• Single underscores italicize text, so _italicize_ renders as italicize
• One or more hash (#) symbols at the beginning of a line make a header, like ### How do you write Markdown?
• Images are referenced in-line in the text with ![alt-text](path/to/image.png)

When you write markdown, you’ll notice that text formatting and images don’t appear. Like the markup formats mentioned above, this renders as bold, italic, headings and so on when you display it somewhere like an application or website. You can usually preview markdown in editors where you write markdown, like VS Code.

Where do you write and view markdown?

Below is a screenshot of Markdown in VS Code being rendered by the Markdown Preview Enhanced extension. While you can edit Markdown in any text editor, code editors like VS Code or Zed often provide syntax highlighting natively and previewing right out of the box. You can add advanced features which improve the preview or automatically enforce formatting rules from extensions:

If you want to learn markdown in more detail, read the GitHub documentation or play around with the interactive widget below:

# Markdown in 30 seconds

Turn **plain text** into formatting with a little _punctuation_.

- Asterisks make text **bold**
- Underscores make text _italic_
- Backticks wrap `inline code`

> Blockquotes start with a greater-than sign.

Markdown has the following advantages:

• It’s lean, which makes it easier to read without previewing and it costs fewer tokens for AI.
• It’s not packaged in a binary format like text is in a Word document (.docx).
• It’s ubiquitous, so almost every program recognizes and supports it (even SharePoint)

Markdown is common in LLM training and tooling

It’s important to be comfortable with Markdown so that you can write instructions and context files in a format that agents are designed to read. You write Markdown files for agents in the following scenarios:

• Memory files, which agents automatically read. Memory files give preferences and important rules but should be kept to a minimum. These include AGENTS.md, CLAUDE.md, or Markdown files in special folders like .claude/rules/
• Skills, which agents or a user can invoke. Skills teach processes to agents and you can add them to a user or project configuration. They usually consist of markdown files but also other files, too.
• Instructions, plans, and requirements (or “specs”): These are typically temporary documents that you create as part of a planning and requirements gathering process. Later, you should refactor them into other documentation.
• Other documentation: Any documentation or text to describe a process can be written using the Markdown format. An example of “other documentation” could be freeform notes that you take in i.e. an Obsidian vault, Notion, or something else.

Almost all agents will store instructions for every session in a markdown file such as AGENTS.md or CLAUDE.md. If you write AI instructions in a Power BI model, those instructions also expect a Markdown syntax.

Additionally, AI agent skills store their instructions in a SKILL.md markdown file as well as any references optionally bundled in the references folder. Coding agent providers have all consolidated around markdown as the primary text format.

Furthermore, most large language models are trained on Markdown and use that for formatting their outputs. When you see a web chat or coding harness output formatted text, it is very likely outputting Markdown. When working with a coding harness, it will commonly save notes as markdown.

Spec-driven development

Some folks lean into AI and Markdown with something called spec-driven development, where markdown specifications are the formal source of truth for the design. Then there are skills that guide the agents either in the phases of planning and development or to take on certain personas, such as a Scrum Master. In extreme cases of spec-driven development, all the human labor goes into writing Markdown and manual testing, with the AI handling all the coding.

In my personal experience, a small amount of SDD can be helpful for slowing down the developer and agent and to think through the design and technical limitations. However, much of SDD feels to me like a crutch for when LLMs were bad at focusing on a task and bad planning (so, before November 2025).

A repeating pattern with AI is what was a best practice 6 months ago turned out to be a workaround for LLM limitations at that time. Coding agent harnesses often have /plan command that is sufficient. Even then, the strongest frontier models like Claude Fable 5 and GPT 5.6 Sol are explicitly being trained on long-running tasks. So even an explicit planning step is less necessary to keep the AI on the rails, if you are using the strongest models.

Also in my experience, specs run into documentation rot very, very quickly. As we talked about in the memory section of our context and memory for agents article, having stale, historical documents in a code repo is often detrimental and confusing to AIs. While I found SDD useful for initial planning, old feature specs ended up conflicting with new plans. Unless you plan to rigorously maintain a single set of active specs, I don’t think the juice is worth the squeeze here.

How Markdown compares to file formats in a PBIP

If you use the PBIP format, which we recommend, then you have seen a PBIX file exploded into a bunch of little plain text files. It’s worth comparing these to Markdown.

The bulk of a PBIP project is two file formats: JSON and TMDL. JSON, or JavaScript Object Notation, is a data storage and serialization format that is ideal when you need to store nested or hierarchical data. It’s also useful when you want a format that can be parsed by machines and edited by humans, although large JSON files can get quite cumbersome to edit.

In some cases you might also run into YAML, particularly if you are using CI/CD. YAML is used primarily for configuration files a human might edit. YAML looks fairly simple, but can be finicky to edit because it uses significant whitespace. This means that a misplaced tab can break your config.

On the semantic model side, if you have a legacy model.bim file that’s stored as JSON. However, we recommend using TMDL, which is a custom Microsoft format inspired by DAX script syntax in Tabular Editor 3. Both bear similarities to YAML in structure.

TMDL is easier to edit than JSON because you don’t have to worry about quoting strings of text or closing braces. We have a course on TMDL if you are new to it.

For further reading

• Basic writing and formatting syntax (GitHub). Guide for using GitHub’s flavor of Markdown.
• Markdown Philosophy (John Gruber). An explanation of the inspiration and motivations of Markdown from its creator.
• Markdown and Visual Studio Code (Microsoft). Documentation for working with Markdown in VS Code.
• Tabular Model Definition Language (Microsoft). Documentation around the TMDL format.

In conclusion

Markdown is a simple and lightweight language for formatting plain-text documents. It has been popular for many years in code repositories and has become increasingly popular because of LLMs and AI Agents. Markdown differs from JSON, TMDL, and YAML which are intended as machine-readable formats that can also be edited by humans.