MarkItDown Skill
Overview
MarkItDown is a lightweight Python utility by Microsoft that converts various file formats into Markdown. It is specifically designed for LLM and text analysis pipelines, preserving document structure such as headings, lists, tables, and links.
This skill enables AI agents to process non-text files by converting them to Markdown, which is the most token-efficient format for LLM consumption.
When to Use This Skill
Use this skill when:
- The user uploads a file that is not plain text (PDF, DOCX, XLSX, PPTX, JPG, PNG, MP3, etc.)
- The user asks to "read", "extract", "analyze", or "summarize" a document, spreadsheet, presentation, or image
- The user wants to convert a file to Markdown format
- The user needs to process multiple files and extract their text content
Supported File Formats
| Format |
Extension |
Notes |
| PDF |
.pdf |
Extracts text, preserves structure |
| Microsoft Word |
.docx, .doc |
Preserves headings, lists, tables |
| Microsoft Excel |
.xlsx, .xls |
Converts sheets to Markdown tables |
| Microsoft PowerPoint |
.pptx |
Extracts slide content |
| Images |
.jpg, .jpeg, .png, .gif, .bmp |
Extracts EXIF metadata and OCR text |
| Audio |
.wav, .mp3 |
Extracts metadata and transcribes speech |
| HTML |
.html, .htm |
Converts to clean Markdown |
| Plain Text |
.csv, .json, .xml, .txt |
Converts with formatting |
| ZIP |
.zip |
Traverses and converts contents |
| YouTube URL |
URL |
Fetches subtitles/transcripts |
| EPub |
.epub |
E-book conversion |
For detailed format information, load references/supported-formats.md.
Prerequisites
Python Version
Installation
Install MarkItDown with all optional dependencies:
pip install 'markitdown[all]'
Or install with specific format support only:
pip install 'markitdown[pdf,docx,xlsx,pptx]'
The bundled script scripts/convert_file.py will automatically check for installation and prompt if missing.
Workflow: Converting a File to Markdown
Step 1: Identify the File and Goal
Determine:
- What file(s) need to be converted?
- What is the target output? (stdout, file, or in-memory string)
- Is OCR or image description needed? (requires LLM client)
Step 2: Convert Using the Script
Basic conversion (output to stdout):
python scripts/convert_file.py path/to/file.pdf
Convert and save to file:
python scripts/convert_file.py path/to/file.pdf -o output.md
Batch convert a directory:
python scripts/batch_convert.py path/to/documents/ -o path/to/output/
Step 3: Use the Markdown Output
The converted Markdown can be:
- Passed directly to the LLM for analysis/summarization
- Saved to disk for later use
- Further processed or split into chunks
Python API Usage
For programmatic integration within the agent's Python environment:
from markitdown import MarkItDown
# Basic conversion
md = MarkItDown()
result = md.convert("document.pdf")
print(result.markdown)
# With LLM for image description (requires OpenAI or compatible client)
from openai import OpenAI
md = MarkItDown(
llm_client=OpenAI(),
llm_model="gpt-4o"
)
result = md.convert("presentation.pptx")
print(result.markdown)
Important Notes
Security
- MarkItDown performs I/O with the same permissions as the current process
- In untrusted environments (e.g., web services), never pass raw user input directly to MarkItDown
- Restrict file paths, URI protocols, and network targets
- Use the narrowest API possible:
- Local files only:
convert_local()
- Custom network requests: fetch with
requests, then convert_response()
- Full control: open stream, then
convert_stream()
LLM Image Description
- To describe images within documents (PDF, PPTX, images), provide an
llm_client
- Without LLM, images are skipped or only EXIF metadata is extracted
- Supported LLM clients: OpenAI-compatible APIs
Azure Integration (Optional)
- Azure Document Intelligence: Enhanced OCR and layout analysis
- Azure Content Understanding: Multi-modal support (documents, images, audio, video)
- Requires Azure endpoint and credentials
- Load
references/integration-guide.md for Azure setup details
Resources
scripts/convert_file.py — Convert a single file to Markdown
scripts/batch_convert.py — Batch convert files in a directory
references/supported-formats.md — Detailed format support and notes
references/integration-guide.md — Integration patterns, Azure setup, plugin usage
1---2name: markitdown-skill3description: Convert various file formats (PDF, Excel, Word, PowerPoint, images, audio, HTML, etc.) to Markdown using Microsoft's MarkItDown tool. This skill should be used when the user uploads a non-text file or asks to extract text/content from documents, spreadsheets, presentations, images, or audio files. It enables AI agents to read and understand file contents by converting them into LLM-friendly Markdown format. Trigger when file conversion to text or markdown is needed.4metadata:5 source: https://skillmd.com/skills/xuanz54/markitdown-skill6---78# MarkItDown Skill910## Overview1112**MarkItDown** is a lightweight Python utility by Microsoft that converts various file formats into Markdown. It is specifically designed for LLM and text analysis pipelines, preserving document structure such as headings, lists, tables, and links.1314This skill enables AI agents to process non-text files by converting them to Markdown, which is the most token-efficient format for LLM consumption.1516## When to Use This Skill1718Use this skill when:19- The user uploads a file that is not plain text (PDF, DOCX, XLSX, PPTX, JPG, PNG, MP3, etc.)20- The user asks to "read", "extract", "analyze", or "summarize" a document, spreadsheet, presentation, or image21- The user wants to convert a file to Markdown format22- The user needs to process multiple files and extract their text content2324## Supported File Formats2526| Format | Extension | Notes |27|--------|-----------|-------|28| **PDF** | `.pdf` | Extracts text, preserves structure |29| **Microsoft Word** | `.docx`, `.doc` | Preserves headings, lists, tables |30| **Microsoft Excel** | `.xlsx`, `.xls` | Converts sheets to Markdown tables |31| **Microsoft PowerPoint** | `.pptx` | Extracts slide content |32| **Images** | `.jpg`, `.jpeg`, `.png`, `.gif`, `.bmp` | Extracts EXIF metadata and OCR text |33| **Audio** | `.wav`, `.mp3` | Extracts metadata and transcribes speech |34| **HTML** | `.html`, `.htm` | Converts to clean Markdown |35| **Plain Text** | `.csv`, `.json`, `.xml`, `.txt` | Converts with formatting |36| **ZIP** | `.zip` | Traverses and converts contents |37| **YouTube URL** | URL | Fetches subtitles/transcripts |38| **EPub** | `.epub` | E-book conversion |3940For detailed format information, load `references/supported-formats.md`.4142## Prerequisites4344### Python Version45- Python 3.10 or higher4647### Installation4849Install MarkItDown with all optional dependencies:5051```bash52pip install 'markitdown[all]'53```5455Or install with specific format support only:5657```bash58pip install 'markitdown[pdf,docx,xlsx,pptx]'59```6061The bundled script `scripts/convert_file.py` will automatically check for installation and prompt if missing.6263## Workflow: Converting a File to Markdown6465### Step 1: Identify the File and Goal6667Determine:68- What file(s) need to be converted?69- What is the target output? (stdout, file, or in-memory string)70- Is OCR or image description needed? (requires LLM client)7172### Step 2: Convert Using the Script7374**Basic conversion (output to stdout):**75```bash76python scripts/convert_file.py path/to/file.pdf77```7879**Convert and save to file:**80```bash81python scripts/convert_file.py path/to/file.pdf -o output.md82```8384**Batch convert a directory:**85```bash86python scripts/batch_convert.py path/to/documents/ -o path/to/output/87```8889### Step 3: Use the Markdown Output9091The converted Markdown can be:92- Passed directly to the LLM for analysis/summarization93- Saved to disk for later use94- Further processed or split into chunks9596## Python API Usage9798For programmatic integration within the agent's Python environment:99100```python101from markitdown import MarkItDown102103# Basic conversion104md = MarkItDown()105result = md.convert("document.pdf")106print(result.markdown)107108# With LLM for image description (requires OpenAI or compatible client)109from openai import OpenAI110111md = MarkItDown(112 llm_client=OpenAI(),113 llm_model="gpt-4o"114)115result = md.convert("presentation.pptx")116print(result.markdown)117```118119## Important Notes120121### Security122- MarkItDown performs I/O with the same permissions as the current process123- In untrusted environments (e.g., web services), **never** pass raw user input directly to MarkItDown124- Restrict file paths, URI protocols, and network targets125- Use the narrowest API possible:126 - Local files only: `convert_local()`127 - Custom network requests: fetch with `requests`, then `convert_response()`128 - Full control: open stream, then `convert_stream()`129130### LLM Image Description131- To describe images within documents (PDF, PPTX, images), provide an `llm_client`132- Without LLM, images are skipped or only EXIF metadata is extracted133- Supported LLM clients: OpenAI-compatible APIs134135### Azure Integration (Optional)136- Azure Document Intelligence: Enhanced OCR and layout analysis137- Azure Content Understanding: Multi-modal support (documents, images, audio, video)138- Requires Azure endpoint and credentials139- Load `references/integration-guide.md` for Azure setup details140141## Resources142143- `scripts/convert_file.py` — Convert a single file to Markdown144- `scripts/batch_convert.py` — Batch convert files in a directory145- `references/supported-formats.md` — Detailed format support and notes146- `references/integration-guide.md` — Integration patterns, Azure setup, plugin usage