Docx

---
name: docx
description: "Use for creating, editing, extracting, converting, and reviewing Word documents."
defaultProjectInstall: true
defaultProjectInstallOrder: 50
---

# Word Document Skill

Under the hood, .docx is a ZIP container holding XML parts. Creation, reading, and modification all operate on this XML structure.

**Visual and typographic standards:** Consult `skills/design-foundations/SKILL.md` for color palette, typeface selection, and layout principles (single accent color with neutral tones, no decorative graphics, WCAG-compliant contrast). Use widely available sans-serif typefaces like Arial or Calibri as your baseline.

## Choosing an approach

| Objective | Technique | Reference |
|-----------|-----------|-----------|
| Create a document from scratch | `docx` npm module (JavaScript) | See CREATION.md |
| Edit an existing file | Unpack to XML, modify, repack | See EDITING.md |
| Pull out text | `anydoc document.docx -o output.md` | For redline content use `pandoc document.docx -o output.md --track-changes=all` |
| Handle legacy .doc format | `soffice --headless --convert-to docx file.doc` | Convert before any XML work |
| Rebuild from a PDF | Run `pdf2docx`, then patch issues | See below |
| Export pages as images | `soffice` to PDF, then `pdftoppm` | See below |
| Flatten tracked changes | `python3 skills/docx/scripts/accept_changes.py in.docx out.docx` | Requires LibreOffice |

System tools such as `anydoc`, `pandoc`, `soffice`, and `pdftoppm` are installed in the sandbox. Python packages such as `lxml`, `python-docx`, and `pdf2docx` are pre-installed — run scripts with `python3`. Use `uv run --with <package>` only for a package that is not pre-installed.

## Editing professional documents

Finance, legal, and other corporate documents carry conventions that are easy to break without noticing. Honor these whenever you create or edit one — violating them is what makes output read as obviously machine-generated:

- **Format with Word styles, never literal markdown.** Map `#` to a Heading style, `**bold**` to a bold run, `*italic*` to an italic run, and `>` to a block-quote style. Never leave raw `#`, `**`, `>`, or `- ` characters in the document body — literal markdown is the clearest tell that a file was generated. Apply named paragraph styles (Heading 1, Normal) rather than hand-setting fonts, so the document's theme and any brand template stay intact.
- **Treat tracked changes as a record, not scratch space.** If a document already has tracked changes, keep your own edits tracked, and never accept or reject someone else's redlines — each is attributed to a named reviewer. For contract edits, default to a tracked-changes redline and offer a clean accepted copy only if asked.
- **Keep fields and links live.** Cross-references, tables of contents, page numbers, dates, and linked Excel/OLE objects (`REF`, `PAGEREF`, `TOC`, `DATE`, `DOCPROPERTY`, `NUMPAGES`, `LINK`) must stay as fields. Re-typing "Section 2.1" or a linked figure as flat text severs every downstream reference. Don't renumber legal clauses (1.1, (a), (i)) without instruction — referenced numbering will desync.
- **Match the document's number dialect.** Sample existing figures before adding new ones: currency style (`$1.2bn` vs `$1.2B` vs `$1.2MM`), comma separators, decimal precision per column, and negatives in parentheses for finance (`($1,234)`, not `-$1,234`). In legal text, follow the spelled-out-then-numeral convention already in use (`Thirty (30) days`).
- **Defined terms are load-bearing.** In contracts, `"the Agreement"` and `"the agreement"` mean different things. Scan the definitions section and inline `("Defined Term")` / `"Defined Term" means …` patterns, then preserve their exact capitalization, pluralization, quote style (curly vs straight), and emphasis (bold/underline) in any new text you generate.
- **Preserve markings and placeholders verbatim.** Keep confidentiality and privilege banners (`PRIVILEGED & CONFIDENTIAL`, `ATTORNEY WORK PRODUCT`) in the page header, and never add new ones unless asked. Leave deliberate blanks and notes (`[•]`, `[TBD]`, `[NTD: …]`, `[XX]`) untouched — on a "finalize" request, flag what's still missing rather than guessing a value.
- **Don't disturb template scaffolding.** Content controls and custom XML parts databind firm-managed templates. Insert text into a control's range only; never delete the control, rename its tag, or strip XML parts, and don't "tidy" branded tables or theme fonts.
- **Check metadata before sharing.** Before any export or hand-off, scan for leftover tracked changes, comments, hidden text, and author metadata, and surface them — never claim metadata was scrubbed without actually removing it.

## PDF to Word

Start by running `pdf2docx` to get a baseline .docx, then correct any artifacts. Never skip the automated conversion and attempt to rebuild manually.
`pdf2docx` is pre-installed — run the conversion code with `python3`.

```python
from pdf2docx import Converter

parser = Converter("source.pdf")
parser.convert("converted.docx")
parser.close()
```

Once you have the converted file, address any problems (misaligned tables, broken hyperlinks, shifted images) by unpacking and editing the XML directly (see EDITING.md).

## Image rendering

```bash
soffice --headless --convert-to pdf document.docx
pdftoppm -jpeg -r 150 document.pdf page
ls page-*.jpg   # always ls to discover actual filenames — zero-padding varies by page count
```

After generating the document, run a verification pass yourself: inspect extracted text, render preview images when useful, and fix issues before delivering the file.