agentleFS
Ben-Lau1Ben-Lau1/codex-skills/skills/read-with-markitdown/SKILL.md

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

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
  1. Distinctive:

    Read existing Markdown and plain-text files directly unless normalization is explicitly requested.

    line 13
  2. Very specific:

    Run the bundled wrapper, resolving the script path relative to this SKILL.md:

    line 16
  3. Distinctive:

    Read the generated Markdown.

    line 23
  4. Distinctive:

    Verify important claims against the original whenever conversion may have lost structure or content.

    line 25
  5. Distinctive:

    Do not modify source files.

    line 39
  6. Very specific:

    Do not silently install MarkItDown globally.

    line 40
  7. Very specific:

    If neither runtime is available, report the dependency problem and suggest an isolated environment or python -m pip install …

    line 41
  8. Distinctive:

    If conversion fails, report the failure and switch to a suitable native, visual, OCR, or structured reader.

    line 42
  9. Distinctive:

    If the Markdown is empty, unexpectedly short, or missing crucial sections, inspect the original and explicitly note the limitation.

    line 43

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.