# Read With Markitdown

> Convert document and data files to Markdown with Microsoft MarkItDown before reading or analyzing them. Use whenever Codex is about to inspect PDF, HTML, DOCX, PPTX, XLSX/XLS, EPUB, CSV, JSON, XML, ZIP, Outlook messages, images with OCR or metadata, or audio requiring transcription, especially for text extraction, summarization, search, comparison, and citation. Do not rely on conversion alone when exact visual layout, figures, scanned pages, formulas, spreadsheet cell fidelity, or dynamic or authenticated web content matters; pair it with native visual or structured inspection.

- Skill: `ben-lau1/read-with-markitdown` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ben-lau1/read-with-markitdown`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ben-lau1/read-with-markitdown/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Ben-Lau1 (https://skillmd.com/u/ben-lau1)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ben-lau1/read-with-markitdown

---


# Read with MarkItDown

Normalize supported documents to Markdown before text-first analysis. Treat the generated Markdown as a derived reading aid; the original source remains authoritative.

## Workflow

1. Identify the source and format.
   - Read existing Markdown and plain-text files directly unless normalization is explicitly requested.
   - Convert supported local non-Markdown files before reading their raw contents.
   - For remote HTML or documents, fetch or download them with an authorized web or file tool, retain the canonical URL for provenance, and convert the local copy. Never give an untrusted URL directly to MarkItDown.
2. Run the bundled wrapper, resolving the script path relative to this `SKILL.md`:

   ```bash
   python3 /absolute/path/to/read-with-markitdown/scripts/convert.py -- /absolute/path/to/report.pdf
   ```

   Pass multiple local sources in one invocation when useful. The wrapper prints JSON containing the generated Markdown paths. It writes to a unique temporary directory by default; use `--output-dir /absolute/path` only when the user wants persistent artifacts.
3. Read the generated Markdown. For large outputs, search first and read only relevant line ranges or sections rather than loading the entire file.
4. Preserve provenance. Cite or identify the original file or canonical remote URL, not only the temporary Markdown path.
5. Verify important claims against the original whenever conversion may have lost structure or content.

## Choose the Right Companion Tool

- For scanned, visual, or layout-heavy PDFs, inspect the original pages and use OCR if the Markdown is empty, sparse, or structurally suspicious.
- For tables, formulas, or spreadsheets, use the Markdown for orientation, then use native structured tools for exact cells, formulas, hidden sheets, types, counts, and calculations.
- For CSV, JSON, and XML, prefer deterministic parsers for exact values, schema inspection, counting, filtering, and arithmetic.
- For dynamic or authenticated HTML, use a browser or native web tool. Convert only a downloaded static representation when that representation is sufficient.
- For ZIP files, inspect the archive listing and sizes first. Convert only selected safe members; do not blindly expand untrusted archives.
- For images and audio, specialized vision, OCR, or transcription tools may be primary. Treat MarkItDown output as supplemental when fidelity matters.

## Safety and Failure Handling

- Give the wrapper local files only. It rejects URLs, directories, and missing paths.
- Do not modify source files. The wrapper refuses to overwrite generated outputs.
- Do not silently install MarkItDown globally. The wrapper uses an existing `markitdown` command or an isolated `uvx --from 'markitdown[all]' markitdown` environment.
- If neither runtime is available, report the dependency problem and suggest an isolated environment or `python -m pip install 'markitdown[all]'` in a dedicated virtual environment.
- If conversion fails, report the failure and switch to a suitable native, visual, OCR, or structured reader. Never infer that a successful process exit means the conversion is complete without checking the output.
- If the Markdown is empty, unexpectedly short, or missing crucial sections, inspect the original and explicitly note the limitation.

## Bundled Resource

- `scripts/convert.py`: safe, local-only batch wrapper around the MarkItDown CLI. It creates collision-free Markdown outputs and reports machine-readable results.