How to use the Convert Word to Markdown agent skill

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md instruction file and optional scripts that an AI agent can load when a task matches the skill's description. This skill is for .docx files. When you share a Word document and ask for a summary, a review, a comparison or specific data, the agent runs a bundled script that converts the document to Markdown, then reads that Markdown to do the work.

Each converted document gets its own folder next to the original. That folder holds a .md file and, if the document contains images, an img/ subfolder with the images saved as separate files. The Markdown image references point to those files with relative paths.

• Converts .docx files to Markdown for analysis, summary, search or extraction.
• Extracts embedded images as real image files instead of placeholders.
• Handles a single file or a whole folder, with an optional --recursive flag for subfolders.
• Does not support legacy .doc files. Re-save them as .docx first (File > Save As > Word Document (.docx)).

How do you install the convert-word-to-md skill?

Download the ZIP for this skill from this page and unzip it. You can install it in one of two places. For all your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. Either way, the skill folder should contain SKILL.md, the scripts/ folder and the references/ folder.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills

How do you set up Python and markitdown?

The skill needs Python 3.10 or newer, pip, and the markitdown Python package with Word support. The skill's references/setup.md file gives the step-by-step setup, and the agent is directed to follow it before the first conversion. The required package is listed in scripts/requirements.txt as markitdown[docx]. The setup file lists these commands for installing Python on each system:

• Windows: winget install --id Python.Python.3.12 -e
• macOS: brew install python@3.12
• Linux (Debian/Ubuntu): sudo apt-get update && sudo apt-get install -y python3 python3-pip python-is-python3
• Check your version with: python --version and pip with: python -m pip --version

How do you trigger the skill with a natural request?

You do not need to type a command. The skill's description tells the agent to use it whenever a .docx file is shared or referenced, even if you do not mention conversion or Markdown. Phrases such as read, summarize, review, extract data from, compare or analyze a Word document, resume, report, contract or proposal are enough.

If you ask about a folder that contains .pdf, .docx and .xlsx files, the agent is instructed to also use the sibling skills convert-pdf-to-md and convert-excel-to-md, so no file type is skipped. This skill only handles the .docx files.

• "Summarize the contract at C:\Work\nda-2024.docx"
• "Compare these two proposals and list the pricing differences."
• "Pull the candidate's work history out of resume.docx."
• "Process every Word file in this folder and tell me which ones mention a termination clause."

How do you run the conversion script yourself?

The agent normally runs the script for you, but you can run it directly. The script is scripts/convert_word_to_md.py. On Windows use backslashes in the path. On macOS or Linux use forward slashes. By default, the output folder is created next to the source file. Use -o only when you want a different location.

• Single file, output next to source: the script creates a document\ folder containing document.md and, if present, an img\ folder.
• Custom output folder: add -o followed by the destination path.
• Folder batch: pass the folder path. Each .docx gets its own output folder.
• Include subfolders: add --recursive.
• Collect outputs in one parent folder: pass -o with a parent directory. Subfolder structure is kept when --recursive is used.

What should you check if conversion fails?

The skill's troubleshooting table covers the most common messages. A missing markitdown module means setup was not completed. An unsupported .doc file must be re-saved as .docx. An input path not found error usually means the path is wrong or the file moved. In batch mode, a FAILED line names one file that is corrupt, password-protected or unreadable, and the other files still convert. A warning about image placeholders means the image count did not match, so the script leaves those placeholders unreplaced rather than insert the wrong images.

• ModuleNotFoundError: No module named 'markitdown' (exit code 2): complete the setup steps.
• ERROR: Unsupported file type '.doc' (exit code 3): re-save as .docx.
• ERROR: Input path not found (exit code 3): confirm the path.
• FAILED <file> in batch output: that file is corrupt, password-protected or unreadable; fix or replace it.

What are the safety notes?

This skill runs a Python script on your machine, so you should only install it if you are comfortable with that. The skill's metadata says it runs scripts and does not use the network. Because the converted text is passed through the agent's model like any other file content, a sensitive or confidential document sent to a cloud-hosted agent will be processed by that service. Check your organisation's rules before sharing confidential contracts or personnel records. Some environments disallow running Python scripts, and in those the skill cannot work.

• Runs scripts: yes. The bundled Python script runs on your machine.
• Uses network: no, according to the skill's metadata.
• Cloud agents receive the converted content like any other file content.
• Environments that ban Python scripts cannot use this skill.