Convert PDFs to Markdown using Mistral OCR API with image extraction. Use when you need to extract structured text and images from PDFs, especially for scanned documents or documents with complex formatting. Outputs Markdown with embedded images.
How this skill is triggered — by the user, by Claude, or both
Slash command
/pdf2markdown-converter:mistral-pdf-to-markdownThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Convert PDF documents to Markdown format using Mistral's OCR API. Automatically extracts text, formatting, and images.
Convert PDF documents to Markdown format using Mistral's OCR API. Automatically extracts text, formatting, and images.
Use the conversion script from this skill's directory:
# Convert entire PDF
uv run python ${CLAUDE_SKILL_DIR}/scripts/convert_pdf_to_markdown.py input.pdf output.md
# Convert specific pages
uv run python ${CLAUDE_SKILL_DIR}/scripts/convert_pdf_to_markdown.py input.pdf output.md --pages "1-5"
uv run python ${CLAUDE_SKILL_DIR}/scripts/convert_pdf_to_markdown.py input.pdf output.md --pages "1,3,5"
Output/PDFConversions/
├── document.md # Markdown with text and image references
└── images/
├── img-0.jpeg # Extracted images
├── img-1.jpeg
└── ...
from pathlib import Path
import subprocess
# Run conversion script
result = subprocess.run([
"uv", "run", "python",
"${CLAUDE_SKILL_DIR}/scripts/convert_pdf_to_markdown.py",
"input.pdf",
"Output/PDFConversions/output.md",
"--pages", "1-10"
], capture_output=True, text=True)
print(result.stdout)
images/ subfolder automaticallyThe script requires:
mistralai, python-dotenv, pypdfThe script checks these locations in order (first match wins):
MISTRAL_API_KEY — recommended for personal use (e.g., add export MISTRAL_API_KEY=your-key to secrets.sh).claude/agent-contract.yaml or ~/.config/agent-contract/config.yaml under paper-reader.mistral_api_keyNotes/.env — add MISTRAL_API_KEY=your-key. This file is gitignored but Dropbox-synced, making it convenient for teams sharing a project folderNever commit API keys to git. Use environment variables or Dropbox-synced
Notes/.envinstead.
uv run python ${CLAUDE_SKILL_DIR}/scripts/convert_pdf_to_markdown.py \
"Data/papers/research.pdf" \
"Notes/Paper Markdown/research.md"
# Extract pages 10-20 (introduction and methods)
uv run python ${CLAUDE_SKILL_DIR}/scripts/convert_pdf_to_markdown.py \
"paper.pdf" \
"Notes/Paper Markdown/intro_methods.md" \
--pages "10-20"
# Extract pages with figures
uv run python ${CLAUDE_SKILL_DIR}/scripts/convert_pdf_to_markdown.py \
"paper.pdf" \
"Notes/Paper Markdown/figures.md" \
--pages "25,27,30,35"
API Key Not Found:
Error: Mistral API key not found
→ See API Key Setup above for three ways to configure it
Page Out of Range:
Warning: Page 100 out of range, skipping
→ Check PDF page count and adjust page selection
API Rate Limit: → Wait a moment and retry, or reduce page count per request
images/ subfolderimages/img-X.jpegpdf skill insteadpdf skill - For local PDF manipulation without API callsreferences/reference.md - Additional details about the Mistral OCR APInpx claudepluginhub fuzhiyu/agentcontract --plugin pdf2markdown-converterParses PDF, Office, and image files into structured Markdown using the MinerU API. Supports OCR, formula/table recognition, batch processing, and multi-format export (DOCX/HTML/LaTeX).
Converts files and URLs to clean Markdown using MarkItDown. Supports PDF, DOCX, XLSX, PPTX, HTML, images (OCR), audio, CSV, and YouTube transcripts. Optimized for LLM ingestion pipelines.
Converts local PDF, DOCX, XLSX, PPTX, images via OCR, and audio files to clean Markdown using Microsoft's markitdown CLI. Best for text extraction from local documents.