前言¶
在 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
