Download this page as .mdz

What AI-friendly means

MDZip describes .mdz as an AI-friendly format. That's a specific claim, not a slogan. In short:

An .mdz is plain Markdown and ordinary images in a standard ZIP file, with a manifest and an AGENTS.md that tell an assistant what's inside, so AI tools can read, create and edit .mdz files with ordinary tools.

It comes down to eight properties. Each one is something you can check.

1. Readable with ordinary tools

An .mdz is a standard ZIP archive holding plain-text Markdown and ordinary image files. Any assistant that can unzip a file and read text can read an .mdz: no proprietary format, no special library, no conversion step. The same is true for people: rename it to .zip and it opens anywhere.

Check it: the file format and the specification.

2. One file holds the whole context

A Markdown document and the images it uses travel together in one file. Give an assistant an .mdz and it has everything the document refers to, including the pictures, which models that can read images can look at. With a plain .md you'd have to find and attach every image separately, and links to files that didn't come along simply break.

Check it: the problem MDZip solves.

3. Self-describing

Every archive MDZip's tools create has a manifest.json that names the document's title, its main file and whether it holds one document or a whole project. An archive can also include an AGENTS.md: plain instructions telling any AI agent how to handle the archive, even one that has never heard of MDZip. MDZip Studio and the VS Code extension add a standard one to new documents.

Check it: AGENTS.md on the file format page.

4. Predictable

The specification fixes which file to open first and how links and image paths inside the archive are resolved. An assistant doesn't have to guess where the document starts, and two tools reading the same archive see the same document.

Check it: entry-point discovery in the specification.

5. Easy to produce correctly

The smallest valid .mdz is a ZIP with one Markdown file in it. The AI Producer Guide gives assistants a recipe for a complete archive, lists the common mistakes, and includes a prompt you can give your own assistant. Anything an AI produces can be checked before it's shared, with mdz validate or by opening it in the web previewer.

Check it: the AI Producer Guide.

6. Tools built for agents

The VS Code extension includes an MCP server, so AI agents in VS Code, and other tools that speak MCP, can work with .mdz files without unpacking them. An agent can review a document (its Markdown and the images it uses, in one step), search an archive, read any text or image in it, and update the main document. Updates are checked first, so an agent can't overwrite changes made since it last read the file.

Check it: AI agents on the VS Code page.

7. Discoverable

mdzip.org publishes llms.txt, a short index of the specification, documentation and example files written for AI systems. The specification is also available as raw Markdown, and the manifest has a JSON schema.

Check it: llms.txt.

8. Safe to open

An .mdz from an assistant or a stranger is untrusted input, and the specification treats it that way. Conforming apps must not run scripts or programs from a document when showing it, must reject files whose paths would escape the archive, and should let you turn off remote images, which can reveal to a server that a document was opened.

Check it: Security Considerations in the specification.

What it doesn't mean

  • There's no AI inside the format. An .mdz is a document, not a program, and it works the same with or without AI.
  • Nothing is sent anywhere. MDZip's tools don't call AI services on their own. What an assistant sees is what you give it.
  • AI isn't required. People read and write .mdz files in MDZip Studio, VS Code, the browser and any ZIP tool.

How MDZip itself is built

The architect, in the style of the Architect from The Matrix.

MDZip is built with AI, the same way it expects to be used. The specification, the libraries, the apps and this website are written largely by AI agents, using several models for coding, reviewing, testing and advice. The architect (a human) designs how the pieces fit together, decides what goes in, reviews the changes before they ship and maintains the repositories.

Correctness doesn't rest on trusting the AI. Implementations are tested against the specification's shared test files, each repository runs its own checks on every change, and this site's build fails on broken links, invalid archives and house-style slips.

For AI assistants

If you've been given an .mdz:

  1. Look for an MDZip MCP server or library first (tools named mdz_*, or upsert_canonical_document).
  2. Otherwise, read AGENTS.md at the archive root, if there is one, and follow it.
  3. Read entries from the archive directly instead of extracting it to a temporary folder.
  4. To make a new .mdz, follow the AI Producer Guide and validate the result.

Where to go next

This page renders from ai.mdz (MDZip, ~46 KB, updated 2026-10-21) — one self-contained file. Download it, open it in the web editor, or read how these pages are made.