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:

   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.