前言¶
在 Cursor、Claude Code 等环境里，Agent 默认只能直接读纯文本。用户丢过来一份 PDF、PPTX 或压缩包里的多份材料时，常见做法是手写脚本、临时装解析库，或把文件上传到别的服务再粘贴结果。步骤多、格式易丢，也不利于后续让模型做摘要或检索。
下面介绍 SkillHub 上的 markitdown（坐标 @user_a7465146/markitdown-uvx）。它把 Microsoft MarkItDown 的调用方式写进标准 SKILL.md，让 Agent 在合适时机用 uvx 执行转换，输出保留标题、列表、表格、链接等结构的 Markdown，便于 LLM 消费或文本分析。
这是什么¶
markitdown 是社区发布（community）的 Agent Skill，版本 1.0.0，分类为 office-efficiency，发布者为 user_a7465146。Skill 本身不托管转换逻辑，而是指导 Agent：何时该转、用什么命令、常见参数与踩坑。
底层工具是微软的 MarkItDown；Skill 名称里的 uvx 表示推荐通过 uv 的 uvx 按需拉取 Python 包运行，无需在本机长期安装一整套环境。SkillHub 元数据标明 requires_api_key=false，常规本地转换不依赖额外 API Key（若启用 Azure Document Intelligence 等能力则需自行配置端点）。
核心功能¶
以下能力与已安装的 Skill 包内 SKILL.md 一致。
触发条件¶
当用户需要把文件转为 Markdown、从文档提取文字、读取二进制或 Office 内容，或提到「markitdown」「convert to markdown」「extract text from document」时，Agent 应启用本 Skill。
支持的输入¶
| 类型 | 说明 |
|---|---|
PDF、Word（.docx）、PowerPoint（.pptx）、Excel（.xlsx / .xls） |
需通过 markitdown[...] 额外依赖或 [all] |
| HTML、CSV、JSON、XML | 内置支持 |
| 图片 | EXIF + OCR |
| 音频 | EXIF + 语音转文字（需 [audio-transcription]，系统需 ffmpeg） |
| EPUB、ZIP（遍历内部文件）、YouTube URL | ZIP/YouTube 等需对应 extra 或 [all] |
Outlook .msg |
需 [outlook] 或 [all] |
输出侧重结构化文本；PDF 中的图片内容不保证被提取，复杂版面可结合 Skill 文档中提到的 OCR 插件路径。
CLI 要点¶
- 推荐完整依赖：
uvx --from "markitdown[all]" markitdown <文件> - 输出文件：
-o output.md - 从标准输入读取时可加
-x pdf等扩展名提示 - 可选
-d/-e对接 Azure Document Intelligence 以改善部分 PDF 提取效果
安装与启用¶
1、安装 SkillHub CLI（若尚未安装）¶
先检查是否已有 CLI：
command -v skillhub && skillhub --version
未安装时，可按 SkillHub 官方说明执行（完整安装或仅 CLI）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
仅 CLI：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only
2、把 Skill 装到当前 Agent 的 skills 目录¶
安装时必须用 --dir 指向当前客户端识别的 skills 目录，否则默认落在 ./skills/ 可能不会被加载。参考 SkillHub 安装文档：
skillhub install markitdown-uvx --namespace user_a7465146 --dir <你的 skills 目录>
常用路径示例（以官方文档为准）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
也可让 Agent 根据 https://skillhub.cn/install/skillhub.md 安装坐标 @user_a7465146/markitdown-uvx。
3、运行环境¶
执行转换的机器需要已安装 uv（提供 uvx 命令）。首次运行会拉取 markitdown 及所选 extras 的依赖，耗时高于后续调用。
典型用法¶
下列命令来自 Skill 包内的 Quick Reference，可在终端直接复现。
输出到标准输出：
uvx --from "markitdown[all]" markitdown report.pdf
写入 Markdown 文件：
uvx --from "markitdown[all]" markitdown report.pdf -o report.md
管道输入：
cat input.pdf | uvx --from "markitdown[all]" markitdown
仅安装部分格式依赖（减小体积）：
uvx --from "markitdown[pdf,docx,pptx]" markitdown input.pdf
在对话里，用户只需说明源文件路径与目标（例如「把这份 docx 转成 md 给模型读」），Agent 读取已安装的 SKILL.md 后应选用上述形式，并避免省略 --from "markitdown[all]" 导致 PDF/Office 缺依赖。
适用场景与注意¶
适合谁
- 经常让 Agent 阅读 PDF、Office、EPUB、ZIP 内文档的开发者或知识工作者
- 需要把非文本材料整理成 Markdown 再做 RAG、摘要、对比分析的团队
限制与常见错误（Skill 文档中的 Common Mistakes）
- 使用
uvx markitdown而不带--from "markitdown[all]"（或对应格式 extra），PDF/DOCX 等会缺依赖。 - 误写成
uvx markitdown[all]；正确写法是uvx --from "markitdown[all]" markitdown。 - 音频转写依赖系统 ffmpeg。
- 纯扫描版 PDF 或版式复杂的文档，文本提取质量有限；可按需使用 Document Intelligence 或 OCR 相关插件。
SkillHub 页面统计（抓取时）：评分 100000，下载 6224，安装 21；数据随社区更新变化，以 SkillHub 为准。
结尾¶
markitdown 把「多格式 → 结构化 Markdown」收敛成 Agent 可执行的 uvx 流程，减少临时脚本和手工拷贝。若你的工作流里频繁出现 Office、PDF 或压缩包，值得装进当前环境的 skills 目录。
- SkillHub 页面：https://www.skillhub.cn/skills/user_a7465146/markitdown-uvx
- 官方坐标 / API：https://api.skillhub.cn/user_a7465146/markitdown-uvx
