前言¶

做知识库或 RAG 流水线时，常见卡点不是检索模型，而是入库前的「物料形态」：PDF、Office、表格、扫描件、压缩包混在一起，各写一套解析脚本，维护成本高，输出结构也不统一。若希望 Agent 在对话里按固定流程完成「检测环境 → 转换 → 清洗 → 校验」，并把结果写成 UTF-8 Markdown，可以接入 SkillHub 上的 make-to-markdown（包名 @indiv-ebandao/make-to-markdown，当前版本 v1.0.11）。下面介绍它的定位、能力与安装用法。

这是什么¶

make-to-markdown 是面向 RAG 场景的 Markdown 物料生成 Skill：底层使用 markitdown，通过技能自带的 scripts/convert.py 作为统一入口，完成依赖检测、格式转换、失败降级与后置清洗。Skill 元数据标注维护方为「智慧半岛」，在 SkillHub 分类为 knowledge-management（知识管理）；页面展示评分约 98663、下载约 484 次（数据来自 SkillHub 列表信息，以页面实时为准）。

与在对话里临时执行 uvx markitdown 相比，该 Skill 强调：旧版 .doc/.ppt 预处理、按操作系统选择 Office COM 或 LibreOffice、批量任务的 Init-Step-Poll 防卡死协议，以及转换后的 V1–V6 质量检查。

官方入口：

• SkillHub 页面：https://www.skillhub.cn/skills/indiv-ebandao/make-to-markdown
• API 标识页：https://api.skillhub.cn/user_741dc82b/make-to-markdown

核心功能¶

以下能力均来自 Skill 包内 SKILL.md / QUICKSTART.md 与 SkillHub 简介，安装后由 Agent 按 Skill 指令执行。

支持的输入格式¶

可将下列类型转为 Markdown（含扩展能力说明）：

旧格式与跨平台¶

• .doc / .ppt 会先预处理为 .docx / .pptx：Windows 上优先 Word / PowerPoint COM，否则尝试 soffice --headless（LibreOffice）。
• 启动时通过 scripts/platform_detect.py 检测 OS 与本地能力，再选择执行路径；Skill 声明 Windows / Linux / macOS 均为 full 支持。

转换管线¶

单次调用 scripts/convert.py 时，内部流程概括为：

(.doc/.ppt) → 预处理 → 依赖检测与安装 → markitdown →（失败）原生降级 → 后置清洗 → 输出

• markitdown 失败时降级：例如 .docx 用 python-docx、表格用 openpyxl、演示文稿用 python-pptx。
• 后置清洗（内联在 convert 中）：去水印/页码、标题层级修复、表格分隔符补全、可选文档摘要等；极端场景可单独调用 scripts/post_clean.py。

Agent 触发方式¶

在支持 Skills 的客户端中，可用自然语言触发，Skill 描述的触发词包括：转 Markdown、转换文档、markitdown、文档转 md、批量转换。当需要把上述多类文件统一成知识库「通用语言」Markdown 时使用。

约束（使用前应知晓）¶

Skill 将下列规则标为红线，Agent 应遵守：

1. 源文件只读，不修改原件；转换经 scripts/convert.py，不裸调 markitdown / uvx markitdown。
2. -o 目标文件已存在时需用户确认，禁止静默覆盖。
3. 加密文档检测到后终止，需用户先解密。
4. 旧格式且 COM、LibreOffice 均不可用时暂停，提示安装 Office 或 LibreOffice。
5. 转换全程本地执行，不上传文档到外部 API。

OpenClaw 类环境元数据要求本机具备 uv 与 python。

安装与启用¶

SkillHub 推荐让 Agent 按安装说明文档操作，或在本机用 CLI 安装到当前 Agent 的 skills 目录。

方式一：按 SkillHub 官方安装说明（推荐给 Agent）¶

在对话中发送 SkillHub 页面提供的提示，或明确要求 Agent 阅读并执行：

请根据 https://skillhub.cn/install/skillhub.md，安装 `@indiv-ebandao/make-to-markdown`。

skillhub.md 要点：

1. 检查是否已有 CLI：command -v skillhub && skillhub --version
2. 未安装时可执行（完整安装含默认 Skill）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

仅 CLI：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

3. 安装技能时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认 ./skills/ 可能不会被加载。常用路径示例：

示例：

skillhub install @indiv-ebandao/make-to-markdown --dir ~/.cursor/skills/

（将路径换成你实际使用的 Agent 目录。）

方式二：npm 生态的 skillhub-cli¶

GitHub 上的 skillhub-cli 支持不全局安装直接拉取 Skill：

npx skillhub-cli install @indiv-ebandao/make-to-markdown

全局安装 CLI 后也可使用 skillhub install <skill-name>；具体落盘路径以 CLI 文档为准（例如 ~/.claude/skills/、~/.codex/skills/）。

前置依赖（跑转换脚本）¶

快速上手文档要求本机有 uv（用于 markitdown 工具链），例如 Windows PowerShell：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
uv --version

安装 Skill 后，进入技能目录，可做一次存在性检查：

python -c "from pathlib import Path; assert Path('scripts/convert.py').exists()"

典型用法¶

安装完成后，Agent 或直接在本机技能目录执行以下命令（路径替换为你的文件）。

单文件转换¶

cd path/to/make-to-markdown

python scripts/convert.py 你的文件.docx -o 输出.md

最小示例（默认输出命名）：

python scripts/convert.py input.docx

查看技能版本：

python scripts/convert.py --version

批量转换¶

确认源目录、输出目录、文件数量与 --ext 过滤后再执行：

python scripts/batch_convert.py ./源目录/ ./输出目录/ --ext .pdf .docx --clean

失败项会写入输出目录下的 _conversion_errors.log（或等价失败清单）。

旧版 Office 与论文入库示例¶

# .doc 自动 COM 或 LibreOffice 预处理后转换
python scripts/convert.py 旧文档.doc -o 旧文档.md

# PDF 报告
python scripts/convert.py paper.pdf -o paper.md

可选：单独后置清洗¶

python scripts/post_clean.py output.md --check-only

转换成功后的反馈模板会包含状态、转换方式（markitdown 或原生降级）、标题与表格统计及输出绝对路径。

适用场景与注意¶

适合谁

• 需要把企业内网资料、项目文档、论文 PDF、混合格式资料库批量变成 Markdown，再接入向量库或全文检索的团队。
• 已在 Cursor / Claude Code / Codex 等环境使用 Skills，希望用固定红线与检查表约束 Agent，避免随手调用 markitdown 导致依赖不全或输出未清洗。

限制与坑

• .doc / .ppt 在无 Office COM 且无 LibreOffice 时无法自动预处理，需先安装其一。
• 加密 Office/PDF 不会反复重试，需用户解密后再跑。
• 批量任务应指定 --ext，并在 Init 阶段确认路径与覆盖策略；大目录、网络盘、含 OCR/音频的慢任务应按 Skill 的 Init → Step → Poll 分步执行。
• 可选依赖可由 convert.py 自动安装；也可参考 Skill 文档一次性安装 markitdown 及 extras，例如：

uv tool install markitdown --with python-docx --with openpyxl --with python-pptx --with pypdf --with xlrd --with ebooklib

完成转换后，Skill 要求做 V1–V6 检查（文件非空、UTF-8、水印残留、标题层级、表格分隔符、批量数量一致等），未通过应走异常处理流程而非直接宣称入库成功。

结尾¶

make-to-markdown 把 markitdown 与预处理、降级、清洗、校验收成一条可重复的 RAG 物料流水线，并通过 Skill 约束 Agent 的执行边界。若你正在统一知识库文档形态，可从 SkillHub 安装 @indiv-ebandao/make-to-markdown，用 scripts/convert.py 做单文件验证后再做批量。

• 页面：https://www.skillhub.cn/skills/indiv-ebandao/make-to-markdown
• API：https://api.skillhub.cn/user_741dc82b/make-to-markdown