read-with-markitdown
Skill0 starsChanged 3 months agoMITView on GitHub
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.
- Installs packages
In this repository4 other files it gives its agents.
- autoresearchSkill
- creative-thinking-for-researchSkill
- delegate-work-to-lunaSkill
- park-long-waitsSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 6 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 13
Read existing Markdown and plain-text files directly unless normalization is explicitly requested.
- Very specific: line 16
Run the bundled wrapper, resolving the script path relative to this SKILL.md:
- Distinctive: line 23
Read the generated Markdown.
- Distinctive: line 25
Verify important claims against the original whenever conversion may have lost structure or content.
- Distinctive: line 39
Do not modify source files.
- Very specific: line 40
Do not silently install MarkItDown globally.
- Very specific: line 41
If neither runtime is available, report the dependency problem and suggest an isolated environment or python -m pip install …
- Distinctive: line 42
If conversion fails, report the failure and switch to a suitable native, visual, OCR, or structured reader.
- Distinctive: line 43
If the Markdown is empty, unexpectedly short, or missing crucial sections, inspect the original and explicitly note the limitation.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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
- 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.
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.pdfPass 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/pathonly when the user wants persistent artifacts.- Read the generated Markdown. For large outputs, search first and read only relevant line ranges or sections rather than loading the entire file.
- Preserve provenance. Cite or identify the original file or canonical remote URL, not only the temporary Markdown path.
- 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
markitdowncommand or an isolateduvx --from 'markitdown[all]' markitdownenvironment. - 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

