markitdown

MarkItDown

使用 Microsoft 的 markitdown CLI，将文档、图像、音频文件或 YouTube URL 转换为 Markdown。此技能会验证输入、组合合适的标志，可选择将结果保存到 ~/.agents/output/<project>/markitdown/<slug>/，并报告一行摘要，其中包含完全展开的绝对路径（不含波浪号，也不使用魔法）。

确定性工作——安装检查、验证、slug 派生、保存路径和命令组合——都在 scripts/markitdown.sh 中完成。此技能会解析 $ARGUMENTS，将其传递给脚本，并将脚本的 RESULT: 行转换为面向用户的报告。

安装

pip install 'markitdown[all]'

如需更精简的安装，请仅选择所需内容：

组	添加内容
[pdf]	PDF 解析
[docx]	Word 文档
[pptx]	PowerPoint
[xlsx] [xls]	Excel
[outlook]	Outlook .msg
[audio-transcription]	MP3/WAV 转录；当前转换器会将音频发送至 Google 识别服务
[youtube-transcription]	YouTube 转录文本
[az-doc-intel]	Azure Document Intelligence 后端

对于 Azure Document Intelligence，在使用 -d 调用前，还需导出 MARKITDOWN_DOCINTEL_ENDPOINT=https://<resource>.cognitiveservices.azure.com/。

参数

标志	默认值	效果
-s	关闭	将 Markdown 保存到 ~/.agents/output/<project>/markitdown/<slug>/<stem>.md
-S	关闭	强制不保存（覆盖当前环境中的保存模式）
-d	关闭	使用 Azure Document Intelligence（需要 MARKITDOWN_DOCINTEL_ENDPOINT）
-p	关闭	启用已安装的第三方 markitdown 插件
-k	关闭	在输出中以内联形式保留数据 URI（base64 图像）
-l	—	列出已安装的插件并退出

输出保存在 ~/.agents/output/{project}/markitdown/{slug}/ 下，其中 {project} 是 git 顶层目录的连字符格式 basename（否则为 cwd），{slug} 是输入 basename 的连字符格式名称（≤5 个词）。适用于流水线——典型的下游用法：/forge -s -f <path> 将提取的内容分解为工作流；/apex -f <path> 根据内容实施；任何接受 -f 的技能都可以使用该文件。

工作流

1. 根据参数或明确无歧义的会话上下文确定目标。只有在目标缺失或有歧义时才询问。进行音频、OCR、Azure 或插件转换前，验证已安装的后端以及所需的数据传输授权；可选依赖组并不意味着会在本地处理。

2. 运行辅助脚本：

   $SKILL_DIR = 此技能的文件夹——在 Claude Code 中为 ${CLAUDE_SKILL_DIR}，在其他环境中为包含此 SKILL.md 的目录。

   bash "$SKILL_DIR"/scripts/markitdown.sh -s '/absolute/path/report.pdf'
   

   将参数作为数据解析，并在 shell 引号保护下分别传递每个标志/值。切勿将原始 $ARGUMENTS 拼接到 shell 代码中，也不要使用 eval。

3. 脚本会输出 RESULT: key=value 行——键包括：bytes、slug、saved；保存时还包括 path（顺序不固定；按键解析）——之后输出转换后的 Markdown（不保存模式下，在 --- 分隔符之后），或者不输出内容（保存模式下，文件已写入磁盘）。

4. 解析 RESULT: 行并生成下方的报告。

5. 如果脚本以 ERR: markitdown not installed 退出（退出代码 127）→ 打印 ## 安装 中的安装命令并停止。切勿代替用户自动安装。

6. 如果脚本以其他 ERR: 退出（文件不存在、缺少 endpoint、未知标志）→ 原样转发消息并停止。

输出

markitdown: <input> → <bytes> bytes of Markdown
saved: <path>      # only when -s

保存时，报告实际文件路径。对于较长的输出，如果符合请求，则选择保存模式；或者将标准输出一次性捕获到经授权的临时文件中，然后提供有限预览和保留的结果。不要仅为截断显示而重复执行耗时转换。

示例

/markitdown ~/Downloads/report.pdf            # convert, print to terminal
/markitdown -s ~/Downloads/report.pdf         # convert + save under ~/.agents/output/<project>/markitdown/report/
/markitdown -s -p deck.pptx                   # use third-party plugins (e.g. markitdown-ocr)
/markitdown -d invoice.pdf                    # Azure Document Intelligence
/markitdown -k brand.html                     # keep base64 images inline
/markitdown https://youtu.be/dQw4w9WgXcQ      # YouTube transcript
/markitdown -l                                # list installed plugins, then exit

注意事项

• YouTube URL 会通过 https?:// 前缀进行检测，并直接传递给 markitdown。Slug 由 URL 的最后一个路径段生成，因此保存路径如下：~/.agents/output/<project>/markitdown/dqw4w9wgxcq/dQw4w9WgXcQ.md。
• 已验证的 0.1.7 转换器使用 recognize_google 进行音频转录，而不是本地 Whisper。处理前，请检查已安装的实现和 Microsoft 的源代码。对于仅限本地／私有处理的请求，必须使用实际配置为本地运行的工具；承诺本地处理时，不要将音频发送到外部。
• 图像 OCR 需要配置可用的后端。Microsoft OCR 插件说明要求提供 llm_client 和模型；仅安装插件并传入 -p 并不足够。请明确说明 OCR 不可用；只有在配置和传输方式均获授权时，才使用文档中说明的集成。
• 如果目标位置已存在文件，转换前就会因保存输出冲突而失败。请使用其他目标位置／输入标识，或先获得替换现有输出的授权；仅靠 slug 命名无法保留文件。

为什么要用封装器

markitdown 本身已经是很棒的 CLI；之所以需要这个技能，是为了（a）遵循仓库的 -s/-S/-f 约定，让其他技能可以接续处理输出；（b）把“提取这个 pdf”转换为正确的调用方式，而不必让用户记住 -x、-m、-d 和 -e；（c）输出统一的单行报告，避免终端意外渲染数 MB 的 Markdown。