Index of every page on this site: llms.txt
All skills
github avatar

/convert-word-to-md

@f10fdb8 official
by githubgithub/awesome-copilot41k stars
5,399
Run it yourself

Converts Word (.docx) documents into Markdown so their contents can be accurately analyzed, summarized, searched, or extracted from. Use this skill whenever the user shares, references, or asks about a .docx file — even if they don't say "convert" or "markdown" explicitly. This includes requests to "read", "summarize", "review", "extract data from", "compare", or "analyze" a Word document, resume, report, contract, or proposal. Always run the bundled conversion script to produce Markdown first; do not attempt to parse .docx content directly or write ad-hoc conversion code. Also use this skill for batch requests involving a whole folder of Word documents. IMPORTANT: When the user references a folder or set of documents containing multiple file types (.pdf, .docx, .xlsx), invoke ALL three sibling skills — convert-pdf-to-md, convert-word-to-md, and convert-excel-to-md — so no file type is silently skipped.

Use this Skill: https://skilld.dev/gh/github/awesome-copilot/convert-word-to-md

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈236 tokens for metadata: the name and description. ≈1.4k when used: this file. ≈573 more on demand in 1 file.

Description uses 11.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈937 characters, or 11.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

Output structure: MarkItDown embeds images as a truncated data:image/png;base64... URI placeholder (not real image data), so the script extracts real images directly from the .docx and writes a self-contained folder per document instead of a single loose .md file:

<name>/
    img/
        img001.<ext>
        img002.<ext>
        ...
    <name>.md          (image references are relative: img/imgNNN.ext)

If the document has no embedded images, no img/ folder is created.

Single file:

# Windows
python scripts\convert_word_to_md.py "C:\path\to\document.docx"
# macOS / Linux
python scripts/convert_word_to_md.py "/path/to/document.docx"

This creates a document\ folder next to the source file (containing document.md and, if present, document\img\). To control the destination folder explicitly:

python scripts\convert_word_to_md.py "C:\path\to\document.docx" -o "C:\path\to\output_folder"

A folder of Word documents (batch mode):

python scripts\convert_word_to_md.py "C:\path\to\folder"

Add --recursive to also include subfolders:

python scripts\convert_word_to_md.py "C:\path\to\folder" --recursive

Each .docx found gets its own <name>\ output folder next to it by default. Pass -o "C:\path\to\output_parent" to collect all the generated <name>\ folders under a separate parent directory instead (subfolder structure is preserved when combined with --recursive).

After conversion, read the resulting .md file(s) to perform the actual analysis the user asked for — the script's job is only to produce accurate Markdown (and images), not to interpret the content.

Deciding where output goes

Default — always output next to the source file. The <name>/ folder is created in the same directory as the source .docx. This is the required default for every case. Do NOT override it unless the user explicitly asks for a different location.

Only use -o when the user explicitly provides an output path (e.g., "save the output to C:\output", "put the results in D:\work"). Do NOT pass -o based on the agent's current working directory, the session state folder, or any implied location.

If the source file path cannot be fully resolved — for example, the user provides only a filename with no directory, or the path is ambiguous — use ask_user to confirm the full absolute path before running the conversion. Never guess or assume the directory.

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 That specific file is corrupt, password-protected, or otherwise unreadable Report which file(s) failed; other files in the batch still succeed
NOTE: skipped N non-.docx file(s) Folder contains non-Word files Expected — those files are intentionally ignored
WARNING: found N image placeholder(s) ... but extracted M image file(s) Mismatch between MarkItDown's placeholder count and images found in word/media/ (unusual/malformed docx) Placeholders are left unreplaced rather than risk wrong images; inspect the source file's media manually if images are needed

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning4mo3 checks · Risk SAFE
  • Gen Agent Trust Hub4mo

    The skill facilitates the conversion of Word (.docx) documents to Markdown using Microsoft's MarkItDown library. It includes a Python script for processing individual files or batches and detailed setup instructions for various operating systems. While the skill is subject to indirect prompt injection from document content, all analyzed components and external dependencies are from trusted sources and no malicious patterns were detected.

  • Socket4mo

    No alerts

  • Snyk4mo

    Risk: MEDIUM · 1 issue

Signed by skilld at f10fdb8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 months ago

README badge

README badge for github/awesome-copilot/convert-word-to-md