Doc to Markdown Skill for Claude Code

A Claude Code skill that converts Microsoft Word documents (.doc/.docx) to clean, well-structured Markdown with full image preservation.

Features

• ✅ Full Format Support - Converts both .doc (legacy) and .docx (modern) formats
• ✅ Image Preservation - Extracts images to separate folders with proper references
• ✅ Smart Content Cleanup - Automatically removes Word comment markers, revision history, and TOC links
• ✅ Content-Hash Matching - Ensures correct image order (Figure 1 maps to correct image)
• ✅ Watermark Exclusion - Skips header/footer logos automatically
• ✅ WMF/EMF Conversion - Converts Windows Metafile formats to PNG
• ✅ Two Output Modes - External images (default) or embedded base64
• ✅ Batch Processing - Convert multiple documents at once

Installation

Step 1: Install the Skill

# Clone the repository to your Claude skills directory
cd ~/.claude/skills
git clone https://github.com/YOUR-USERNAME/doc-to-markdown-skill.git doc-to-markdown

Or download and extract manually:

mkdir -p ~/.claude/skills
cd ~/.claude/skills
# Download and extract the zip file here
unzip doc-to-markdown.zip

Step 2: Install Dependencies

The converter will use uvx (from uv) if available. If uvx is not installed, it will fall back to a markitdown executable on PATH.

Option A (recommended): install uv (provides uvx)

brew install uv

Option B: install markitdown directly

pip install 'markitdown[all]'

markitdown requires Python 3.10+.

Optional (for legacy .doc files):

brew install --cask libreoffice

Step 3: Restart Claude Code

The skill will automatically load on the next Claude Code session.

Usage

The skill activates automatically when you ask Claude to convert Word documents.

Single File Conversion

Convert document.docx to markdown

Extract specification.doc to markdown with images

Batch Conversion

Convert all Word files in this folder to markdown

Batch convert all .docx files in the specs directory

Embedded Mode

Convert document.docx to markdown with embedded images

Output Structure

Default Mode (External Images)

original-document.docx           # Original Word file
original-document.md             # Clean Markdown (2-3KB)
original-document_images/        # Extracted images folder
  ├── image1.png
  ├── image2.png
  └── ...

Embedded Mode

original-document.docx           # Original Word file
original-document.md             # Markdown with base64 images (large file)

How It Works

1. Detects Format - Automatically handles .doc or .docx files
2. Extracts Images - Pulls images from Word document (excluding headers/footers)
3. Converts to Markdown - Uses markitdown CLI tool
4. Matches Images - Content-hash matching ensures correct image order