1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | convert-pdf-to-md-github-awesome-copilot | — |
| 作者/维护者 | GitHub（github/awesome-copilot 官方合集仓库） | GitHub API |
| 来源链接 | https://github.com/github/awesome-copilot/tree/main/skills/convert-pdf-to-md | — |
| 许可证 | MIT（仓库级） | GitHub API |
| GitHub Stars / Forks | 38,083 / 4,810（属整个 awesome-copilot 合集仓库，不代表本技能自身热度） | GitHub API |
| 最新版本 | 无独立版本号，随仓库持续更新（该子技能最近一次内容改动 2026-07-16） | GitHub API（按路径过滤的提交记录） |
| 安装方式 | gh skills install github/awesome-copilot convert-pdf-to-md（需 GitHub CLI），或手动复制 skills/convert-pdf-to-md 整个目录到本地 skills 目录 |
仓库官方文档 |
2. 功能介绍与亮点
convert-pdf-to-md 把 PDF 文档转换成 Markdown，让 agent 能准确读取、总结、搜索或从中提取信息。核心能力：
- 隐式自动触发：只要用户提到、附上或引用一个
.pdf文件（报告、论文、发票、合同、扫描件），无论是否明说“转换”或“markdown”，都会触发；覆盖“读取”“总结”“比较”“分析”等各种自然语言表达。 - 真实图片提取：底层用 MarkItDown 做文本与表格转换，但 MarkItDown 原生只会给图片留一个截断的 base64 占位符——本技能额外调用 PyMuPDF 把 PDF 中的真实图片提取为独立文件，写入
<name>/img/目录，并在 Markdown 末尾以“Extracted Images”章节按页归类呈现。 - 批量与文件夹模式：支持单文件或整个文件夹（含
--recursive递归子文件夹）批量转换，单个文件失败不影响批内其他文件。 - 多文件类型协同：当用户引用的文件夹里混有
.pdf/.docx/.xlsx时，会自动一并调用同仓库的姊妹技能 convert-word-to-md、convert-excel-to-md，避免漏转某种格式。 - 完整故障排查表：SKILL.md 附带按报错信息定位原因与修复方式的对照表，覆盖依赖缺失、路径错误、扫描件无文字层等常见场景。
3. 适用场景
固定分类：文档与办公自动化
适合需要 agent 读取并分析 PDF 内容、但 agent 本身不擅长直接解析 PDF 二进制格式的场景：研究人员批量摘要论文、行政人员整理合同与发票、分析师从报告中提取数据表格等。受益对象是任何会把 PDF 丢给 Claude Code / Codex 等 Coding Agent 处理的初中级用户，装好之后不需要额外指令，agent 遇到 PDF 会自动先转换再分析。
分类判定：文档与办公自动化｜依据：manual/08 规则 B——核心动作是把 PDF 内容原样换成 Markdown 形态，信息基本守恒，不产出新的分析结论｜最近邻：pdf-anthropics-skills(文档与办公自动化)、markdown-exporter(文档与办公自动化)、anydoc(文档与办公自动化)｜一致
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持——标准 Agent Skills 格式（SKILL.md + YAML front matter），复制到
.claude/skills/目录即可使用。 - Codex：✅ 支持——仓库文档明确技能遵循开放的 Agent Skills 规范，Codex CLI 官方文档同样构建在该规范之上。
- OpenClaw：未验证。
- Hermes Agent：未验证。
5. 推荐理由
多数“文档转 Markdown”类技能要么只做纯文本提取、要么把图片扔成不可用的占位符，convert-pdf-to-md 把这两个短板都补上了：一次性 pip 安装两个开源依赖后即可离线运行，无需任何付费 API 或联网；触发描述专为“用户没说要转换”的自然场景设计，减少了用户手动调用的心智负担；批量模式与姊妹技能协同让“整理一个文件夹的混合文档”这种真实工作场景一次到位。对经常需要把 PDF 报告、论文、合同喂给 agent 处理的用户，这是一个轻量、可审计、零成本的前置转换工具。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | GitHub 官方运营的合集仓库出品；仓库整体 3.8 万星属整个合集，不代表本技能自身热度，该子技能自身尚无独立于合集之外的第三方热度证据 |
| 可用性 | 8 | 需一次性 pip install -r scripts/requirements.txt 安装 MarkItDown 与 PyMuPDF，配有独立 setup 文档与验证命令；SKILL.md 含完整故障排查表；最近一次内容改动在近 3 个月维护窗口内 |
| 安全性 | 9 | 见下方检查清单，无扣分项 |
安全检查清单：
① Shell 命令执行——仅在本地运行随附的 Python 脚本，读写范围限于用户指定的 PDF 文件/文件夹及其同级输出目录，无提权或系统级操作。 ② 联网外发——无，MarkItDown 与 PyMuPDF 均为本地库，转换过程不发起任何网络请求。 ③ API Key/凭据——不需要。 ④ 可疑指令——通读 SKILL.md 与故障排查表未发现夹带无关内容或隐蔽指令。 ⑤ 作者/组织信誉——GitHub 官方合集仓库，提交者为具名贡献者，PR 记录含 CI linter 拦截与多轮修复，显示有真实代码审查流程。 ⑥ License——MIT（仓库级），明确。 ⑦ 最近维护——最近一次内容改动距今约一个月，在半年维护窗口内。
综合评分 = (7+8+9)/3 = 8.0
7. 跟同类 Skills 相比的优势
| 竞品 | 定位 | 与本技能的差异 |
|---|---|---|
| pdf（Anthropic 官方 skill） | 通用 PDF 工具箱：读取提取、OCR 扫描件识别、合并拆分加密、表单填写、从零生成 PDF | 功能覆盖远超本技能，但也更重；本技能只做单一动作“PDF → 可分析 Markdown”，依赖更轻（仅两个 pip 包），并会把真实图片提取为独立文件而非占位符 |
| anydoc | 一条命令覆盖 20 余种文档格式（含 PDF/Word/Excel/PPT/RTF/EPUB 等），npx 零安装 | 格式覆盖面远大于本技能（仅 PDF）；本技能在 PDF 场景下额外做 PyMuPDF 驱动的真实图片提取，且触发描述专为“用户未明说转换”的隐式场景设计 |
| markdown-exporter | 把 Markdown 转成 PPT/Word/PDF 等十余种输出格式，服务内容发布场景 | 方向相反——它是“Markdown 转出去”，本技能是“外部文档转进来”供 agent 读取，两者互补而非竞争 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。仓库官方展示页面（awesome-copilot.github.com）提供功能与安装说明，未展示安装量或评分类数据。
9. 安装使用方式
渠道一（GitHub CLI，推荐）：
gh skills install github/awesome-copilot convert-pdf-to-md渠道二（手动复制）：将仓库 skills/convert-pdf-to-md/ 整个目录（含 SKILL.md、scripts/、references/）复制到本地 agent 的 skills 目录下。
安装后注意：首次使用前需执行一次性环境准备（同一环境只需做一次，不必每次转换都做）：
python -m pip install -r scripts/requirements.txt可用以下命令验证依赖是否安装成功：
python -c "from markitdown import MarkItDown; import fitz; print('markitdown + pymupdf OK')"无需重启 agent；环境准备好之后，agent 下次识别到 .pdf 文件即会自动触发转换。
10. 注意事项
- 仅支持
.pdf格式；不支持 OCR——扫描件（无文字层）转换后正文可能为空，但图片仍会被提取。 - 因 MarkItDown 的 PDF 文本没有可靠的页内定位锚点，图片统一放在文档末尾的“Extracted Images”章节，而非嵌入正文对应位置。
- 需要本地 Python 3.10+ 环境并完成一次性 pip 依赖安装；纯托管、无法执行 pip 安装的受限沙箱环境可能无法使用。
- 跨 Agent 兼容性目前仅确认 Claude Code / Codex 基于同一开放格式原生支持，OpenClaw 与 Hermes Agent 尚未实机验证。