SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsmarkitdown

markitdown

Office & productivity

View repository

Updated 10-16 10:20

About this skill

MarkItDown — File → Markdown unified entry point

Uniformly convert PDF / Office / images / audio / HTML / EPUB / ZIP and various other formats into clean Markdown,then feed it to AI to read. Wraps Microsoft's open-source MarkItDown. Works across Claude Code / Codex / any platform compatible with SKILL.md.

User agreement: From now on, any file handed to AI should by default go through MarkItDown first, rather than stuffing the binary directly into context or relying entirely on manual description.

When to use / when not to use (judge first, don't just run blindly)

File type How to handle
Office binary .docx .xlsx .pptx .xls MarkItDown(native Read cannot read binary, must convert)
.pdf(text-based / digital edition) MarkItDown extract text, fast and token-efficient
.pdf(scanned / image-heavy / mixed text and images) native visual Read preferred; MarkItDown cannot extract the text in images
Images .png .jpg .jpeg .webp native visual Read preferred; MarkItDown only extracts EXIF, does not do visual OCR
Audio .mp3 .wav .m4a MarkItDown(transcription; ffmpeg already installed locally)
.html .epub .msg(Outlook).zip(recursively unpack internal files) MarkItDown
.csv .json .xml .tsv small ones can just be Read directly; for tabularization / large files use MarkItDown
Plain text / code .txt .md .py .go .log … Read directly, no conversion needed
YouTube links MarkItDown(extract subtitles)markitdown "https://youtu.be/..."

In one sentence:Binary document types always use MarkItDown; purely visual content (images, scans) go through native visual Read; plain text is Read directly.

Standard workflow (three steps for AI)

  1. Convert:markitdown <文件> -o <输出>.md(for large files, be sure to write to disk as .md, don't use stdout to swallow it directly into context).
  2. Read: use the Read tool to read that .md, read whichever section you need.
  3. Act: on the Markdown, do summarization / extraction / translation / Q&A.
# 单文件 → stdout(小文件、快速瞄一眼)
markitdown report.pdf

# 单文件 → 落盘(推荐:大文件、之后要反复 Read)
markitdown report.pdf -o /tmp/report.md

# stdin(从管道来的文件流)
cat report.pdf | markitdown

# 批量 / 输出到目录(本 skill 的封装脚本)
scripts/mdconvert.sh -o /tmp/out *.docx *.xlsx
scripts/mdconvert.sh -p one.pdf          # 只打印不落盘

If the path contains spaces / Chinese → always add quotes:markitdown "我的 报告.pdf" -o /tmp/out.md。

Supported formats (the full MarkItDown suite, already installed locally [all] extras)

PDF · Word(.docx)· Excel(.xlsx/.xls)· PowerPoint(.pptx)· HTML · EPUB · Outlook(.msg)· CSV/JSON/XML · ZIP(recursive unpacking)· Images(EXIF + optional LLM description)· Audio(EXIF + speech transcription)· YouTube URL.

Pitfalls & boundaries (learned the hard way)

  • Images / scanned PDFs are not visual OCR: MarkItDown by default only extracts EXIF metadata from images, and for scanned PDFs can only extract the text layer already embedded—it cannot read the text inside images. For theseprioritize native visual Read(the model's built-in vision), don't expect MarkItDown to recognize images for you.
  • Conversion output may contain sensitive information: documents often hide tokens / passwords / JWTs / personal information (measured: a .docx containing login state, when converted, comes out as a whole string of accessToken).Don't echo the converted Markdown in full into chat, don't commit it to a repo, don't share it externally; when writing to disk, prefer to put it in /tmp, delete it once you're done with it.
  • Large files: dumping dozens of pages of PDF / large Excel straight to stdout will blow up the context.First -o write to disk as .md, then Read fragments as needed。
  • Audio transcription requires ffmpeg: on this machine ~/.local/bin/ffmpeg is already installed, mp3/m4a/wav can all be transcribed. On another machine, if there's no ffmpeg → brew install ffmpeg。
  • Images need a "description", not just EXIF extraction: MarkItDown supports passing an LLM client to generate descriptions for images, but the CLI doesn't enable it by default. If you want descriptions of image content, using native vision Read is simpler.
  • Not sure whether it can convert: just markitdown <文件> give it a try; on failure it exits non-zero + reports an error, then fall back to native Read.

Installation / maintenance (already installed on this machine, only needed on another machine)

Already installed globally on this machine via uv tool, the CLI is at ~/.local/bin/markitdown(already in PATH):

# 全新安装(全格式 extras)
uv tool install 'markitdown[all]'

# 升级
uv tool upgrade markitdown

# 自检
which markitdown && markitdown --help | head -3

If there's no uv, then brew install uv; it's installed in a uv isolated environment, without polluting the system / project Python.