markitdown-skill

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

For detailed format information, load references/supported-formats.md.

Prerequisites

Python Version

• Python 3.10 or higher

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