Translate between Word (.docx) files and Markdown with high-fidelity round-trip. Use this skill whenever the user wants to convert a Word document to Markdown, edit a .docx as text, regenerate a .docx from Markdown, diff/review Word content in git, or keep a canonical text version of a document alongside the .docx. Triggers: 'docx to markdown', 'word to md', 'convert this Word doc to markdown', 'rebuild this docx from markdown', 'edit my report in markdown', 'extract word text with formatting', 'round-trip my Word doc'. Preserves headings, lists, tables, images, footnotes, comments, tracked changes, and document styles via pandoc plus a sidecar metadata file. Not a replacement for the base docx skill when the user is authoring a new Word document from scratch — use that skill for new content, and use this one for round-trip translation.
Instrucciones de origen · Vista previa de solo lectura
name
kiss-docx-markdown
description
Translate between Word (.docx) files and Markdown with high-fidelity round-trip. Use this skill whenever the user wants to convert a Word document to Markdown, edit a .docx as text, regenerate a .docx from Markdown, diff/review Word content in git, or keep a canonical text version of a document alongside the .docx. Triggers: 'docx to markdown', 'word to md', 'convert this Word doc to markdown', 'rebuild this docx from markdown', 'edit my report in markdown', 'extract word text with formatting', 'round-trip my Word doc'. Preserves headings, lists, tables, images, footnotes, comments, tracked changes, and document styles via pandoc plus a sidecar metadata file. Not a replacement for the base docx skill when the user is authoring a new Word document from scratch — use that skill for new content, and use this one for round-trip translation.
compatibility
Requires kiss project structure with .kiss/ directory
Round-trip translation between .docx and Markdown.
Inputs
A .docx file (for export to Markdown) or a .md file produced by
this skill (for rebuild to .docx).
Optional sidecar <name>.meta.json and <name>.reference.docx
produced on the prior export — required for high-fidelity rebuild.
Optional environment variables for auto mode: KISS_DOCX_OP,
KISS_DOCX_INPUT, KISS_DOCX_OUTPUT, KISS_DOCX_ACCEPT_CHANGES,
KISS_DOCX_NO_META.
Outputs
On export (to-md): <name>.md, <name>.assets/ (extracted media),
<name>.reference.docx, and <name>.meta.json next to the input
unless --no-meta is passed.
On rebuild (to-docx): the destination .docx reconstructed from
the Markdown + sidecar + reference doc.
On round-trip check: a diff of the original Markdown against
Markdown re-extracted from the rebuilt .docx.
Context Update
Does not mutate .kiss/context.yml. Operates on user-supplied file
paths only.
User Input
$ARGUMENTS
Consider the user input before proceeding (if not empty). If the
input clearly states the operation and file (e.g. "convert report.docx
to markdown"), skip questions that are already answered.
Mode behaviour
Interactive (default — KISS_AGENT_MODE unset or interactive):
Ask one question at a time. Offer lettered options. Always recommend a
default and state why. After gathering answers, show the exact command
and ask for confirmation before instructing the user to run it.
Auto (KISS_AGENT_MODE=auto or user says "in auto mode"):
Read answer keys from the environment (see table below). Apply defaults
for any missing key and log each default as a decision of kind
default-applied. Do not ask questions; output the command immediately.
Auto mode answer keys
Key
Meaning
Default
KISS_DOCX_OP
to-md / to-docx / roundtrip
to-md
KISS_DOCX_INPUT
Input file path
(required — ask if missing)
KISS_DOCX_OUTPUT
Output file path
Derived from input name
KISS_DOCX_ACCEPT_CHANGES
true / false — accept tracked changes before export
false
KISS_DOCX_NO_META
true / false — skip sidecar (lossy)
false
Interactive workflow
Detect intent from $ARGUMENTS. If operation and input file
are already clear, jump to step 5.
Ask operation:
A) Export .docx → Markdown (default)
B) Rebuild .docx from Markdown
C) Round-trip check (export, rebuild, diff)
Ask input file path (the .docx for A/C; the .md for B).
Ask output file path — propose the derived default
(e.g. report.md for report.docx) and let the user accept or
override.
Ask about the key option for the chosen operation:
A) Accept tracked changes first? (--accept-changes) Default: no.
B) Override reference doc? (--reference-doc) Default: use sidecar.
C) No extra options.
Show the full command and ask for confirmation before running. Built on pandoc, with a sidecar metadata file for anything pandoc can't represent losslessly (comments, custom styles, core properties, tracked-change authorship).
When to use
User wants to edit a Word document's content as Markdown and regenerate the .docx.
User wants text-friendly diffs for a Word document in version control.
User wants to extract a .docx to Markdown with images, tables, and comments intact.
User asks to "convert this docx to md" or "rebuild this Word doc from markdown".
For authoring a brand-new Word document with complex styling, use the base docx skill. This skill is focused on faithful round-trip, not visual design.
Quick reference
Task
Command
docx to Markdown
python scripts/docx_to_md.py input.docx output.md
Markdown to docx
python scripts/md_to_docx.py input.md output.docx
Round-trip check
python scripts/roundtrip_check.py input.docx
Convert .doc first
soffice --headless --convert-to docx input.doc (macOS / Linux) — see Setup for the Windows form
The python … invocations work identically on macOS, Linux, and Windows — forward slashes in script paths are accepted by Python on all three platforms. The platform difference is only in setup and in invoking soffice directly.
Setup (cross-platform)
The scripts auto-prefer a project-local ./.venv in your current working directory. Run the bootstrap helper once per workspace:
macOS / Linux (bash):
cd /path/to/your/workspace # where your .docx lives
bash <skill-dir>/scripts/bash/setup_env.sh
Windows (PowerShell):
cd C:\path\to\your\workspace # where your .docx lives
pwsh <skill-dir>\scripts\powershell\setup_env.ps1
The helper creates ./.venv next to your files (not inside the skill folder) and pip installs the deps from scripts/requirements.txt. Subsequent script runs are then automatic — each script detects the venv and re-execs under it.
If the venv is missing when you run a script, you get a clear setup hint and the script exits. Pass --system-python on the command line to force the current interpreter:
# macOS / Linux
python scripts/docx_to_md.py input.docx output.md --system-python
# Windows
python scripts\docx_to_md.py input.docx output.md --system-python
pandoc is a separate system dependency (not pip-installable). Install via your package manager:
Export the Word document. The script runs pandoc and writes:
<name>.md — the Markdown source (pandoc GFM+extensions).
<name>.assets/ — extracted images and media.
<name>.reference.docx — a copy of the original, used as pandoc's reference doc on rebuild to preserve styles.
<name>.meta.json — core properties, custom styles, comment threads, tracked-change authors, and raw XML for sections pandoc doesn't round-trip cleanly.
Edit the .md file. Standard Markdown, plus pandoc extensions (fenced divs, attribute blocks, footnotes). Comments and tracked changes are represented as Markdown inline annotations — see the format spec.
Rebuild to .docx. The script runs pandoc with the reference doc, then post-processes the output to reattach metadata from the sidecar.
The sidecar is what makes this high-fidelity. Keep all four artifacts together. If the sidecar is lost, the rebuild is still correct content-wise but loses comments and some style customizations.
Markdown format
Full spec in references/format-spec.md. Highlights:
---
title: Project Brief
author: Claude
reference_doc: brief.reference.docx
docx_meta: brief.meta.json
---
# Background
The project aims to ship a new onboarding flow by end of Q3.^[Source: roadmap v4.2]
## Scope
We will support:
- Self-serve sign-up with email verification
- SSO via Okta and Google Workspace
- A guided setup wizard with checkpoints
[This section needs sign-off from Legal.]{.comment author="Claude" date="2026-04-22"}
| Milestone | Target date | Owner |
| --- | --- | --- |
| Design review | 2026-05-02 | Priya |
| Engineering kickoff | 2026-05-09 | Jin |
{#fig-flow width=6in}
::: {.tracked-insertion author="Claude" date="2026-04-22"}
Added note: we also need to update the billing docs.
:::
::: {.tracked-deletion author="Claude" date="2026-04-22"}
Deprecated paragraph about the old signup.
:::
pandoc (>= 2.18) — required for the docx ↔ md conversion. Install via brew, apt, choco, or pandoc.org.
LibreOffice (soffice) — optional, required only for --accept-changes and for .doc → .docx conversion. The scripts also look in standard install locations on macOS / Linux / Windows even when not on PATH.
Composition with the base docx skill
If the user wants visual changes (heading styles, table themes, page size), update the reference doc using the base docx skill, then re-run the rebuild. This skill handles content translation; the base skill handles authoring.
