前言¶

做 RAG 或文档分析的人常遇到这类问题：手上有 PDF、Word、Excel、PPT，还有图片和音频，格式各不相同，但要喂给模型的只有 Markdown。自己写转换脚本，每加一种格式就要补一套解析逻辑，表格、标题、列表很容易在转换中丢掉；格式一变又得返工。

下面介绍一个把这件事收敛成一条命令的 Skill：Markdown Converter。它内部调用 markitdown，把常见文档格式转成结构化 Markdown，保留标题、表格、列表和链接，不需要你关心每种格式的解析细节。

这是什么¶

一句话定位：这是一个基于 markitdown 的文档转 Markdown 工具型 Skill，把「PDF/Word/PPT/Excel/HTML/CSV/JSON/XML/图片/音频/ZIP/YouTube/EPub → Markdown」统一成一次命令调用。

出品方与来源：发布者是 steipete，坐标 @clawhub_steipete/markdown-converter，来源标记为 clawhub，上游仓库在 https://clawhub.ai/steipete/markdown-converter。

解决的问题是：格式转换这一步被嵌入到 Agent 流程里，Agent 只需要给出文件路径就能拿到可用的 Markdown 文本，不用再自己拼转换脚本。

核心功能¶

支持的输入格式如下（来自上游 SKILL.md）：

1、文档类：PDF、Word (.docx)、PowerPoint (.pptx)、Excel (.xlsx, .xls)。
2、Web 与数据类：HTML、CSV、JSON、XML。
3、媒体类：图片（含 EXIF 与 OCR）、音频（含转录）。
4、其他：ZIP 压缩包（会遍历内容）、YouTube 链接、EPub。

输出方面，官方说明是保留文档结构：标题、表格、列表、链接。

不需要 API Key。Skill 页面的标签为 requires_api_key=false；只有在启用 Azure Document Intelligence 时才需要提供 endpoint。

安装与启用¶

上游页面给出的安装命令如下，属于 OpenClaw 体系的 CLI 安装方式：

openclaw skills install @steipete/markdown-converter

页面上同时提供了 CLI 与 Prompt 两种入口（页面顶部标注 Install / CLI / npx skills / Prompt），说明该 Skill 既可以通过命令行安装，也可以直接以提示词形式使用。

版本与许可：上游当前版本 v1.0.0，许可为 MIT-0，页面显示安全审计为 Pass。

SkillHub 侧信息：官方地址 https://api.skillhub.cn/org-0ll53pt7/markdown-converter（2026-10-30 尝试访问返回失败）。按已抓取的 SkillHub 页面资料，名称为 Markdown Converter，分类 knowledge-management，评分 100000，下载 186732，安装 8264，来源 clawhub。这些数字以 SkillHub 页面抓取资料为准，与任务线索里写的「评分 99959、下载 33762、分类 office-efficiency」不一致，此处采用抓取资料。

说明一下差异：本次任务线索中的分类 office-efficiency 与已抓取资料的 knowledge-management 不一致；「SkillHub 评分 99959、下载 33762」与抓取资料的「100000、186732」也不一致。由于 api.skillhub.cn 与 skillhub.cn 页面都无法打开，以上一律以已抓取资料为准，没有采用线索里的数字。

典型用法¶

转换的核心是 uvx markitdown，官方说明是「无需安装」——首次运行会缓存依赖，之后再跑会快一些。

输出到标准输出：

uvx markitdown input.pdf

保存到文件：

uvx markitdown input.pdf -o output.md
uvx markitdown input.docx > output.md

从标准输入读取：

cat input.pdf | uvx markitdown

带格式提示（stdin 场景下文件类型不明确时用）：

cat document | uvx markitdown -x .pdf > output.md

Office 文档的几个例子：

uvx markitdown report.docx -o report.md
uvx markitdown data.xlsx > data.md
uvx markitdown slides.pptx -o slides.md

针对扫描件或抽取效果差的复杂 PDF，官方给出的路径是接 Azure Document Intelligence：

uvx markitdown scan.pdf -d -e "https://your-resource.cognitiveservices.azure.com/"

可选参数一览：

-o OUTPUT              # 输出文件
-x EXTENSION           # 提示文件扩展名（用于 stdin）
-m MIME_TYPE           # 提示 MIME 类型
-c CHARSET             # 提示字符集，例如 UTF-8
-d                     # 使用 Azure Document Intelligence
-e ENDPOINT            # Document Intelligence endpoint
--use-plugins          # 启用第三方插件
--list-plugins         # 列出已安装插件

适用场景与注意¶

适合的场景：需要把一批异构文档批量变成结构化文本再做检索、摘要或交给 LLM 分析的场景；Agent 流水线中作为「读取文档」这一步的统一实现，避免为每种格式单独维护解析代码。

需要注意的地方：

1、复杂 PDF 的抽取质量取决于文档本身，抽取效果差时官方建议走 -d 加 Azure Document Intelligence。
2、首次运行要下载并缓存依赖，批处理任务里要考虑到这一次额外开销。
3、使用 Azure Document Intelligence 需要有效的 endpoint，这一路径不在「无 API Key」范围内。
4、ZIP 是遍历压缩包内容逐个转换，大压缩包的转换时间要单独评估。
5、音频转换依赖转录能力，图片转换依赖 OCR，两者都受上游 markitdown 依赖项的可用性影响。

结尾¶

这个 Skill 的价值在于把多格式文档转换压缩成一条 uvx markitdown 命令，Agent 侧不需要再关心每种格式怎么解析。如果你的文档来源单一、格式固定，可能只需要 markitdown 本体；如果文档来源杂、且要在 Agent 流程里稳定复用，这个 Skill 省掉的是格式适配和返工。

官方地址：https://api.skillhub.cn/org-0ll53pt7/markdown-converter（SkillHub，2026-10-30 访问失败）；上游仓库：https://clawhub.ai/steipete/markdown-converter。