file-to-markdown

Field	Value
Type	Skill
Source	`~/.copilot/skills/file-to-markdown/SKILL.md`
Description	Convert rich documents — PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx/.xls), Outlook (.msg), HTML, CSV, JSON, XML, EPUB, and images — into clean Markdown so their content can be read into context cheaply, using Microsoft’s markitdown. Use this skill WHENEVER you need to read, summarize, extract from, quote, search, or feed the content of a non-Markdown document into the model, especially PDFs and Office files, which are token-expensive or unreadable in raw form. Trigger on things like “read this PDF”, “what does this contract/docx say”, “summarize this deck”, “pull the numbers out of this spreadsheet”, “ingest these files”, “add these files to context”, “convert this to markdown”, or any time a .pdf/.docx/.pptx/.xlsx/.msg/.html/.epub file needs to become text the model can work with. This is the default way to bring document content into a conversation — prefer it over dumping raw file bytes or guessing. It DEFERS to the pdf, docx, xlsx, and pptx skills when the goal is to EDIT or CREATE one of those files rather than read it.

Bundled Pages

Group	Name	Source
Scripts	Convert	`~/.copilot/skills/file-to-markdown/scripts/convert.sh`

Source Content

<!— File → Markdown —>

File → Markdown (token-efficient document ingestion)

Rich document formats are expensive or impossible to read directly. A PDF or .docx is binary — you can’t just read it as text. Even when a format is technically textual (HTML, a giant CSV), it’s bloated with markup, styling, and chrome that burns context tokens without adding meaning. This skill converts any such file into clean, minimal Markdown first, so the model reads the content and not the container. That’s the whole point: spend tokens on meaning, not on wrapper.

The conversion is backed by markitdown, Microsoft’s utility built specifically to turn documents into LLM-friendly Markdown.

When to reach for this

Use it any time a document’s content needs to enter the conversation:

Reading, summarizing, or answering questions about a PDF, Word doc, deck, or spreadsheet
Extracting figures, tables, or quotes from a report
Bringing a batch of files “into context” before analysis
Stripping a saved web page or bloated HTML export down to its substance

The tell is that the file is input to be understood, not output to be edited.

When NOT to use this — defer instead

This skill is read-only, one-way: file → Markdown, for ingestion. It does not round-trip. When the task is to edit or produce one of these files with fidelity (styling, formulas, layout, tracked changes), stop and use the dedicated skill:

The task is to…	Use instead
Edit/create a Word document, letterhead, tracked changes	`docx` skill
Edit/create a PDF, fill a form, merge/split, OCR-for-output	`pdf` skill
Edit/create a spreadsheet, add formulas, format cells	`xlsx` skill
Build/edit a slide deck or presentation	`pptx` skill

If you’re unsure: are you trying to understand the file (this skill) or change it (the fidelity skill)? Understanding wins → convert. Changing wins → defer.

How to use it

One self-contained script does everything, including a one-time dependency bootstrap:

# Convert one or many files — writes a sibling <name>.md next to each source,
# and reports the approximate token cost of reading each result.
skills/file-to-markdown/scripts/convert.sh path/to/report.pdf path/to/deck.pptx

# Just print the Markdown to stdout without writing a file (good for piping/quick reads):
skills/file-to-markdown/scripts/convert.sh --stdout path/to/contract.docx

Then read the resulting .md (or the stdout) to bring the content into context — that is the token-cheap artifact. Do not read the original binary.

The first run creates a dedicated Python venv at ~/.venvs/markitdown and installs the document-focused dependencies; every run after that is instant. Override the location with MARKITDOWN_VENV=/some/path if needed.

For a single ad-hoc conversion you can also call the tool directly: ~/.venvs/markitdown/bin/markitdown file.pdf.

Supported formats

Format	Extensions	Notes
PDF	`.pdf`	Text + tables; scanned/image-only PDFs yield little (no OCR in this install)
Word	`.docx`	Headings, lists, tables preserved as Markdown
PowerPoint	`.pptx`	Slide text and notes flattened in order
Excel	`.xlsx`, `.xls`	Each sheet rendered as a Markdown table
Outlook	`.msg`	Headers + body extracted
Web / markup	`.html`, `.htm`, `.xml`	Chrome and styling stripped to content
Data	`.csv`, `.json`	Rendered as tables / readable text
E-book	`.epub`	Chapters flattened to Markdown
Images	`.jpg`, `.png`, …	EXIF metadata only — no OCR/captioning in this install

Not installed (by choice, to stay lean and offline): audio transcription, YouTube transcript fetching, and Azure Document Intelligence. If a task genuinely needs one, add the extra to the venv, e.g. ~/.venvs/markitdown/bin/pip install 'markitdown[audio-transcription]'.

Working habits that keep this token-efficient

Convert, then read the .md — never the source. The savings only land if the binary/bloated original never enters context.
Batch related files in one call so you get all the Markdown at once.
Treat the generated .md as scratch for pure ingestion. If it’s in a project repo and you don’t need it committed, write it under a scratch/temp path or clean it up afterward, so conversion artifacts don’t litter the tree.
Watch the “~N tokens to read” readout. If a converted file is still huge, read only the section you need rather than the whole thing.
Scanned PDFs and photos of text won’t extract (no OCR here). If the Markdown comes back empty or garbled, say so rather than guessing at the contents.