Convert Word to Markdown
Convert .docx files into Markdown and image folders with the bundled script, then read the generated .md output to perform the user's requested analysis.
When to invoke
- "Read this Word document."
- "Summarize this .docx file."
- "Extract data from these Word reports."
- "Convert this folder of Word documents to Markdown."
- "Analyze these mixed PDF, Word, and Excel files."
Prerequisites and context
- This skill supports
.docx only. For legacy .doc, tell the user to re-save as .docx with Word: File > Save As > Word Document (.docx).
- Use
scripts/convert_word_to_md.py; do not parse .docx XML directly and do not write ad-hoc conversion code.
- Before first use in an environment, follow
references/setup.md to ensure Python, pip, and markitdown are installed.
- If
ModuleNotFoundError: No module named 'markitdown' appears, follow references/setup.md.
- IMPORTANT: the agent MUST convert first; if the path is ambiguous, use
ask_user-style confirmation instead of guessing.
Procedure
- Resolve the full source path. If the user provides only a filename or an ambiguous path, ask for the full absolute path before conversion.
- If the input set includes
.pdf, .docx, and .xlsx, invoke convert-pdf-to-md, convert-word-to-md, and convert-excel-to-md so no supported file type is silently skipped.
- Run
scripts/convert_word_to_md.py on the .docx file or folder.
- Use the default output location next to the source unless the user explicitly provides an output path.
- Read the generated Markdown file or files and complete the requested summary, extraction, review, comparison, or analysis.
Conversion commands
| Task |
Command |
| Single file on Windows |
python scripts\convert_word_to_md.py "C:\path\to\document.docx" |
| Single file on macOS / Linux |
python scripts/convert_word_to_md.py "/path/to/document.docx" |
| Explicit output folder |
python scripts\convert_word_to_md.py "C:\path\to\document.docx" -o "C:\path\to\output_folder" |
| Folder batch mode |
python scripts\convert_word_to_md.py "C:\path\to\folder" |
| Recursive folder batch mode |
python scripts\convert_word_to_md.py "C:\path\to\folder" --recursive |
| Collect outputs under a parent |
python scripts\convert_word_to_md.py "C:\path\to\folder" --recursive -o "C:\path\to\output_parent" |
MarkItDown emits truncated data:image/png;base64... placeholders, so the script extracts real images from the .docx and creates one folder per document:
<name>/
img/
img001.<ext>
img002.<ext>
...
<name>.md
On Windows this corresponds to <name>\, document\, document.md, and document\img\. The folder is self-contained.
Image references in Markdown are relative, for example img/imgNNN.ext. If no embedded images exist, no img/ folder is created.
Output location rules
- Default to a
<name>/ folder next to the source .docx.
- Use
-o only when the user explicitly provides an output path such as "save the output to C:\output" or "put the results in D:\work".
- Do not infer output from the current working directory, a session-state folder, or the agent's location.
- In recursive mode, preserve subfolder structure under the output parent.
- The flags
--recursive and -o "C:\path\to\output_parent" keep their original meanings.
Troubleshooting
| Symptom |
Likely cause |
Fix |
ModuleNotFoundError: No module named 'markitdown' / exit code 2 |
MarkItDown not installed |
Follow references/setup.md. |
ERROR: Unsupported file type '.doc' / exit code 3 |
Legacy .doc, not .docx |
Ask the user to re-save as .docx. |
ERROR: Input path not found / exit code 3 |
Wrong path, or file moved |
Confirm the correct path with the user. |
FAILED <file> -> ... in batch output |
File is corrupt, password-protected, or unreadable |
Report failed file names; other batch files still succeed. |
NOTE: skipped N non-.docx file(s) |
Folder contains non-Word files |
Expected for unsupported types; invoke sibling skills for supported PDF and Excel files. |
WARNING: found N image placeholder(s) ... but extracted M image file(s) |
Placeholder count differs from word/media/ images in an unusual/malformed document |
Leave placeholders unreplaced and inspect media manually if images are needed. |
Progressive disclosure and bundled resources
references/setup.md: environment setup for Python, pip, and MarkItDown.scripts/convert_word_to_md.py: required converter for single-file and batch conversion.scripts/requirements.txt: Python package requirements for the converter.
Related primitives
| Name |
Type |
Use it when |
convert-pdf-to-md |
skill |
The input set includes .pdf files. |
convert-excel-to-md |
skill |
The input set includes .xlsx files. |
Output template
## Word conversion result
**Status:** converted | partially converted | blocked
**Input:** `<file or folder>`
**Output:** `<generated Markdown path or folder>`
| Source | Markdown | Images | Notes |
| --- | --- | --- | --- |
| `<document.docx>` | `<name>/<name>.md` | `<count or none>` | `<success, skipped, or failure reason>` |
### Requested analysis
<summary, extraction, comparison, or next result based on the generated Markdown>
Quality gate
1---2name: convert-word-to-md-23description: Convert Word .docx documents into Markdown with extracted images using the bundled script. Use this skill when a user asks to read, summarize, review, compare, analyze, extract data from, or batch-process Word documents, resumes, reports, contracts, or proposals, including mixed folders that also require sibling PDF or Excel conversion skills.4---56# Convert Word to Markdown78Convert `.docx` files into Markdown and image folders with the bundled script, then read the generated `.md` output to perform the user's requested analysis.910## When to invoke1112- "Read this Word document."13- "Summarize this .docx file."14- "Extract data from these Word reports."15- "Convert this folder of Word documents to Markdown."16- "Analyze these mixed PDF, Word, and Excel files."1718## Prerequisites and context1920- This skill supports `.docx` only. For legacy `.doc`, tell the user to re-save as `.docx` with Word: File > Save As > Word Document (.docx).21- Use `scripts/convert_word_to_md.py`; do not parse `.docx` XML directly and do not write ad-hoc conversion code.22- Before first use in an environment, follow `references/setup.md` to ensure Python, pip, and `markitdown` are installed.23- If `ModuleNotFoundError: No module named 'markitdown'` appears, follow `references/setup.md`.24- IMPORTANT: the agent MUST convert first; if the path is ambiguous, use `ask_user`-style confirmation instead of guessing.2526## Procedure27281. Resolve the full source path. If the user provides only a filename or an ambiguous path, ask for the full absolute path before conversion.292. If the input set includes `.pdf`, `.docx`, and `.xlsx`, invoke `convert-pdf-to-md`, `convert-word-to-md`, and `convert-excel-to-md` so no supported file type is silently skipped.303. Run `scripts/convert_word_to_md.py` on the `.docx` file or folder.314. Use the default output location next to the source unless the user explicitly provides an output path.325. Read the generated Markdown file or files and complete the requested summary, extraction, review, comparison, or analysis.3334## Conversion commands3536| Task | Command |37| --- | --- |38| Single file on Windows | `python scripts\convert_word_to_md.py "C:\path\to\document.docx"` |39| Single file on macOS / Linux | `python scripts/convert_word_to_md.py "/path/to/document.docx"` |40| Explicit output folder | `python scripts\convert_word_to_md.py "C:\path\to\document.docx" -o "C:\path\to\output_folder"` |41| Folder batch mode | `python scripts\convert_word_to_md.py "C:\path\to\folder"` |42| Recursive folder batch mode | `python scripts\convert_word_to_md.py "C:\path\to\folder" --recursive` |43| Collect outputs under a parent | `python scripts\convert_word_to_md.py "C:\path\to\folder" --recursive -o "C:\path\to\output_parent"` |4445MarkItDown emits truncated `data:image/png;base64...` placeholders, so the script extracts real images from the `.docx` and creates one folder per document:4647```text48<name>/49 img/50 img001.<ext>51 img002.<ext>52 ...53 <name>.md54```5556On Windows this corresponds to `<name>\`, `document\`, `document.md`, and `document\img\`. The folder is self-contained.5758Image references in Markdown are relative, for example `img/imgNNN.ext`. If no embedded images exist, no `img/` folder is created.5960## Output location rules6162- Default to a `<name>/` folder next to the source `.docx`.63- Use `-o` only when the user explicitly provides an output path such as "save the output to `C:\output`" or "put the results in `D:\work`".64- Do not infer output from the current working directory, a session-state folder, or the agent's location.65- In recursive mode, preserve subfolder structure under the output parent.66- The flags `--recursive` and `-o "C:\path\to\output_parent"` keep their original meanings.6768## Troubleshooting6970| Symptom | Likely cause | Fix |71| --- | --- | --- |72| `ModuleNotFoundError: No module named 'markitdown'` / exit code 2 | MarkItDown not installed | Follow `references/setup.md`. |73| `ERROR: Unsupported file type '.doc'` / exit code 3 | Legacy `.doc`, not `.docx` | Ask the user to re-save as `.docx`. |74| `ERROR: Input path not found` / exit code 3 | Wrong path, or file moved | Confirm the correct path with the user. |75| `FAILED <file> -> ...` in batch output | File is corrupt, password-protected, or unreadable | Report failed file names; other batch files still succeed. |76| `NOTE: skipped N non-.docx file(s)` | Folder contains non-Word files | Expected for unsupported types; invoke sibling skills for supported PDF and Excel files. |77| `WARNING: found N image placeholder(s) ... but extracted M image file(s)` | Placeholder count differs from `word/media/` images in an unusual/malformed document | Leave placeholders unreplaced and inspect media manually if images are needed. |7879## Progressive disclosure and bundled resources8081- `references/setup.md`: environment setup for Python, pip, and MarkItDown.82- `scripts/convert_word_to_md.py`: required converter for single-file and batch conversion.83- `scripts/requirements.txt`: Python package requirements for the converter.8485## Related primitives8687| Name | Type | Use it when |88| --- | --- | --- |89| `convert-pdf-to-md` | skill | The input set includes `.pdf` files. |90| `convert-excel-to-md` | skill | The input set includes `.xlsx` files. |9192## Output template9394```markdown95## Word conversion result9697**Status:** converted | partially converted | blocked98**Input:** `<file or folder>`99**Output:** `<generated Markdown path or folder>`100101| Source | Markdown | Images | Notes |102| --- | --- | --- | --- |103| `<document.docx>` | `<name>/<name>.md` | `<count or none>` | `<success, skipped, or failure reason>` |104105### Requested analysis106<summary, extraction, comparison, or next result based on the generated Markdown>107```108109## Quality gate110111- [ ] Every `.docx` was converted with `scripts/convert_word_to_md.py` before analysis.112- [ ] Legacy `.doc` files were rejected with re-save guidance.113- [ ] Mixed `.pdf`, `.docx`, and `.xlsx` sets invoked the sibling conversion skills.114- [ ] The default output stayed next to the source unless the user explicitly supplied `-o`.115- [ ] Generated `.md` files were read before summarizing, reviewing, comparing, or extracting.116- [ ] Conversion failures were reported per file without hiding successful batch outputs.
paulasilvatech