Convert Word to Markdown

Convert Word to Markdown

When to use this skill

Trigger this skill any time there is a .docx file that needs to be understood or processed — for example, a user attaches a Word document and asks questions about it, wants a summary, wants specific data pulled out, or wants multiple Word documents in a folder processed together. Word's native .docx format is a zipped XML bundle that is not reliably readable as plain text, so always convert it to Markdown first using the script in this skill rather than trying to open or parse the file directly.

This skill only supports .docx. If asked to convert a legacy .doc file, tell the user it isn't supported and ask them to re-save it as .docx (Word: File > Save As > Word Document (.docx)) first.

Mixed file types: When the user references a folder or set of documents containing multiple supported file types (.pdf, .docx, .xlsx), this skill handles only .docx files. The agent MUST also invoke the sibling skills in parallel:

• convert-pdf-to-md for any .pdf files
• convert-excel-to-md for any .xlsx files

Never process a folder and silently skip a supported file type. All three skills must be invoked together when mixed types are present.

Setup (once per environment)

Before the first conversion in a given environment, follow references/setup.md step by step to ensure Python, pip, and the markitdown package are installed. Do this proactively rather than guessing whether the environment is ready — the script itself will also fail with a clear pointer back to that file if markitdown turns out to be missing, so it's safe to just try the conversion first if you're reasonably confident setup was already done.

Usage

The conversion script lives at scripts/convert_word_to_md.py.