docx

name	docx
description	Create, read, edit, or convert Microsoft Word documents while preserving professional document structure. Use when a .docx file is a primary input or requested output, including tracked changes, comments, images, headings, page furniture, or polished reports and letters. Not for PDFs, spreadsheets, Google Docs, or unrelated coding tasks.
license	Proprietary. LICENSE.txt has complete terms
allowed-tools	Bash(uv*, pandoc*, node*, npx*, mkdir*, ls*), Read, Write, Edit

DOCX creation, editing, and analysis

Overview

A .docx file is a ZIP archive containing XML files.

Quick Reference

Task	Approach
Read/analyze content	pandoc or unpack for raw XML
Create new document	Use docx-js — see references/docx-js-patterns.md
Edit existing document	Unpack → edit XML → repack — see Editing below

Converting .doc to .docx

uv run python scripts/office/soffice.py --headless --convert-to docx document.doc

Reading Content

# Text extraction with tracked changes
pandoc --track-changes=all document.docx -o output.md

# Raw XML access
uv run python scripts/office/unpack.py document.docx unpacked/

Converting to Images

uv run python scripts/office/soffice.py --headless --convert-to pdf document.docx
pdftoppm -jpeg -r 150 document.pdf page

Accepting Tracked Changes

uv run python scripts/accept_changes.py input.docx output.docx

---

Creating New Documents

Generate .docx files with JavaScript using docx-js. Install: npm install -g docx

Full code patterns (setup, page size, styles, lists, tables, images, hyperlinks, footnotes, tab stops, multi-column layouts, TOC, headers/footers): references/docx-js-patterns.md

Critical Rules for docx-js

• Set page size explicitly — defaults to A4; use US Letter (12240 x 15840 DXA) for US documents
• Landscape: pass portrait dimensions — docx-js swaps width/height internally
• Never use \n — use separate Paragraph elements
• Never use unicode bullets — use LevelFormat.BULLET with numbering config
• PageBreak must be in Paragraph — standalone creates invalid XML
• ImageRun requires type — always specify png/jpg/etc
• Always set table width with DXA — never use WidthType.PERCENTAGE (breaks in Google Docs)
• Tables need dual widths — columnWidths array AND cell width, both must match
• Use ShadingType.CLEAR — never SO[Project] for table shading
• Never use tables as dividers — use border on Paragraph instead; for two-column footers, use tab stops
• TOC requires HeadingLevel only — no custom styles on heading paragraphs
• Override built-in styles — use exact IDs: "Heading1", "Heading2", etc.
• Include outlineLevel — required for TOC (0 for H1, 1 for H2, etc.)

Validation

uv run python scripts/office/validate.py doc.docx

---

Editing Existing Documents

Follow all 3 steps in order.

Step 1: Unpack

uv run python scripts/office/unpack.py document.docx unpacked/

Extracts XML, pretty-prints, merges adjacent runs, and converts smart quotes to XML entities. Use --merge-runs false to skip run merging.

Step 2: Edit XML

Edit files in unpacked/word/. Use "Claude" as the author for tracked changes and comments.

Use the Edit tool directly for string replacement. Do not write Python scripts.

Use smart quotes for new content:

Entity	Character
‘	' (left single)
’	' (right single / apostrophe)
“	" (left double)
”	" (right double)

Adding comments:

uv run python scripts/comment.py unpacked/ 0 "Comment text with & and ’"
uv run python scripts/comment.py unpacked/ 1 "Reply text" --parent 0

Then add markers to document.xml.

Full XML patterns (tracked changes, comments, images): references/xml-reference.md

Step 3: Pack

uv run python scripts/office/pack.py unpacked/ output.docx --original document.docx

Validates with auto-repair, condenses XML, and creates DOCX. Use --validate false to skip.

Common Pitfalls

• Replace entire <w:r> elements: When adding tracked changes, replace the whole <w:r>...</w:r> block with <w:del>...<w:ins>... as siblings.
• Preserve <w:rPr> formatting: Copy the original run's <w:rPr> block into your tracked change runs.

---

Dependencies

• pandoc: Text extraction
• docx: npm install -g docx (new documents)
• LibreOffice: PDF conversion (auto-configured via scripts/office/soffice.py)
• Poppler: pdftoppm for images