前言¶
对话里要读一份 .docx，常见做法是先把文件下载、解压、遍历 word/document.xml，再想办法把表格拼回 Markdown，脚本写一次能用，但换一个 .xlsx 又要重来一遍。这类「文档内容提取」的活，格式分散、依赖琐碎，每次都从头造轮子成本不低。
下面介绍的 Skill「万能文档转 Markdown」就是把这件小事封装成一条命令。它底层用的是微软开源的 MarkItDown，支持 PDF、Word、Excel、PowerPoint、HTML、CSV、图片 OCR、音频等格式，输出统一为 Markdown，适合直接喂给大模型或 RAG 流程。
这是什么¶
一句话定位：把各种格式的本地文档批量转成 Markdown 文本的 Skill。
- 出品方：SkillHub 上的 community 来源 Skill，坐标
@user_825f001d/markitdown，Skill 版本1.0.0，分类office-efficiency。 - 底层能力：微软开源的 MarkItDown，PyPI 上以
markitdown包发布（MIT 许可）。 - 解决的问题：让 Agent 在拿到用户上传的 Office 附件时，不必自己写解析逻辑，直接产出可读、可索引的 Markdown。
- 前置条件：
requires_api_key=false，不需要额外配置密钥。
核心功能¶
以下能力来自该 Skill 的官方简介，并与 MarkItDown 上游仓库核对。
支持的输入格式：
- Word（
.docx） - Excel（
.xlsx，另支持旧版.xls） - PowerPoint（
.pptx） - HTML
- CSV、JSON、XML 等文本类格式
- 图片（读取 EXIF 元数据，并支持 OCR）
- 音频（读取 EXIF 元数据，并做语音转写）
- ZIP（遍历包内内容逐个转换）
- EPUB、RSS
触发时机：当用户要求「把 PDF/Word/Excel/PPT 转成 markdown」「提取这份文档的内容」「docx 转 md」「网页转 markdown」，或需要把 Office 附件内容读入对话时使用。
Skill 侧还内置了一套工程化处理：本机安全转换、批量工作流、环境检查，以及在 markitdown 缺失时的离线兜底方案。资料中说明本机已把 MarkItDown 装在托管 venv 中，因此多数情况下无需自行装依赖。
安装与启用¶
Skill 本体按 SkillHub 的通用 SKILL.md 格式使用，在对应 Agent 的 Skill 管理里启用即可。需要安装底层 MarkItDown 时，命令如下（来自 MarkItDown 官方文档）。
先建虚拟环境，避免污染全局依赖：
python -m venv .venv
source .venv/bin/activate
安装全部可选依赖：
pip install 'markitdown[all]'
只想装部分格式的依赖，可以按需裁剪，例如只用到 PDF、DOCX、PPTX：
pip install 'markitdown[pdf, docx, pptx]'
MarkItDown 要求 Python 3.10 到 3.14。可选依赖项包括 [all]、[pptx]、[docx]、[xlsx]、[xls]、[pdf]、[outlook]、[az-doc-intel]、[az-content-understanding]、[audio-transcription]、[youtube-transcription]。
典型用法¶
命令行下把单个文件转成 Markdown，重定向到输出文件：
markitdown path-to-file.pdf > document.md
或指定输出路径：
markitdown path-to-file.pdf -o document.md
也可以走管道，从标准输入读取：
cat path-to-file.pdf | markitdown
在 Python 里调用，适合嵌进 Agent 的转换流程：
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("test.xlsx")
print(result.markdown)
批量处理多个文件时，通常由 Skill 内的批量工作流统一调度；命令行也可以按上面的形式逐个处理。
适用场景与注意¶
适合：需要把 Office 附件、PDF、网页内容读进大模型对话或 RAG 索引，但又不想维护多套解析脚本的场景。
需要注意的几点：
- 输出面向文本分析工具，不保证人类阅读的版式还原。MarkItDown 官方说明其目标是保留标题、列表、表格、链接等结构，而不是高保真的文档转换。
- 转换以当前进程权限执行 I/O。在不可信环境下处理外部文件时，应先做输入校验，并尽量调用粒度最窄的转换函数（如
convert_stream()、convert_local()）。 - 部分格式依赖可选依赖项。没装
[all]时，遇到对应格式会缺能力，先确认实际需要哪几类再装。 - 图片 OCR 与音频转写依赖相应依赖；PDF 内嵌图片的 OCR 还可通过
markitdown-ocr插件走 LLM 视觉能力。 - 版本方面，该 Skill 页面记录的底层版本是 MarkItDown 0.1.8，PyPI 上当前最新版是 0.1.9，安装时以实际装到的版本为准。
结尾¶
这个 Skill 的价值在于把「读文档」这件事从一次性脚本变成可复用能力：格式覆盖面广，输出统一为 Markdown，不需要配置密钥，且自带环境检查与离线兜底。如果你的 Agent 经常要处理用户上传的 Office 附件或 PDF，用它比每次手写解析更省事。
官方地址：https://api.skillhub.cn/user_5d230dc2/markitdown
