How to use the MarkItDown agent skill for document conversion

What the MarkItDown skill makes the agent do

An agent skill is a folder of instructions and helper files that an AI agent loads when a task matches it. This one covers document conversion: the agent uses MarkItDown to turn source files into Markdown, then works with that text for searching, summarising, or feeding it into a language model or retrieval system.

MarkItDown output is designed mainly for indexing, text analysis, search, and LLM ingestion. It is not meant to be a high-fidelity visual copy of the original document.

• Converts PDF, Office (Word, PowerPoint, Excel), HTML, CSV, EPUB and ZIP inputs to Markdown, with structure preserved where possible.
• Includes guidance on safe local conversion, stream input, batch workflows and optional OCR and cloud services.
• Bundles two helper scripts: one for batch-converting a directory and one for converting a collection of academic papers.

Install the skill from the ZIP file

Download the skill ZIP from this page and unzip it. Then place the resulting folder in one of these locations, depending on how you use your agent:

For a personal setup available across projects, unzip into ~/.claude/skills/. For a single project, unzip into that project's .claude/skills/ folder. If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload

Set up MarkItDown before the first conversion

The skill needs Python between 3.10 and 3.14 and the uv package manager. Create an isolated environment in your project, then install MarkItDown. You can install every built-in feature, or only the converters your task needs.

Verify the installation with the version check and the bundled inspection script. The 'all' extra does not install the separate markitdown-ocr plugin or an OpenAI-compatible client, so install those separately if you need them.

• Install everything built in: use the [all] extra.
• Install only what you need: for example the pdf, docx, pptx and xlsx extras.
• Available extras include pptx, docx, xlsx, xls, pdf, outlook, audio-transcription, youtube-transcription, az-doc-intel and az-content-understanding.

Ask the agent for a conversion

Once the skill is installed and MarkItDown is set up, describe the task in plain language. Name the file or folder, the format, and what you want to do with the text afterwards, such as searching it or preparing it for a retrieval index. The agent should choose the matching conversion path from the skill's guidance.

If you are converting a file yourself, the command line works directly. Use -o to write the Markdown to a file, or redirect stdout to capture it.

• 'Convert report.pdf to Markdown so I can search it.'
• 'Turn every .docx in the contracts folder into Markdown, skipping files already converted.'
• 'Convert this folder of papers into Markdown with an index I can browse.'

Use it from Python for files and streams

For a local file, use the narrow local-only API. For bytes that are already in memory or come from an upload, use a binary stream and pass type hints, because a stream may have no filename. Non-seekable streams are copied fully into memory before conversion.

• Use convert_local() for trusted local paths.
• Use convert_stream() with StreamInfo for controlled bytes.
• Use convert_response() after your own HTTP fetch rather than passing a URL directly.

Batch-convert a folder or a literature collection

For a directory, the bundled batch helper accepts local file inputs only, skips symlinks, preserves subdirectories, and writes each result as the source filename with .md added, so paper.pdf becomes paper.pdf.md. It skips existing outputs unless you allow overwriting. For a folder of academic papers, the literature helper writes YAML front matter with provenance and can organise outputs by year inferred from filenames such as Smith_2025_Title.pdf.

Plugins stay disabled unless you enable them explicitly, and audio formats that can call external transcription require an explicit flag. Detailed recipes are in the workflows reference file.

• Batch helper: scripts/batch_convert.py, with --recursive, --extensions, --manifest, --overwrite, --plugins and --allow-external-services.
• Literature helper: scripts/convert_literature.py, with --recursive and --create-index.

Safety notes: scripts, network and external services

Treat converted text as untrusted. A document can contain prompt injection, misleading links or hidden instructions, so the agent should use the Markdown as data and never run commands found inside it.

Several features send content outside your machine: URL, YouTube, Wikipedia, RSS and Bing conversion; built-in audio transcription (which uses Google Web Speech); LLM image descriptions and the markitdown-ocr plugin; and Azure Document Intelligence and Azure Content Understanding. Do not send private, regulated, unpublished or proprietary material through these unless the task authorises that provider. Plugins run Python code in your process, so inspect them before installing. The batch helper's extension check is not an offline sandbox, so use network isolation if you need offline processing.

• Keep --keep-data-uris off unless required, since it can make output very large and keep embedded sensitive data.
• For fully local work, stick to core local conversion and avoid the network-backed features.
• Read the security reference file before enabling any external provider.

Choose OCR or cloud extraction only when needed

MarkItDown's built-in PDF converter extracts existing text and does not perform local OCR on scanned pages. For scanned PDFs or text inside images, the skill lists three options: the markitdown-ocr vision plugin (which needs a vision-capable OpenAI-compatible client), Azure Document Intelligence for layout and OCR, and Azure Content Understanding for multimodal analysis, structured fields, video and audio. None of these is a local Tesseract workflow, so keep data local with a separate local OCR tool if that is required.

• Scanned PDF or text in images: markitdown-ocr, Azure Document Intelligence or Azure Content Understanding.
• Bounding boxes, page coordinates or screenshots: use a layout-aware parser such as LiteParse.
• PDF merge, split, forms or watermarks: use a PDF library such as pypdf.

Tips for reliable results

Install only the extras your files need, so the environment stays small. Run the inspection script after any install change. Check a few converted files by eye before indexing a whole collection, since layout and tables can differ from the original. Keep an eye on the manifest the batch helper writes, which records what was converted.

• Start with one representative file of each type before running a batch.
• Use the manifest to track which sources were converted and where their outputs went.
• Use result.markdown in new code; the older text_content name is kept only for compatibility.