skill-document-converter（文档转换技能Skill）Skill 是什么？

文档转换技能Skill：让 PDF、Word、Excel 一键变成可用 Markdown 与 PDF

一个“薄包装器”，而非重型工具：该技能本身不做转换，而是把任务精准转交给 document-converter-agent 子代理执行，职责单一、边界清晰。
双通道触发：既能用 /convert 命令显式调用，也能在任务执行过程中被自动识别（例如出现“从 PDF 提取文本”“生成 PDF”等意图）并接管。
输入校验 + 返回校验闭环：先验证源文件是否存在、自动推断输出路径，再校验子代理返回的 JSON 结构，保证结果可追溯。
有明确的“不该用”清单：读取源码文件、仅查看图片、文件已是目标格式等情况不触发，避免无效调用。
适合把“文档搬运”从人工操作变成流水线环节：减少复制粘贴、格式错乱与上下文丢失。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能中文名：文档转换技能Skill 技能英文名：skill-document-converter 技能ID：12895

它解决的问题很具体：在 AI 辅助的文档处理与开发流程中，PDF、Word（.docx）、Excel（.xlsx）、PPT（.pptx）、HTML 这些“人类格式”与 Markdown、PDF 这些“机器友好格式”之间始终存在断层。过去你要么手动复制粘贴、要么在多个命令行工具之间来回切换，格式一乱，后续的检索、摘要、代码生成全部受影响。这个技能把这些动作收敛成一个可被调用的路由入口。

一键安装的思路与步骤

该技能本质上是一个“路由层 + 委派层”的组合：技能负责识别意图、校验输入、发起委派；真正的转换能力位于被委托的 document-converter-agent 子代理中。因此安装的核心是“让技能与子代理同时在位”。

确认运行环境：需要具备支持技能（Skill）与子代理（Agent）机制的运行环境，且技能目录与代理目录结构已就绪（技能位于 .claude/skills/，代理位于 .claude/agents/）。具体目录规范与版本要求以官方说明为准。
检索并安装技能：在技能市场或技能库中以技能ID 12895 或英文名 skill-document-converter 检索，执行安装。安装命令、入口地址与是否收费以官方说明为准。
确认依赖代理存在：检查 .claude/agents/ 下是否存在 document-converter-agent。该技能依赖它完成实际转换，缺失时技能会返回失败并给出提示。
确认技能元数据中的 allowed-tools 包含 Task：这是关键前提。技能必须通过 Task 工具生成子代理，而不能用 Skill 工具去调用一个代理（后者会失败）。
验证是否生效：在对话中显式输入 /convert 命令，或直接说“把这个 PDF 转成 Markdown”。若技能被正确激活，你会看到它先校验源文件路径，再委派子代理，最后返回带 status、summary、artifacts 的结构化结果。若返回“源文件未找到”，说明技能已生效但路径有误；若完全没有反应，说明技能未被加载。

“一键安装”之所以能提升开发效率，关键在于它把“格式转换”从一个需要记忆工具、记忆参数、记忆输出位置的手工动作，变成了一个语义化意图——你只要描述目的，路由由技能完成。

该技能的主要功能和特点

双重调用机制：支持直接调用（用户显式运行 /convert，或在对话中请求文件格式转换）与隐式调用（实施代理在执行任务时识别到转换意图后自动接管）。
格式覆盖明确：源文件支持 .pdf、.docx、.xlsx、.pptx、.html；默认推断规则为“上述格式 → .md”，“.md → .pdf”。
智能路径推断：未提供 output_path 时，自动取源文件所在目录与文件名主干，按规则补上目标扩展名，避免用户手写路径。
严格的输入校验：源文件不存在时立即返回失败状态，不做无效委派。
工具自动探测：子代理会检测当前环境可用的转换工具，根据文件扩展名决定转换方向，再执行转换并验证输出存在且非空。
标准化返回结构：返回 status（已转换 / 已提取 / 部分 / 失败）、简短 summary、artifacts 工件数组、含 session_id 与 delegation_path 的 metadata，以及 next_steps 建议。
上下文按需加载：技能自身是薄包装器，参考文档（如返回校验规范）仅在子代理执行时才加载，不提前占用上下文。
明确的负向边界：读取 .py、.js、.lean 等源码，仅查看图片而不提取内容，以及文件本就处于目标格式时，不触发该技能。

与“随手找个转换工具”相比，它的差异化不在转换算法本身，而在流程纪律：触发条件可判定、输入可校验、返回可验证、错误可传递。

如何使用该技能？

以下为典型使用流程，可按步骤参考。

步骤 1：显式调用或自然语言触发

在对话中使用命令形式：

/convert

或直接描述意图，例如：“把 ./docs/report.pdf 转成 Markdown”。

步骤 2：技能校验输入

技能会检查 source_path 是否存在。若缺失或文件不存在，立即返回错误，例如：

源文件未找到: ./docs/report.pdf

步骤 3：输出路径自动推断（可覆盖）

若不指定 output_path，技能按规则推断：

源扩展名	默认目标
.pdf / .docx / .xlsx / .pptx / .html	同目录同名 `.md`
.md	同目录同名 `.pdf`
其他	返回“无法推断输出格式”错误

你也可以显式传入目标路径，例如把 report.pdf 转为 ./out/report.md。

步骤 4：委派子代理执行

技能通过 Task 工具发起委派，携带绝对路径与元数据：

{
  "source_path": "/绝对路径/到/source.pdf",
  "output_path": "/绝对路径/到/output.md",
  "metadata": {
    "session_id": "sess_{时间戳}_{随机数}",
    "delegation_depth": 1,
    "delegation_path": ["协调器", "转换", "skill-document-converter"]
  }
}

子代理随后探测工具、判定转换方向、执行转换、验证输出非空。

步骤 5：读取结构化返回

成功时形如：

{
  "status": "converted",
  "summary": "使用 markitdown 成功将 document.pdf 转换为 document.md",
  "artifacts": [
    {
      "type": "implementation",
      "path": "/绝对路径/到/document.md",
      "summary": "已转换的 markdown 文档"
    }
  ],
  "next_steps": "审查转换后的文档"
}

注意 tool_used 字段会记录实际使用的工具（上例中为 markitdown），便于复盘。

步骤 6：隐式调用场景

当你在任务计划中写下“从 spec.docx 读取内容”“创建 proposal 的 PDF 版本”“解析 data.pdf 以获取内容”这类指令时，实施代理会识别到计划步骤语言模式并自动激活该技能，你无需再单独发命令。

步骤 7：处理错误返回

源文件不存在 → 立即失败，修正路径后重试。
不支持格式 → 返回失败并提示支持的格式范围。
子代理出错 → 错误原样透传，按提示排查。
转换工具不可用 → 返回失败并附带安装说明，按说明补齐工具后重试。

同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
文档转换技能Skill（skill-document-converter）	AI 工作流内的转换路由层	意图识别 + 输入校验 + 委派子代理 + 结构化返回校验	需具备技能/代理机制环境，并安装配套子代理；具体安装入口以官方说明为准	AI 辅助的开发与文档流水线，需可追溯结果的批量转换	优势：触发条件清晰、返回可验证、双通道调用、边界明确；不足：依赖子代理与本地转换工具，脱离该生态不可用
markitdown 等开源转换库	通用文档转 Markdown 库	多格式解析为 Markdown	需自行安装依赖并编写调用代码	批量入库、知识库预处理	优势：轻量、可编程；不足：无意图识别与流程编排，需自己处理路径、校验与错误
Pandoc	通用文档格式转换器	数十种格式互转	需安装命令行工具、记忆参数组合	学术写作、发布流水线	优势：格式覆盖极广、成熟稳定；不足：参数复杂，PDF 相关能力受外部引擎影响，缺少 AI 侧路由
办公软件/在线转换服务	面向人的图形化转换	打开、另存、导出 PDF	几乎零门槛，多为点击操作	单次人工转换、临时需求	优势：直观；不足：难以嵌入自动化链路，批量与可追溯性弱，隐私与合规需评估

从对比可见，该技能并非要替代 Pandoc 或开源库，而是站在它们之上做调度与纪律：谁来判断“该转了”、谁来校验“转成功了”、谁来把结果结构化成下一步可消费的工件。

该技能的典型应用场景与实际体验情况

场景一：把外部 PDF 资料转成可检索的 Markdown（研究者 / 技术写作者） 痛点是拿到一份 PDF 白皮书后，想摘录、引用、二次加工，复制粘贴会丢标题层级与表格结构。使用方式是直接说“把 whitepaper.pdf 转成 markdown”，技能自动推断输出为其同目录同名 .md，子代理完成转换并返回工件路径。实际体验：上手难度低，不需要记参数；效果取决于源 PDF 的排版复杂度，扫描件类文档需注意是否会出现内容缺失；建议转换后先抽查标题层级与表格。

场景二：任务执行中隐式接管，生成交付物 PDF（项目执行者） 当任务计划里出现“创建 proposal 的 PDF 版本”时，实施代理识别到“生成 PDF”语言模式，技能自动激活并把 .md 转成 .pdf。实际体验：流程顺滑，不用中断主任务去单独跑一次转换；注意点在于 .md → .pdf 的排版效果依赖子代理探测到的转换工具，样式复杂时建议人工复核成品。

场景三：批量读取 Excel / PPT 内容做汇总（运营 / 数据分析支持） 源扩展名 .xlsx、.pptx 均在支持列表内，默认输出为 .md，便于后续喂给摘要或检索流程。实际体验：结构化程度因表结构而异，合并单元格、图表较多的文件转换后信息密度会下降；建议一次处理一个文件、逐个核对 status 字段（可能出现“部分”状态）。

场景四：工程化接入，作为流水线的一个环节（开发者） 通过稳定的返回结构（status、artifacts、metadata.session_id、delegation_path）判断成败并串联下一步。实际体验：可观测性好，失败原因区分了“输入校验错误”“不支持格式”“子代理错误”“工具不可用”四类，便于分别处理；需注意必须使用 Task 工具委派，误用 Skill 工具调用代理会直接失败。

该技能能为用户带来的价值

把“手工搬运”变成“一次声明”：过去一次格式转换要经历打开文件、复制、粘贴、修正格式、另存，现在一句意图即可完成，单次可节省数分钟，批量场景收益线性放大。
降低工具门槛：不必记住 Pandoc 的参数组合或各转换库的调用方式，技能已把“探测可用工具 + 判定转换方向 + 验证输出”封装好。
降低出错率：输入校验挡住了“文件根本不存在”的无效操作，返回校验挡住了“转换成功但文件为空”的假成功。
让结果可追溯：session_id、delegation_path、tool_used 让每一次转换都能回溯到“谁在什么时候用什么工具转了什么”，这在团队协作与审计场景中价值明显。
长期价值在于流程标准化：当转换成为稳定的、有明确触发条件与返回契约的环节，文档处理才能真正被纳入自动化流水线，而不是永远停留在人工补位。

常见问题 FAQ

Q1：这个技能怎么安装？装完怎么确认生效？ 以技能ID 12895 或英文名 skill-document-converter 在技能库中检索并安装，同时确认 .claude/agents/ 下存在 document-converter-agent 子代理。验证方式是执行 /convert 或直接描述“把某文件转成 Markdown”：若返回“源文件未找到”，说明技能已激活；若无任何反应，说明未被加载。具体安装入口与命令以官方说明为准。

Q2：它是收费的吗？ 技能详情中未包含定价信息，是否收费、是否有额度限制需以官方说明为准。需要注意的是，它依赖的底层转换工具（如 markitdown 等）由子代理探测，其安装与授权情况同样以官方说明为准。

Q3：为什么不直接用 Pandoc 或在线转换网站？ 单次临时转换，在线工具确实更快。但如果你需要“在任务里自动判断要不要转”“转完还要校验结果”“结果要能被后续步骤消费”，那缺的就不是转换算法，而是调度与契约。该技能补的正是这一层，底层仍可能调用同类工具。

Q4：哪些情况它不会触发？ 读取 .py、.js、.lean 等源码文件；仅查看图片而不提取内容；不涉及格式转换的操作；文件已处于目标格式。这些场景请勿调用，避免无效委派。

Q5：转换结果不理想怎么办？ 先看返回的 status 是否为“部分”，以及 tool_used 记录的实际工具。排版复杂的 PDF 或含图表较多的 Excel/PPT 转换后信息可能不完整，建议转换后人工抽查标题层级与表格；如提示“工具不可用”，按返回信息中的安装说明补齐工具后重试。