| name | markitdown |
| description | Reads .pdf, .docx, .pptx, .xlsx, .msg, and .epub files by converting them to Markdown with markitdown, then ingests the result. Use when a file with one of those extensions is uploaded or a local path to one is given and the goal is to read, summarize, or understand its content. Also use when the user explicitly asks to "convert to markdown" or "save as markdown" for a supported file. Proactively convert on upload — do not wait for the user to ask. Do NOT use for creating or editing documents, for web URLs, for HTML files, or for plain text. |
| license | Apache-2.0 |
| metadata | {"author":"Oleg Shulyakov","version":"1.2.0","source":"github.com/olegshulyakov/agent.md","catalog":"utility","category":"document-conversion","tags":["documents","markdown","conversion","markitdown"]} |
MarkItDown
Converts .pdf, .docx, .pptx, .xlsx, .msg, and .epub files to Markdown using markitdown, then reads the result.
Supported Formats
| Extension | Format |
|---|
.pdf | PDF documents |
.docx | Word documents |
.pptx | PowerPoint presentations |
.xlsx | Excel workbooks |
.msg | Outlook email messages |
.epub | EPUB ebooks |
Mode 1 — Read (primary)
Use whenever a supported file is uploaded or the user gives a local path and the goal is to understand its content. Do not wait for the user to ask — convert and read proactively.
Step 1: Resolve the file path
- Uploaded file: resolve it using this harness's convention for attached-file paths.
- Typed path: use it as-is
Step 2: Convert and read
python3 scripts/run.py --read <path>
The script prints the Markdown content to stdout (capped at 50 000 characters).
Ingest the output, then respond to the user normally.
Step 3: If the output is truncated
The script appends [truncated — content exceeds 50 000 characters] when the file is large.
Tell the user the file was partially read and offer to answer questions about specific sections.
Mode 2 — Convert (secondary)
Use only when the user explicitly asks to convert a file to Markdown or save it as a .md file.
Step 1: Resolve the file path (same as Mode 1)
Step 2: Convert and save
python3 scripts/run.py --convert <path> --out <dest>
<dest> is <stem>.md (the original filename without extension, e.g. report.pdf → report.md) written wherever this harness's convention places generated files for the user — e.g. the current working directory in a CLI session. If the output file already exists, append _1, _2, etc.
Step 3: Deliver the file
If this harness provides a file-delivery mechanism (e.g. present/download), use it with the output path so the user can retrieve the file.
Examples
Uploaded PDF — proactive read
User uploads annual_report.pdf and asks: "What were the key findings?"
python3 scripts/run.py --read <annual_report.pdf-resolved-per-harness-convention>
Ingest the output, then answer the question.
Explicit conversion
User says: "Convert this spreadsheet to Markdown" (after uploading data.xlsx)
python3 scripts/run.py --convert <data.xlsx-resolved-per-harness-convention> --out data.md
Then deliver data.md to the user via this harness's file-delivery mechanism.
Troubleshooting
Error: file not found
Verify the path with ls <path>. For uploads, confirm the filename matches exactly — paths are case-sensitive.
Error: unsupported format
Only the six extensions above are supported. For other formats, use the appropriate skill or tool.
Error: conversion failed
markitdown may fail on corrupted or password-protected files. Tell the user the file could not be read and ask them to verify it opens correctly in its native application.
Verification
- The correct mode (read vs. convert) matches what the user actually asked for.
- Mode 1: the output was ingested and used to answer the user; truncation was flagged if present.
- Mode 2: a
.md file was saved at the resolved path and delivered via the harness's file-delivery mechanism, if one exists.
