Microsoft MarkItDown

Convert various document formats (PDF, Word, PowerPoint, Excel, images, audio, HTML, etc.) to Markdown using Microsoft's markitdown tool. Supports OCR, audio...

Security Scan

The skill's files and runtime instructions are consistent with a simple wrapper around the third‑party markitdown tool; nothing in the bundle requests unrelated credentials, unusual installs, or hidden endpoints.

Purpose & Capability

Name/description match the content: SKILL.md documents markitdown usage and the included script wraps the markitdown CLI for single and batch conversions. Requested resources and code are proportionate to a converter helper.

Instruction Scope

SKILL.md focuses on installing and using markitdown and shows CLI/Python API examples. The included wrapper only invokes the external markitdown CLI and reads/writes files; it does not access unrelated system files or environment variables. Note: the included test uses a hard-coded user path (/Users/study/.openclaw/skills/markitdown) which is an odd, environment-specific assertion but not indicative of exfiltration.

Install Mechanism

This is an instruction-only skill (no install spec). SKILL.md recommends installing markitdown from PyPI/pipx which is a standard distribution channel; the bundle does not download arbitrary archives or run remote installers itself.

Credentials

The skill declares no required environment variables or credentials. The wrapper calls an external CLI (markitdown) but does not request secrets or unrelated tokens.

Persistence & Privilege

Skill is not always-enabled and does not modify other skills or system-wide settings. It simply provides a wrapper script invoked on demand.

Assessment

This skill is a thin wrapper around the third‑party 'markitdown' tool and is internally consistent. Before installing: (1) confirm you trust the markitdown PyPI/GitHub project (pipx is recommended to isolate installation); (2) review markitdown's own docs for any network behavior (YouTube download, remote transcription, MCP server) because those operations may fetch or upload content; (3) be cautious when converting sensitive documents—the conversion tool will read the content and may fetch remote resources if given URLs; (4) the included smoke test contains a hard-coded user path which is probably an autogenerated/benign artifact but may fail on different machines. If you need guarantees about data locality or network access, inspect the upstream markitdown source (links are in SKILL.md) before use.

MarkItDown

Microsoft's lightweight Python utility for converting various files to Markdown for use with LLMs and related text analysis pipelines.

Installation

Prerequisites

• Python 3.10+
• Java 11+ (for some converters)

Install via pipx (recommended)

pipx install 'markitdown[all]'

Install via pip

pip install 'markitdown[all]'

Minimal install (specific formats only)

pip install 'markitdown[pdf,docx,pptx]'

Supported Formats

Format	Extension	Notes
PDF	.pdf	Preserves structure, tables, links
Word	.docx	Headings, lists, tables
PowerPoint	.pptx	Slides to Markdown
Excel	.xlsx, .xls	Table data
Images	.png, .jpg, etc.	EXIF metadata + OCR
Audio	.wav, .mp3	Speech transcription
HTML	.html, .htm	Web content
YouTube	URL	Video transcription
ZIP	.zip	Iterates over contents
EPub	.epub	E-books
Text	.csv, .json, .xml	Text-based formats

CLI Usage

Basic Conversion

# PDF to Markdown
markitdown document.pdf > output.md

# Word to Markdown
markitdown document.docx -o output.md

# PowerPoint to Markdown
markitdown presentation.pptx -o output.md

Pipe Input

cat document.pdf | markitdown

Image OCR

markitdown screenshot.png -o text.md

YouTube Video

markitdown "https://youtube.com/watch?v=..." -o transcript.md

Python API Usage

from markitdown import MarkItDown

# Initialize
md = MarkItDown()

# Convert file
result = md.convert("document.pdf")
print(result.text_content)

# Convert from stream
with open("document.pdf", "rb") as f:
    result = md.convert_stream(f)
    print(result.text_content)

Options

Option	Description	Example
-o, --output	Output file	-o output.md
--format	Output format (default: markdown)	--format json
--pages	Specific pages	--pages "1,3,5-7"
--image-output	Image handling	--image-output external
--quiet	Suppress output	--quiet

MCP Server

MarkItDown provides an MCP (Model Context Protocol) server for integration with LLM applications:

pip install markitdown-mcp

Best Practices

1. Batch processing: Process multiple files in one call for efficiency
2. Format selection: Use minimal install if only specific formats needed
3. OCR quality: Ensure 300 DPI+ for scanned documents
4. Output review: Always verify Markdown output for complex documents

Troubleshooting

Java not found

Install Java 11+:

# macOS
brew install openjdk@17

# Ubuntu
sudo apt install openjdk-17-jdk

Permission denied

Use pipx or virtual environment:

python3 -m venv ~/.venvs/markitdown
source ~/.venvs/markitdown/bin/activate
pip install 'markitdown[all]'

References

• GitHub: https://github.com/microsoft/markitdown
• PyPI: https://pypi.org/project/markitdown/
• MCP Server: https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp