docx

docx

Work with Microsoft Word .docx files. The format is OOXML — a zip container holding XML parts (word/document.xml, styles.xml, numbering.xml, headers, footers, relationships). Treat structure as primary; rendered text is a view.

Decide the path first

Pick one path up front. The right path depends only on what is on disk before you start.

You have	Goal	Path
Existing .docx	Read text/structure	A. Inspect
Existing .docx	Modify content while keeping styles	B. Edit-in-place
Nothing or a brief	Build a new doc	C. Create from scratch

If the user hands you a doc and asks for changes, default to path B and treat the input as the visual style baseline. Only choose path C when the user says "start fresh" or there is no input.

---

Path A: Inspect

Dump structure as JSON for inspection without mutating anything.

python {baseDir}/scripts/inspect_docx.py /path/to/doc.docx

Output schema:

{
  "paragraphs": [{"index": 0, "text": "...", "style": "Heading 1"}, ...],
  "tables": [[["row0,col0", "row0,col1"], ...], ...],
  "sections": 1,
  "has_tracked_changes": false
}

Use this whenever you need to see what is in the doc before deciding how to edit. The output is stable and machine-readable — diff two inspect outputs to verify a round-trip preserved everything you intended.

---

Path B: Edit in place

Two sub-strategies; pick by how invasive the edit is.

B1. Run-level text replacement (preferred)

When the change is "swap this string" or "fill these placeholders": mutate runs in place. This preserves all theme/style/font settings.

python {baseDir}/scripts/edit_docx.py input.docx ops.json --out output.docx

ops.json is a list of operations:

[
  {"op": "replace_run", "para": 0, "run": 0, "text": "Q3 Review"},
  {"op": "replace_text", "find": "{{CLIENT}}", "with": "Acme Corp"}
]

Edit at the run level, not the paragraph level — replacing whole paragraph text drops formatting. If a placeholder spans multiple runs (often happens when the original template applied bold/italic mid-word), the helper script collapses runs into the first one and clears the rest.

B2. Structural edits (sections / page layout / numbering)

python-docx exposes paragraphs, tables, and runs but has limited support for page layout, numbering definitions, and tracked changes. For those, unzip the .docx, patch word/document.xml and adjacent parts, and repack:

mkdir _unpacked && (cd _unpacked && unzip -q ../input.docx)
# edit _unpacked/word/document.xml
(cd _unpacked && zip -q -r ../output.docx . -x "*.DS_Store")

Rules when patching XML:

• Use defusedxml.ElementTree or lxml, not stdlib xml.etree.ElementTree. ET drops or rewrites namespace prefixes (w:, r:) in ways Word refuses to load.
• Preserve xml:space="preserve" on <w:t> elements that hold leading or trailing whitespace.
• [Content_Types].xml must list every part type. Removing a header without also removing its override entry yields a "repair" prompt in Word.
• Numbering definitions live in numbering.xml; bullet/number changes must patch the numbering ID, not just the visible text.

When done, validate by opening in LibreOffice headless before declaring success — silent failures are common.

---

Path C: Create from scratch

For a simple Markdown source, run the export script with the Markdown on stdin:

python {baseDir}/scripts/export_markdown_docx.py --out out.docx < draft.md

For structured content, use a JSON specification:

python {baseDir}/scripts/create_docx.py spec.json --out out.docx

spec.json describes content declaratively:

{
  "metadata": {"title": "Q3 Review", "author": "Wei E."},
  "body": [
    {"kind": "heading", "level": 1, "text": "Q3 Review"},
    {"kind": "paragraph", "text": "Revenue +18% YoY."},
    {"kind": "table", "rows": [["Metric", "Value"], ["Revenue", "$2.1M"]]}
  ]
}

For programmatic use call python-docx directly:

from docx import Document
doc = Document()
doc.add_heading("Q3 Review", level=1)
doc.add_paragraph("Revenue +18% YoY.")
table = doc.add_table(rows=2, cols=2)
table.rows[0].cells[0].text = "Metric"
doc.save("out.docx")

See references/python_docx.md for paragraphs, styles, numbering, tables, headers/footers, and section breaks.

---

Tracked changes

Tracked changes are stored in word/document.xml as <w:ins> and <w:del> elements. python-docx does not expose them as first-class objects — the inspect helper sets has_tracked_changes: true when any w:ins or w:del element is found, and you must resolve them by patching XML directly. Treat docs with tracked changes as read-only until reviewers accept or reject the revisions.

---

Common pitfalls

Symptom	Cause	Fix
Word reports "needs repair"	Removed a header part but left override in [Content_Types].xml	Strip the override entry too
Text replacement drops bold/italic	Replaced paragraph.text instead of editing runs	Use op: replace_run
Numbering restarts unexpectedly	Edited a list item across two abstractNum definitions	Patch numbering.xml; rebuild numbering IDs
Smart-quote characters render as garbage	XML read with stdlib ET dropped namespaces	Switch to defusedxml or lxml
Long string overflows	Cell width is fixed in the template	Either shorten or compute auto-fit before save

---

Boundaries

• This skill is for .docx (OOXML WordprocessingML). It does not handle .doc (legacy binary) or Google Docs. Convert via LibreOffice or Word export first.
• Do not run macro-enabled .docm / VBA. The runtime sandbox does not execute embedded code, and security scanners flag mixed content.
• For PDF generation from a .docx, hand off to LibreOffice headless or a separate PDF skill. This skill stops at .docx.