Stats
Actions
Tags
From word-doc-to-md-skill
Convert Word documents (.docx) into clean, agent-readable Markdown. Use when someone asks to convert, export, or transform a Word doc into Markdown for AI agents, LLM pipelines, Claude Code tools, or MCP context. Also triggers when someone wants to make a Word document "agent-readable" or "LLM-friendly", or asks to "clean up" Markdown exported from Word.
How this skill is triggered — by the user, by Claude, or both
Slash command
/word-doc-to-md-skill:convert-docx <input.docx> [output.md] [--stdout]<input.docx> [output.md] [--stdout]This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
```
┌─────────────────────────────────────────────────────────────────┐
│ DOCX → AGENT MARKDOWN │
│ ═════════════════════ │
│ │
│ .docx ──▶ pandoc ──▶ 5 transforms ──▶ clean .md │
│ │
│ Tracked changes ✓ Heading hierarchy ✓ Tables ✓ │
│ Image refs ✓ Blank lines ✓ │
│ │
│ Everything lazy-loads on first use. Nothing to install. │
└─────────────────────────────────────────────────────────────────┘
docx-to-md binary (~2.5 MB) downloads on first use, and pandoc (~30 MB) downloads on first conversion.install.sh inside this plugin's directory — nothing is added to PATH or the user's project.Use the Glob tool to find docx-to-md in the plugin cache:
Glob pattern: ~/.claude/**/docx-to-md
If found, use that path as DOCX_TO_MD. If not found, search for install.sh:
Glob pattern: ~/.claude/**/word-doc-to-md-skill/install.sh
Then run the installer:
bash /path/to/install.sh
The installer auto-detects the platform and downloads the correct binary into the same directory.
# Basic conversion (output goes next to the input file)
/path/to/docx-to-md document.docx
# Explicit output path
/path/to/docx-to-md document.docx output/clean.md
# Pipe to another tool
/path/to/docx-to-md document.docx --stdout | your-ingestion-tool
On the first conversion, pandoc (~30 MB) downloads automatically into the plugin directory.
If a newer pandoc version is expected, it upgrades automatically with a message like:
Pandoc update available: 3.9.0.2 -> 3.x.x — Upgrading...
| # | Transform | Before | After |
|---|---|---|---|
| 1 | Tracked changes | [new text]{.insertion} | new text |
| 2 | Heading hierarchy | H3 → H5 (gap) | H1 → H3 (no gap) |
| 3 | Tables | +----+----+ grid dividers | Removed |
| 4 | Images |  | [IMAGE: alt] |
| 5 | Blank lines | 3+ blank lines | Single blank line |
Already have markdown from another source? Clean it without pandoc:
/path/to/docx-to-md postprocess existing.md cleaned.md
/path/to/docx-to-md postprocess existing.md --stdout
| Issue | Fix |
|---|---|
pandoc binary not found | Run /path/to/docx-to-md bootstrap to force re-download |
| Want a specific pandoc version | Run /path/to/docx-to-md bootstrap 3.x.x |
| Proxy/firewall blocks download | Set HTTPS_PROXY env var before running |
Legacy .doc file (not .docx) | Pre-convert: libreoffice --headless --convert-to docx file.doc |
| Multi-column layout garbled | Flag for human review — pandoc limitation |
| Missing alt text on images | Outputs [IMAGE: no description] — add alt text in Word |
Everything lives in the skill plugin directory — nothing is added to PATH or the user's project:
<plugin-dir>/
install.sh # platform-aware installer
docx-to-md # converter binary (lazy-loaded on first use)
bin/
pandoc # pandoc binary (lazy-loaded on first conversion)
.pandoc-version # tracks installed version for auto-upgrade
for f in *.docx; do /path/to/docx-to-md "$f"; donedocx-to-md and re-run install.shbin/ directory next to docx-to-md, then run any conversion--stdout to pipe directly into your ingestion toolCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub greenstevester/word-doc-to-md-skill --plugin convert-docx