markitdown
Convert various file formats (PDF, Office documents, images, audio, web content, structured data) to Markdown optimized for LLM processing
Install / Use
npx skills add brycewang-stanford/Auto-Empirical-Research-Skills --skill markitdownInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
AI & Machine LearningSupported Platforms
Our assessment of markitdown
markitdown scores 94/100 on our quality scale, 186th of 950 AI & Machine Learning skills we index (top 20%).
Its SKILL.md is 6.7 KB long, well organised into 19 sections with 15 code examples: a thorough specification that gives an agent plenty to work with.
With 4,360 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so markitdown is actively maintained.
- Our last check on 2026-11-16 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-29. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
markitdown compared with similar skills
All 4 of these similar skills score higher than markitdown; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| markitdown (this skill)by brycewang-stanford | 94 | 4.4k | 54d ago | SKILL.md |
| claude-memby thedotmack | 100 | 117.6k | today | CLAUDE.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 9d ago | CLAUDE.md |
| Understand-Anythingby Egonex-AI | 100 | 92.8k | 1d ago | CLAUDE.md |
Frequently asked questions
- How do I install markitdown?
- Run
npx skills add brycewang-stanford/Auto-Empirical-Research-Skills --skill markitdown. The install tabs above show the steps for each supported agent. - Which AI agents does markitdown work with?
- It is written for Zed, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is markitdown safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is markitdown still maintained?
- The repository was last updated about 2 months ago, so markitdown is actively maintained.
Skill content
View source on GitHubname: markitdown description: Convert various file formats (PDF, Office documents, images, audio, web content, structured data) to Markdown optimized for LLM processing. Use when converting documents to markdown, extracting text from PDFs/Office files, transcribing audio, performing OCR on images, extracting YouTube transcripts, or processing batches of files. Supports 20+ formats including DOCX, XLSX, PPTX, PDF, HTML, EPUB, CSV, JSON, images with OCR, and audio with transcription.
MarkItDown
Overview
MarkItDown is a Python utility that converts various file formats into Markdown format, optimized for use with large language models and text analysis pipelines. It preserves document structure (headings, lists, tables, hyperlinks) while producing clean, token-efficient Markdown output.
When to Use This Skill
Use this skill when users request:
- Converting documents to Markdown format
- Extracting text from PDF, Word, PowerPoint, or Excel files
- Performing OCR on images to extract text
- Transcribing audio files to text
- Extracting YouTube video transcripts
- Processing HTML, EPUB, or web content to Markdown
- Converting structured data (CSV, JSON, XML) to readable Markdown
- Batch converting multiple files or ZIP archives
- Preparing documents for LLM analysis or RAG systems
Core Capabilities
1. Document Conversion
Convert Office documents and PDFs to Markdown while preserving structure.
Supported formats:
- PDF files (with optional Azure Document Intelligence integration)
- Word documents (DOCX)
- PowerPoint presentations (PPTX)
- Excel spreadsheets (XLSX, XLS)
Basic usage:
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)
Command-line:
markitdown document.pdf -o output.md
See references/document_conversion.md for detailed documentation on document-specific features.
2. Media Processing
Extract text from images using OCR and transcribe audio files to text.
Supported formats:
- Images (JPEG, PNG, GIF, etc.) with EXIF metadata extraction
- Audio files with speech transcription (requires speech_recognition)
Image with OCR:
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("image.jpg")
print(result.text_content) # Includes EXIF metadata and OCR text
Audio transcription:
result = md.convert("audio.wav")
print(result.text_content) # Transcribed speech
See references/media_processing.md for advanced media handling options.
3. Web Content Extraction
Convert web-based content and e-books to Markdown.
Supported formats:
- HTML files and web pages
- YouTube video transcripts (via URL)
- EPUB books
- RSS feeds
YouTube transcript:
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("https://youtube.com/watch?v=VIDEO_ID")
print(result.text_content)
See references/web_content.md for web extraction details.
4. Structured Data Handling
Convert structured data formats to readable Markdown tables.
Supported formats:
- CSV files
- JSON files
- XML files
CSV to Markdown table:
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("data.csv")
print(result.text_content) # Formatted as Markdown table
See references/structured_data.md for format-specific options.
5. Advanced Integrations
Enhance conversion quality with AI-powered features.
Azure Document Intelligence: For enhanced PDF processing with better table extraction and layout analysis:
from markitdown import MarkItDown
md = MarkItDown(docintel_endpoint="<endpoint>", docintel_key="<key>")
result = md.convert("complex.pdf")
LLM-Powered Image Descriptions: Generate detailed image descriptions using GPT-4o:
from markitdown import MarkItDown
from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("presentation.pptx") # Images described with LLM
See references/advanced_integrations.md for integration details.
6. Batch Processing
Process multiple files or entire ZIP archives at once.
ZIP file processing:
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("archive.zip")
print(result.text_content) # All files converted and concatenated
Batch script: Use the provided batch processing script for directory conversion:
python scripts/batch_convert.py /path/to/documents /path/to/output
See scripts/batch_convert.py for implementation details.
Installation
Full installation (all features):
uv pip install 'markitdown[all]'
Modular installation (specific features):
uv pip install 'markitdown[pdf]' # PDF support
uv pip install 'markitdown[docx]' # Word support
uv pip install 'markitdown[pptx]' # PowerPoint support
uv pip install 'markitdown[xlsx]' # Excel support
uv pip install 'markitdown[audio]' # Audio transcription
uv pip install 'markitdown[youtube]' # YouTube transcripts
Requirements:
- Python 3.10 or higher
Output Format
MarkItDown produces clean, token-efficient Markdown optimized for LLM consumption:
- Preserves headings, lists, and tables
- Maintains hyperlinks and formatting
- Includes metadata where relevant (EXIF, document properties)
- No temporary files created (streaming approach)
Common Workflows
Preparing documents for RAG:
from markitdown import MarkItDown
md = MarkItDown()
# Convert knowledge base documents
docs = ["manual.pdf", "guide.docx", "faq.html"]
markdown_content = []
for doc in docs:
result = md.convert(doc)
markdown_content.append(result.text_content)
# Now ready for embedding and indexing
Document analysis pipeline:
# Convert all PDFs in directory
for file in documents/*.pdf; do
markitdown "$file" -o "markdown/$(basename "$file" .pdf).md"
done
Plugin System
MarkItDown supports extensible plugins for custom conversion logic. Plugins are disabled by default for security:
from markitdown import MarkItDown
# Enable plugins if needed
md = MarkItDown(enable_plugins=True)
Resources
This skill includes comprehensive reference documentation for each capability:
- references/document_conversion.md - Detailed PDF, DOCX, PPTX, XLSX conversion options
- references/media_processing.md - Image OCR and audio transcription details
- references/web_content.md - HTML, YouTube, and EPUB extraction
- references/structured_data.md - CSV, JSON, XML conversion formats
- references/advanced_integrations.md - Azure Document Intelligence and LLM integration
- scripts/batch_convert.py - Batch processing utility for directories
Related Skills
claude-mem
117.6kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Understand-Anything
92.8kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
