markitdown — 任何文件 → Markdown 喂给 AI 的 agent skill

把 PDF / Word / Excel / PPT / 图片 / 音频 / HTML / EPUB / ZIP 等转成干净的 Markdown,再喂给 AI 读。封装微软 MarkItDown,做成一个 SKILL.md 技能,跨 Claude Code / Codex / Cursor / OpenCode 及任何兼容 skill 规范的 agent 即插即用。

理念:任何丢给 AI 的文件,先过一遍 MarkItDown 转成 Markdown,而不是把二进制塞进上下文或人肉描述。

安装

方式 A — 一键脚本(推荐)

git clone https://github.com/xnydl/markitdown-skill.git
cd markitdown-skill && ./install.sh

脚本会:装 uv(若缺)→ uv tool install 'markitdown[all]' → 把 skill 拷进检测到的 cc / codex / opencode skills 目录。重启 agent 即生效。

方式 B — 手动

# 1) 装 CLI(uv 隔离环境,不污染系统 python)
brew install uv && uv tool install 'markitdown[all]'
brew install ffmpeg          # 可选:音频转写才需要

# 2) 把 skill 放进你的 agent skills 目录(Codex 换 ~/.codex/skills/)
git clone https://github.com/xnydl/markitdown-skill.git ~/.claude/skills/markitdown

确保 ~/.local/bin 在 PATH(uv 把 markitdown 命令装在这里)。

用法

markitdown report.pdf -o out.md          # 单文件(大文件务必落盘再读)
markitdown report.pdf                    # 小文件直接打印
scripts/mdconvert.sh -o /tmp/out *.docx  # 批量(本仓库自带的薄封装)

装好后,在 agent 里直接说「读一下这个 pdf / 把这个 docx 转成 markdown / 这个文件讲了啥」就会自动触发本 skill。

支持格式

PDF · Word(.docx)· Excel(.xlsx / .xls)· PowerPoint(.pptx)· HTML · EPUB · Outlook(.msg)· CSV / JSON / XML · ZIP(递归解包)· 图片(EXIF)· 音频(语音转写,需 ffmpeg)· YouTube URL。

注意

• 图片 / 扫描版 PDF 用 agent 原生视觉读更好 —— MarkItDown 只抽文本层 / EXIF,读不出图里的字。
• 转换产物可能含 token / 密码 / PII,别整段回显、别 commit、别外传。

详细判断边界与坑见 SKILL.md。

License

MIT