docx

DOCX Skill

Create, read, and edit Word documents — reports, memos, letters, letterheads, tables of contents, tracked changes (redlining), and comments. A .docx is a ZIP archive of XML files; this skill covers both the high-level creation path and surgical XML editing.

When to Use

Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx) or Word templates (.dotx). Triggers include: any mention of "Word doc", ".docx", ".dotx", or requests for a "report", "memo", "letter", or similar deliverable as a Word file; extracting or reorganizing content from .docx files; find-and-replace in Word files; inserting images; tracked changes or comments. Do NOT use for PDFs (see the pdf skill), spreadsheets (xlsx), or presentations (powerpoint).

Prerequisites

npm ls docx --depth=0 2>/dev/null | grep -q docx || npm install docx   # creation (docx-js)
pip show pandoc >/dev/null 2>&1 || true; which pandoc || sudo apt install -y pandoc   # reading
which soffice || sudo apt install -y libreoffice     # rendering/verification
which pdftoppm || sudo apt install -y poppler-utils  # PDF → images
pip install defusedxml lxml   # validation scripts

macOS: brew install pandoc libreoffice poppler.

Quick Reference

Task	Approach
Create a new document	Write a docx (npm) script — see gotchas below
Edit an existing document	unzip → edit word/document.xml → zip (docx-js cannot open existing files)
Read content	pandoc -t markdown file.docx (or read_file, which auto-extracts .docx text)

Script paths below are relative to this skill's directory.

Creating with docx-js — gotchas

Write the script and require('docx'). The model knows the API; these are the footguns:

• Page size defaults to A4. For US Letter set page: { size: { width: 12240, height: 15840 } } (DXA; 1440 = 1″).
• Landscape: pass portrait dimensions and orientation: PageOrientation.LANDSCAPE — docx-js swaps width/height internally.
• Tables need dual widths: set columnWidths on the table AND width on every cell, both in WidthType.DXA (PERCENTAGE breaks in Google Docs). Column widths must sum to the table width.
• Table shading: use ShadingType.CLEAR, never SOLID (renders black).
• Lists: never insert • literally; use a numbering config with LevelFormat.BULLET.
• ImageRun requires type: ("png", "jpg", …).
• PageBreak must be inside a Paragraph.
• Never use \n — use separate Paragraph elements.
• TOC: headings must use built-in HeadingLevel.*; custom heading styles need outlineLevel set or they won't appear.
• Don't use a table as a horizontal rule — use a paragraph bottom border instead.
• Dot-leader / right-aligned-on-same-line: use PositionalTab (alignment: PositionalTabAlignment.RIGHT, leader: PositionalTabLeader.DOT) inside a TextRun, not literal . or space padding.