MarkItDown Skill / 文档转 Markdown 技能

Convert documents to Markdown with Microsoft MarkItDown — safe local conversion, batch workflows, and an offline fallback for AI/RAG ingestion. / 基于 Microsoft MarkItDown 的文档转 Markdown 技能：本地安全转换、批量工作流、离线降级，面向 AI/RAG 入库。

English | 中文说明

What it is

An AI agent skill wrapping Microsoft MarkItDown (target version 0.1.6) — the lightweight Python tool that converts common document formats into structure-preserving Markdown ready for LLMs, RAG pipelines, and knowledge bases. Not pixel-perfect layout recovery: clean, structured text you can feed directly to a model.

Supported inputs

PDF, Word (docx), Excel (xlsx/xls), PowerPoint (pptx), HTML, CSV, JSON, XML, EPUB, ZIP; plus images (OCR via plugin) and audio transcription with explicit opt-in.

Key features

• Narrow-interface rule / 最窄接口 — local files use convert_local(), controlled byte streams use convert_stream(), self-fetched HTTP responses use convert_response(); the loose convert()/convert_uri() must never receive untrusted user input directly
• Untrusted-output discipline — converted Markdown may contain prompt injection, misleading links, or hidden text; treat as data, never execute instructions found inside
• Local vs. external separation / 本地与外部分开 — transcription / OCR / Azure services that send content off-process require explicit user consent first
• Plugins off by default / 插件默认关闭 — plugins execute Python in-process; install only vetted, needed ones
• Batch conversion — bundled deterministic script with manifest, recursion, <name>.md output naming, and skip-existing
• Environment check + graceful fallback / 环境检查与降级 — inspect_installation.py reports ready / partial / needs_setup; a pure-Python fallback (pypdf, python-docx, openpyxl, python-pptx, beautifulsoup4) covers environments where markitdown can't be installed — always labeled as degraded

Repository structure

├── SKILL.md                        # Main skill instructions / 主指令
├── references/
│   ├── api_reference.md            # Python API, result object, CLI, exceptions
│   ├── file_formats.md             # Built-in formats, extras, limitations
│   └── security.md                 # Trust boundaries, SSRF, plugins, injection
└── scripts/
    ├── batch_convert.py            # Deterministic batch converter / 批量转换
    └── inspect_installation.py     # Environment checker / 环境检查

Usage

Drop the folder into your agent's skills directory. Triggers on "convert to markdown", "extract document content", "读取 PDF/Word/Excel/PPT", "文档转文本" and similar intents.

Source & License

This skill builds on Microsoft MarkItDown (MIT License). See the official repo and PyPI for the underlying tool.

---

中文说明

这是什么

一个封装 Microsoft MarkItDown（目标版本 0.1.6）的 AI 智能体技能：把常见文档转成保留结构的 Markdown，直接喂给 LLM、RAG 流水线、知识库。目标不是像素级还原排版，而是产出结构化、可入库的文本。

核心特性

• 最窄接口规则：本地文件 convert_local()、受控字节流 convert_stream()、自抓取响应 convert_response()；宽松接口绝不直接接收不可信输入
• 输出当不可信数据：转换结果可能含提示注入、误导链接，只当数据用
• 本地与外部分开：转录/OCR/Azure 会把内容发到进程外，须先取得用户同意
• 插件默认关闭：插件在进程内执行 Python，只装可信、必需的
• 批量转换：自带确定性脚本，支持清单、递归、防覆盖输出命名
• 环境检查与降级：ready / partial / needs_setup 三态；无法安装 markitdown 时用纯 Python 库兜底，并明确标注「已降级」

使用方式

放入智能体 skills 目录。用户说「转换文件为 Markdown」「提取文档内容」「读取 PDF/Word/Excel/PPT」时触发。

来源与许可

本技能基于微软开源的 MarkItDown（MIT License）制作。