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
5. Cleans Content - Removes redundant Word markers and revision history
6. Creates Output - Generates clean Markdown with proper image references

What Gets Cleaned

• Word comment markers: [///txt], [/***], [***/], [txt///]
• Revision history: ~~strikethrough text~~, (removed)
• Word TOC links: [1 Arc 4](#_Toc200457262)
• Result: ~35% file size reduction

Supported Formats

Document Formats

• .docx - Office 2007+
• .doc - Legacy Office formats

Image Formats

• PNG, JPG/JPEG
• EMF (Enhanced Metafile - converted to PNG)
• BMP, GIF, and other embedded formats

Troubleshooting

Issue: "MissingDependencyException"

Solution: Ensure markitdown is installed with all dependencies:

pip install 'markitdown[all]'

Issue: .doc conversion fails with "output file not found"

Cause: LibreOffice GUI is already running - headless mode cannot start

Solution:

# Close all LibreOffice windows and quit the application
killall soffice

# Or check if LibreOffice is running
pgrep -lf soffice

Issue: Images not displaying in Markdown viewer

Solution:

• Ensure image folder is in the same directory as the .md file
• WMF/EMF files are automatically converted to PNG

Issue: Wrong image order (Figure 1 shows wrong diagram)

Solution: The skill uses content-hash matching to solve this - ensure you're using the latest version

Technical Details

Scripts Included

• convert_word_to_markdown.py - Main unified converter
• convert_with_images.py - Core conversion logic with image extraction
• convert_doc_to_docx.py - Legacy .doc to .docx converter
• clean_markdown.py - Content cleanup utilities

Requirements

• Python 3.6+
• markitdown (with all dependencies)
• LibreOffice (optional, for .doc files)

Examples

Example 1: Architecture Specification

User: Convert AV2_VE_DAMR_OPFL_arch_spec.docx to Markdown

Claude: I'll convert this document using the doc-to-markdown skill.

Result:
✓ Extracted 13 images to AV2_VE_DAMR_OPFL_arch_spec_images/
✓ Created AV2_VE_DAMR_OPFL_arch_spec.md (2,121 bytes, 92 lines)
✓ Removed 50 redundant lines

Example 2: Batch Processing

User: Convert all VE architecture documents to Markdown

Claude: Found 5 Word documents. Converting...

Result:
✓ Converted 5 documents
✓ Extracted 47 total images
✓ Created 5 markdown files

Contributing

Feel free to submit issues and enhancement requests!

License

MIT License - Feel free to use and modify

Author

Created for Claude Code users who need to convert Word documents to Markdown while preserving all content and images.

Version

1.0.0 - Initial release

---

For detailed documentation, see SKILL.md in the skill directory.