name: skill-document-converter 描述: 文档转换路由，支持双重调用 allowed-tools: Task

文档转换技能

这是一个薄包装器，将文档转换委托给 document-converter-agent 子代理。

上下文指针

参考（不要提前加载）：

路径：.claude/context/core/formats/subagent-return.md
目的：返回验证
加载时机：仅当子代理执行时

注意：此技能是一个薄包装器。上下文由委托的代理加载，而非此技能。

触发条件

此技能在以下情况激活：

直接调用

用户显式运行 /convert 命令
用户在对话中请求文件格式转换

隐式调用（在任务执行期间）

当实施代理遇到以下任何模式时：

计划步骤语言模式：

“从 [文件].pdf 提取文本”
“从 [文件] 提取内容”
“将 [文件] 转换为 markdown”
“将 [文件] 转换为 PDF”
“从 [文档/文件] 生成 PDF”
“从 [文件].docx 读取内容”
“创建 [文件] 的 PDF 版本”
“解析 [文件].pdf 以获取内容”
“导入 [文件] 内容”

文件扩展名检测：

源文件扩展名：.pdf、.docx、.xlsx、.pptx、.html
目标提及：“markdown”、“.md”、“PDF”、“.pdf”

任务描述关键词：

“文档转换”
“格式转换”
“从 PDF 提取”
“生成 PDF”

不应触发的情况

不要为以下情况调用：

读取源代码文件（.py、.js、.lean 等）
查看图像而不提取内容
不涉及格式转换的操作
文件已处于目标格式

执行

1. 输入验证

验证必需输入：

source_path - 必须提供且文件必须存在
output_path - 可选，默认基于源目录和适当扩展名

# 验证源文件存在
if [ ! -f "$source_path" ]; then
  return error "源文件未找到: $source_path"
fi

# 如果未提供输出路径，则确定之
if [ -z "$output_path" ]; then
  source_dir=$(dirname "$source_path")
  source_base=$(basename "$source_path" | sed 's/\.[^.]*$//')
  source_ext="${source_path##*.}"

  # 推断目标扩展名
  case "$source_ext" in
    pdf|docx|xlsx|pptx|html) output_path="${source_dir}/${source_base}.md" ;;
    md) output_path="${source_dir}/${source_base}.pdf" ;;
    *) return error "无法为 .$source_ext 推断输出格式" ;;
  esac
fi

2. 上下文准备

准备委托上下文：

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

3. 调用子代理

关键：您必须使用 Task 工具来生成子代理。

此技能的前置元数据中的 agent 字段指定目标：document-converter-agent

必需的工具调用：

工具: Task（非 Skill）
参数:
  - subagent_type: "document-converter-agent"
  - prompt: [包括 source_path、output_path、metadata]
  - description: "将 {source_path} 转换为 {output_path}"

不要使用 Skill(document-converter-agent) - 这将失败。代理位于 .claude/agents/，而非 .claude/skills/。 Skill 工具只能调用 .claude/skills/ 中的技能。

子代理将：

检测可用转换工具
根据文件扩展名确定转换方向
使用适当工具执行转换
验证输出存在且非空
返回标准化 JSON 结果

4. 返回验证

验证返回匹配 subagent-return.md 架构：

状态为其中之一：已转换、已提取、部分、失败
摘要非空且少于 100 个令牌
存在输出文件路径的工件数组
元数据包含 session_id、agent_type、委托信息

5. 返回传播

将已验证的结果返回给调用者，不作修改。

返回格式

请参阅 .claude/context/core/formats/subagent-return.md 获取完整规范。

预期成功返回：

{
  "status": "converted",
  "summary": "使用 markitdown 成功将 document.pdf 转换为 document.md",
  "artifacts": [
    {
      "type": "implementation",
      "path": "/绝对路径/到/document.md",
      "summary": "已转换的 markdown 文档"
    }
  ],
  "metadata": {
    "session_id": "sess_...",
    "agent_type": "document-converter-agent",
    "delegation_depth": 1,
    "delegation_path": ["协调器", "转换", "skill-document-converter", "document-converter-agent"],
    "tool_used": "markitdown"
  },
  "next_steps": "审查转换后的文档"
}

错误处理

输入验证错误

如果源文件未找到，立即返回失败状态。

不支持格式

返回失败状态，并附上关于支持格式的清晰信息。

子代理错误

直接传递子代理的错误返回。

工具不可用

返回失败状态，并附上安装说明。