Skip to content
Conduit

skill

mmdoc

Folder-based multimodal document format: AI agents search, read, and edit image-bearing docs with ordinary file tools

hsurick/mmdoccommunitylistedunreviewed
Use skill

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/hsurick/mmdoc itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 22, 2026

mmdoc

A folder-based multimodal document format so AI agents can read and edit image-bearing docs with ordinary file tools.

The problem

Research is text + tables + images, but Markdown can only reference images, not hold them — and AI agents are now the primary readers. Content trapped in a screenshot is invisible to grep; an agent can't see a referenced image without extra steps; converting a .docx or Google Doc to Markdown silently drops the images; and rich copy-paste from Google Docs or Notion has nowhere to land, because terminals strip everything but plain text. The worst case: a Markdown file with base64-inlined images, read as text, costs roughly 200k tokens per image, and the model still can't see the image.

mmdoc fixes this once, at write time: convert content into a plain folder shape, and the read side needs nothing special.

The format

An mmdoc is a directory: a single index.md (the document) plus any number of co-located image files at the folder root, referenced by relative path with descriptive alt text.

district-analysis/
  index.md          ← the document: YAML frontmatter + Markdown body
  img-001.png       ← any images, referenced as
  img-002.jpg          ![what it shows and why it matters](img-001.png)

The alt text is a one-sentence summary you can grep — rg "budget allocation" matches the reference line, and an agent opens the actual image file only when it needs visual detail. grep, git, and editors already work on it; nothing new is needed to read one.

Install

Via Homebrew (includes pandoc):

brew install hsurick/mmdoc/mmdoc

Or from PyPI (then install pandoc yourself):

uv tool install mmdoc    # or: pip install mmdoc
brew install pandoc

Then wire up Claude Code (installs the agent skill + the CLAUDE.md read convention):

mmdoc setup

Usage

Copy a chunk of a Google Doc — text and images — then:

mmdoc paste notes/

The text lands in notes/index.md and the images land as real files (notes/img-001.png, …) next to it. Or skip the clipboard entirely and pull a link-shared Google Doc directly:

mmdoc fetch "https://docs.google.com/document/d/<id>/edit"

Commands

CommandWhat it does
mmdoc init <name>Start a blank document: a new folder with a ready-to-edit index.md.
mmdoc normalize <src>Convert a .docx or a Markdown file with embedded images into a plain folder.
mmdoc paste <target>Add whatever you just copied — text and images — to a document folder.
mmdoc clipSave the clipboard as numbered files before your next copy overwrites it; your clipboard then holds {clip:N} to paste into a prompt (--keep leaves it untouched).
mmdoc fetch <url>Turn a shared Google Doc link into a local folder of text + images — no sign-in needed.
mmdoc export <target>Bundle a document folder into one shareable file (HTML, Word, or PDF).
mmdoc validate <target>Check a document folder for problems like missing images or bad metadata.
mmdoc setupSet up Claude Code to work with these document folders (run once).

Agent integration

mmdoc setup installs the bundled workflow skill to ~/.claude/skills/mmdoc/ and maintains a marker-delimited read-convention block in ~/.claude/CLAUDE.md (idempotent; --dry-run supported).

The read convention:

  • index.md holds the text; alt text is a summary — read the image file only when you need visual detail.
  • Convert before read: never read a .docx or a base64-blob .md directly into context; run mmdoc normalize first.
  • After editing an mmdoc, run mmdoc validate <folder>.

The format is agent-agnostic: paste the same convention into an AGENTS.md (or any equivalent instruction file) and any agent with file tools can work with mmdocs.

Spec & design docs

  • FORMAT.md — the normative format specification (v0.1).
  • CLI.md — CLI architecture and command specs.
  • OVERVIEW.md — the problem, goal, and build plan.
  • NOTES.md — background reasoning and prior-art survey.

Status

v0.1. Clipboard commands (paste, clip) are macOS-only for now (Linux via xclip/wl-paste planned). Roadmap:

  • normalize support for Notion .zip exports.
  • normalize support for loose/messy folders.
  • DocLang (.dclg/.dclx) importer — bridges Docling document-AI pipelines (and PDFs) into mmdoc.
  • TextBundle interop — import/export the existing .textbundle format.

License

Apache-2.0. See LICENSE.

↑↓ navigate openesc close