`md-to-docx`

Turn a Markdown draft into a Word document (.docx) that someone outside engineering can open, edit and track changes in, with real Heading styles so the navigation pane and table of contents work, live hyperlinks, numbered and bulleted lists, tables, code blocks, embedded images and optional brand fonts and colours, and a warning for everything that could not be carried over. Use when the user wants a Markdown file as a Word doc, says "send this as a .docx", "convert to Word", "legal needs it in Word", or "make this editable for the client".

Pack convertersTier standardJob Get a draft ready to shipv0.1.3

npx skilldrop-cli install md-to-docx

Other ways to install

With the sibling skills it hands off to:

npx skilldrop-cli install md-to-docx --with-related

The whole pack it belongs to:

npx skilldrop-cli install --pack converters

By hand, from a clone of the repo:

cp -R packs/converters/skills/md-to-docx ~/.claude/skills/

In Claude Code, with the converters plugin installed, invoke it as:

/converters:md-to-docx

Try it

A realistic prompt from the skill's acceptance evals:

Northwind Legal wants our vendor onboarding policy as a Word doc so they can track changes. It's in docs/vendor-onboarding.md: a # title, ## sections, a numbered approval process with sub-steps, a pipe table of approval limits ($5,000 / $50,000 / unlimited), a footnote citing the finance policy, and a Mermaid flowchart of the approval path. Use ./brand/brand.json and A4 paper.

What a good result looks like

Headings are real Word headings. The navigation pane shows the outline, and *Insert Table of Contents* works without restyling.
Every link is clickable and every in-document #anchor link jumps to its heading.
Nothing is lost silently. Each WARN line is either fixed in the source and gone on rerun, or reported to the user with what it means.
Facts are untouched. You restructure Markdown (heading levels, footnotes into text) but never change a number, a name or a date in it.
Images are embedded, not linked, so the file still works when it's emailed.
The file opens. You checked it with textutil, Quick Look, LibreOffice or Word, not just that the script exited 0.

Example output

Northwind Support: Q3 review · the skill's own worked example, source

Worked example

title: Northwind Support — Q3 Review author: Support Operations

Prepared for the Acme account team. This review covers July to September and the three changes we propose for Q4. Raw numbers live in the support dashboard.

Summary

First-response time fell from 6.1 to 3.4 hours
Backlog is down 18%, mostly in the EMEA queue
- EMEA: 412 → 301 open tickets
- APAC: unchanged at 155
Chatbot hand-off rule shipped in August
Weekend rota still not agreed

Tickets by region

Region	Opened	Closed	Median first response
EMEA	2,140	2,251	3.1 h
NA	1,876	1,840	3.6 h
APAC	932	932	3.9 h

Proposals for Q4

Agree the weekend rota by 15 October.
Move APAC triage into the shared queue.
Retire the legacy support@ alias; see the alias section.

Customers said the chatbot hand-off was the biggest improvement this year. — from the September survey[^1]

Retiring the alias

The forwarding rule to remove:

match: to == "support@northwind.example"
action: forward -> queue/general

<div class="callout">Draft — not yet reviewed by Legal.</div>

Questions go to the support ops channel.

[^1]: 214 responses, 31% response rate.

How it's checked

Measured against plain Claude Code (2026-10-23): it met 66% of its checks, against 53% without it, and a blind judge preferred the agent without it. How skills are checked

26 assertions across 4 acceptance evals, and 8 trigger queries. Every skill's checks

What the output must do

Runs md_to_docx.py with --brand ./brand/brand.json and --page a4, writing a .docx
Deals with the Mermaid flowchart before converting: renders it to PNG with the Mermaid CLI and embeds it, or says plainly that it stays as code
Moves the footnote's text into the body or a Notes section instead of letting it drop silently
Reports every WARN line the script printed, each with what was done about it
Keeps the approval limits ($5,000 / $50,000 / unlimited) and every other fact exactly as in the source
Checks the file opens (textutil, Quick Look, LibreOffice or Word) and reports the script's summary counts
Tells the user the headings drive Word's navigation pane and table of contents
Saves the pasted text to a .md file before converting
Turns the bold-line pseudo-headings into ## headings so Word sees them as headings
Rewrites the HTML table as a pipe table rather than letting it drop
Says the remote image is not embedded and asks for, or downloads, a local copy
Does not invent content, numbers or dates that are not in the pasted report
Writes tender-response.docx as a valid Word file, and the section headings use Word's built-in heading styles (Heading 1, Heading 2 and so on) rather than just bold or larger text
The team photo is embedded in the document, and the site map (img/site-map.png) is reported as missing rather than silently dropped
It tells the user that the pricing total (33,650) does not match the items, which add up to 32,650, and does not change any figure in the document on its own
It warns that the 'NOTE TO SELF' about checking the gritting price is still in the text and would go to the council, rather than passing it through without a word
The parish tender page link is a working hyperlink in the .docx, and the user is told the insurance certificate link points to a local file (docs/insurance-2026.pdf) that is not included
It reports that the accent colour in brand.json (#C8A2) is not a valid colour, rather than silently applying it or quietly replacing it with a colour of its own
It does not add content, prices or sections that are not in tender-response.md
Writes a .docx file that opens in Word and can be edited
All seven items appear in the original order, with the names (Jan, Priya), the pieces and the 20-minute interval kept as written
The items end up numbered 1 to 7 in sequence, with no item lost or duplicated because of the repeated '3' in the source; if the numbering was changed, the reply says so
The title is a heading, the date, hall and door time line is kept, and 'Bring:' stays bold
It fits on one page, with no cover page, contents page or extra sections added
It does not invent times, pieces, performers or other details that are not in the text
It delivers the file without asking questions first, and the reply is short and in plain words

When it should and shouldn't activate

Should activate:

Convert README-for-legal.md to a Word document
The client can't open Markdown, can you send the design doc as a .docx?
Make this markdown report editable in Word with our brand fonts
Export these release notes to docx so HR can track changes

Should leave to another skill:

Turn this markdown outline into a PowerPoint deck
Convert the onboarding guide into a single HTML page I can email
Turn this Word file the client sent back into Markdown
Put these markdown tables into an Excel spreadsheet

Hands off to

output-hygiene — when the Markdown was written by an agent and is going to someone outside the team. Strip invisible characters and generated-by trailers before they are frozen into a Word file.

Source

SKILL.md · the whole folder on GitHub.

md-to-docx