file-to-markdown

name

file-to-markdown

description

Convert binary document files (PDF, DOCX, XLSX, PPTX, HWP, HWPX, EPUB, MSG, XLS, DOC, PPT, ZIP) to Markdown for AI consumption. Use this skill whenever a user references or wants to read, analyze, summarize, or extract data from any non-plaintext document file. This includes office documents, Korean Hangul files (.hwp/.hwpx), PDFs, spreadsheets, presentations, and email messages. Trigger even if the user just says "read this file" or "what's in this document" and the file is a binary format that Claude cannot read directly with the Read tool. Do NOT trigger for plain text files (.txt, .md, .csv, .json, .xml, .html, .yaml, .toml, .ini, .log, .py, .ts, .js, etc.) — Claude can read those directly.

File to Markdown

Convert binary document files to Markdown so they become readable, searchable, and analyzable in conversation context.

Why this skill exists

Claude's Read tool handles plain text files natively, but binary formats (PDF, DOCX, XLSX, PPTX, HWP, etc.) are opaque blobs. This skill bridges that gap by converting binary documents to clean Markdown using specialized tools, so you can then read, analyze, summarize, or answer questions about any document the user throws at you.

Supported formats

Extension	Format	Engine
.pdf	PDF	markitdown
.docx	Word (modern)	markitdown
.doc	Word (legacy)	markitdown
.xlsx	Excel (modern)	markitdown
.xls	Excel (legacy)	markitdown
.pptx	PowerPoint (modern)	markitdown
.ppt	PowerPoint (legacy)	markitdown
.epub	E-book	markitdown
.msg	Outlook email	markitdown
.zip	Archive (recursive)	markitdown
.hwp	Hangul (한글) binary	unhwp
.hwpx	Hangul (한글) XML	unhwp

Conversion workflow

Step 1: Identify the file

When a user mentions a document file, confirm the file path exists and check its extension. If the extension matches a supported binary format above, proceed. If it's a plain text format, just use the Read tool directly — no conversion needed.

Step 2: Run the conversion script

The bundled scripts/convert.py handles file detection, dependency checks, and conversion routing.

python3 <skill-dir>/scripts/convert.py "<file-path>"

This outputs Markdown to stdout. For large files, save to a temp file first:

python3 <skill-dir>/scripts/convert.py "<file-path>" -o /tmp/converted.md

Then read the output with the Read tool to bring it into context.

Step 3: Use the content

Once you have the Markdown content, proceed with whatever the user asked — summarize, analyze, extract data, answer questions, compare documents, etc.

Handling multiple files

When the user provides multiple documents, convert each one sequentially. For comparison tasks, convert all files first, then analyze them together.

Handling large documents

Some documents produce very long Markdown output. When a converted file is large (over ~2000 lines):

1. Save the conversion to a temp file: python3 convert.py "file.pdf" -o /tmp/converted.md
2. Read specific sections using the Read tool with offset/limit parameters
3. Summarize section by section rather than loading everything at once

Prerequisites

The script requires external conversion dependencies. It does not auto-install them; instead it prints setup guidance when they are missing.

markitdown (PDF, DOCX, XLSX, PPTX, etc.)

Installed as a CLI tool. Install it manually before use:

uv tool install 'markitdown[all]' --python 3.13

unhwp (HWP, HWPX)

Used as a Python library (no CLI). The script invokes it via uv run --with unhwp so no persistent install is needed — uv handles the ephemeral environment automatically. Manual test:

uv run --python 3.13 --with unhwp python3 -c "import unhwp; print(unhwp.to_markdown('file.hwp'))"

If uv is not installed

The script uses uv run --with unhwp when available and otherwise falls back to direct Python import. Install uv for the best experience:

curl -LsSf https://astral.sh/uv/install.sh | sh

Error handling

Common issues and how to deal with them:

Problem	Solution
"File not found"	Verify the path. Ask the user to confirm the exact file location.
"Unsupported file type"	Check if it's a plain text format (use Read instead) or an unsupported binary format.
"Installation failed"	Network issue or PEP 668 restriction. Install uv and retry, or run uv tool install 'markitdown[all]' --python 3.13 manually.
"Conversion produced empty output"	The file may be corrupted, password-protected, or contain only images. Let the user know.
Password-protected files	markitdown cannot open password-protected files. Ask the user for the password or an unprotected version.

Tips

• Excel files convert to Markdown tables — great for data analysis tasks
• PowerPoint slides convert with slide numbers and content structure preserved
• ZIP files are processed recursively — each contained file gets converted
• HWP/HWPX conversion preserves Korean text and basic formatting
• PDF quality depends on the PDF structure — text-based PDFs convert well, scanned PDFs may produce limited output