pdf-convert 是一个文档转换技能，目标是让用户通过一个入口完成 PDF 与 Markdown 之间的双向转换：脚本 scripts/convert.cjs 配合 --to 参数选择方向，--to markdown 表示 PDF 转 Markdown，--to pdf 表示 Markdown 转 PDF。--to 为必填项，没有默认方向，缺失或未知取值时会打印有效方向并以退出码 1 结束，避免在方向猜错时静默产错结果。
主要能力
PDF 转 Markdown：自动检测 PDF 首页是否存在可提取文本，有则用原生方式快速提取，没有则报告该文档疑似扫描件。支持基本表格结构保留，纯 JavaScript 实现，无系统依赖。
Markdown 转 PDF：代码块使用 highlight.js 做语法高亮，支持用 --css 覆盖内置样式表；检测到系统 Chrome/Chromium 时直接使用，否则首次运行可能下载 Chromium（约 150MB）。支持 YAML frontmatter 提供标题与元数据。默认样式为 Georgia 衬线正文字体、Consolas/Monaco 等宽代码字体、2cm 页边距、代码块背景高亮、表格边框与隔行变色。
依赖与安装
两个方向各自有独立的 package.json，安装互不影响：PDF 转 Markdown 依赖 @opendocsg/pdf2md 与 pdfjs-dist，需 Node.js >= 18；Markdown 转 PDF 依赖 md-to-pdf 与 gray-matter，运行时版本范围见 to-pdf/package.json。安装前可用 createRequire 探测所选方向的依赖是否就绪，只安装缺失部分：
PDF -> Markdown
cd .claude/skills/pdf-convert/to-markdown npm install
Markdown -> PDF
cd .claude/skills/pdf-convert/to-pdf npm install
使用方式
PDF -> Markdown（自动检测原生文本或扫描件）
node .claude/skills/pdf-convert/scripts/convert.cjs --to markdown --input ./document.pdf
指定输出路径并强制原生模式
node .claude/skills/pdf-convert/scripts/convert.cjs --to markdown -i ./doc.pdf -o ./out.md --mode native
Markdown -> PDF
node .claude/skills/pdf-convert/scripts/convert.cjs --to pdf --input ./README.md
Markdown -> PDF 并使用自定义 CSS
node .claude/skills/pdf-convert/scripts/convert.cjs --to pdf -i ./doc.md --css ./my-style.css
--to=markdown 与 --to markdown 等价。其他参数会原样传给所选方向的转换器，因此每个方向保留各自独立的 CLI 选项：Markdown 方向支持 --input/-i（必填）、--output/-o（默认 {input}.md）、--mode/-m（auto、native、ocr，默认 auto）、--help/-h；PDF 方向支持 --input/-i（必填）、--output/-o（默认 {input}.pdf）、--css/-c、--no-highlight、--help/-h。
转换模式（--to markdown）
auto 为默认模式，检查首页是否有可提取文本，有则原生提取，否则报告疑似扫描件；native 为快速直接文本提取，适合带可选中文本的 PDF；ocr 模式当前不支持，转换器直接返回失败，安装可选 OCR 包也无法启用。
输出与限制
成功时返回 JSON，包含 success、input、output 以及统计信息（PDF 转 Markdown 返回 pages 与 mode，Markdown 转 PDF 返回 pages）；失败时返回 { "success": false, "error": "..." } 并以退出码 1 结束。已知限制包括：复杂多栏版式可能无法保留结构、扫描版 PDF 无法转写、数学公式可能转换不完美、大文档转 PDF 可能占用较多内存，建议拆分输入。
适用场景
适合将带可选中文本的说明文档、README 等 PDF 提取为 Markdown 以便编辑或入库，也适合把 Markdown 笔记、技术文档渲染为带代码高亮的 PDF 分发。需要 OCR 的扫描件不在其能力范围内。
排错与测试
Markdown 转 PDF 找不到 Chrome 时会自动下载 Chromium，可设置 PUPPETEER_SKIP_DOWNLOAD=1 阻止；缺依赖时错误信息会给出对应方向精确的 cd … && npm install 命令；字体不一致时可用 @font-face 内嵌 base64 字体。测试命令为：
cd .claude/skills/pdf-convert && node tests/dispatcher.test.cjs cd .claude/skills/pdf-convert/to-markdown && node tests/run-tests.cjs cd .claude/skills/pdf-convert/to-pdf && node tests/run-tests.cjs
该技能在 Windows、macOS 与 Linux 上均可用。在 Codex 中通过 $skill-name 加载注册的 .agents/skills/<name>/SKILL.md 并执行。