---
name: markitdown-skill
description: 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.
---

# 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
- Python 3.10 or higher

### Installation

Install MarkItDown with all optional dependencies:

```bash
pip install 'markitdown[all]'
```

Or install with specific format support only:

```bash
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):**
```bash
python scripts/convert_file.py path/to/file.pdf
```

**Convert and save to file:**
```bash
python scripts/convert_file.py path/to/file.pdf -o output.md
```

**Batch convert a directory:**
```bash
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:

```python
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