Writing in Markdown: Why It Matters and What It Has to Do with AI

When you hear about Markdown, the most common association is with GitHub documentation, README files, or Discord messages. Something technical, something for developers.

For me, it has become something else entirely: the way I communicate with my AI agents every day. (An AI agent is a program that carries out tasks for you based on written instructions; I explain how I use them in How I work with AI agents.)

I'm not talking about writing beautiful documentation. I'm talking about using Markdown as a language to tell an agent what I want it to do, with what context, in what order, and with what constraints.

Why Markdown and Not Plain Text

You can write to an AI agent in plain text. It works for simple things. But when a task has several parts —context, instructions, examples, constraints— plain text becomes hard to follow.

A long message without structure is difficult to read for a person. And for an AI, too. Models don't process a block of text the same way they process a document with sections, lists, and hierarchy.

Markdown brings structure without complications. A heading marks a section. A list orders the steps. A code block separates an example from the rest. And all of this helps the model understand what is context, what is an instruction, and what is a constraint.

What I Use Every Day

My agents are guided by Markdown documents. Skills are .md files with a fixed structure: what they are, when they're used, what steps to follow, and what mistakes to avoid. Templates are Markdown templates with variables. Recurring instructions are saved as Markdown notes.

I didn't do this by design, but out of necessity. When I started delegating tasks to agents, instructions in plain text generated more errors, more back-and-forth, and more corrections. When I moved those same instructions to Markdown, the result improved noticeably.

Lists, Blocks, and Order

When I give instructions to an agent, I write them as numbered lists. Not because I like the format: a list imposes an order. Step 1 comes before step 2. If the agent follows the list, nothing gets left behind.

Code blocks are useful for giving specific examples. If I want an agent to update a project through the API (the door programs use to talk to each other), I write the full curl —the command that makes the request— inside a code block, as part of the instruction. I don't tell it "do a curl to this endpoint" (the address that receives the request); I write the exact command. The difference in the result is clear.

And headings separate sections: context, instructions, constraints. If everything is in a single paragraph, the model can mix the instructions with the context. If each thing has its own section, it keeps them separate.

Frontmatter as Context

One thing I've learned working with Astro and my portfolio is that the frontmatter of a Markdown file is a very efficient way to give context. Frontmatter is that header between dashes with key-value pairs.

A file with frontmatter is not just text. It's text with metadata: language, date, category, status. And that metadata tells the agent, before reading anything, what it's dealing with.

It's like the header of an email: before reading the message you already know who it's from, when it arrived, and what it's about.

What It Isn't

Writing in Markdown for AI agents is not the same as documenting code. It doesn't try to be beautiful or exhaustive. It tries to be clear and functional.

You don't need to explain everything. You need to give enough information for the agent to know what to do, without unnecessary information. A 200-line document that repeats the same thing in three places is worse than a 50-line one that gets straight to the point.

When Plain Text Is Enough

Not everything needs Markdown. If the task is simple —"review this text and tell me what you think" or "check that this server responds"— a clear message in plain text works fine.

The problem appears when the complexity grows and I keep writing the same way. If the task has several parts, depends on specific context, or has important constraints, plain text falls short. This is where Markdown's structure makes the difference.

It's not about using Markdown always. It's about knowing when plain text is no longer enough.

What It Has Taught Me

Learning to write in Markdown has taught me to think more structurally. When you separate context from instructions, order the steps, and distinguish what is important from what is secondary, you don't just do it better for the AI: you also do it better for yourself.

Now, when I write an email, an instruction for a colleague, or a technical document, I think in sections, order, and clarity. And when an entire workday is delegated to agents, structure is what keeps everything in order: I told the story of one very dense day in The densest Saturday: editor, ingest, and a DNS that shut down.

Not because Markdown imposes it on me, but because I've seen that when something is well-structured, everyone understands it better.