DOCX creation, editing, and analysis

Where to look

Overview

A .docx file is a ZIP archive containing XML. Read it with pandoc, edit it by unpacking the XML and repacking, or create a new one with the docx npm package.

Common Operations

# Extract text as markdown (accepts tracked changes by default)
pandoc document.docx -o out.md

# Extract preserving tracked changes as markup
pandoc --track-changes=all document.docx -o out.md

# Convert legacy .doc → .docx (required before editing)
python scripts/office/soffice.py --headless --convert-to docx document.doc

# Convert to images (via PDF)
python scripts/office/soffice.py --headless --convert-to pdf document.docx
pdftoppm -jpeg -r 150 document.pdf page

# Accept all tracked changes
python scripts/accept_changes.py input.docx output.docx

# Unpack for raw XML editing
python scripts/office/unpack.py document.docx unpacked/

Editing Existing Documents

Follow all 3 steps in order.

Step 1: Unpack

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

Extracts XML, pretty-prints, merges adjacent runs, and converts smart quotes to XML entities (“ etc.) so they survive editing. Use --merge-runs false to skip run merging.

Step 2: Edit XML

Edit files in unpacked/word/. See references/ooxml.md for element patterns (tracked changes, comments, images, schema rules).

Use "Claude" as the author for tracked changes and comments, unless the user explicitly requests use of a different name.

Use the Edit tool directly for string replacement. Do not write Python scripts. Scripts introduce unnecessary complexity. The Edit tool shows exactly what is being replaced.

CRITICAL: Use smart quotes for new content. When adding text with apostrophes or quotes, use XML entities to produce smart quotes:

<!-- Use these entities for professional typography -->
<w:t>Here&#x2019;s a quote: &#x201C;Hello&#x201D;</w:t>

Adding comments: Use comment.py to handle boilerplate across multiple XML files (text must be pre-escaped XML):

python scripts/comment.py unpacked/ 0 "Comment text with & and ’"
python scripts/comment.py unpacked/ 1 "Reply text" --parent 0  # reply to comment 0
python scripts/comment.py unpacked/ 0 "Text" --author "Custom Author"  # custom author name

Then add markers to document.xml (see the Comments section in references/ooxml.md).

Step 3: Pack

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.

Auto-repair will fix:

• durableId >= 0x7FFFFFFF (regenerates valid ID)
• Missing xml:space="preserve" on <w:t> with whitespace

Auto-repair won't fix:

• Malformed XML, invalid element nesting, missing relationships, schema violations

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. Don't inject tracked change tags inside a run.
• Preserve <w:rPr> formatting: Copy the original run's <w:rPr> block into your tracked change runs to maintain bold, font size, etc.

Dependencies

• pandoc — text extraction (brew install pandoc)
• docx npm package — creating new documents (bun install -g docx)
• LibreOffice — PDF conversion and accepting tracked changes; scripts/office/soffice.py auto-configures it for sandboxed environments (brew install --cask libreoffice)
• Poppler — pdftoppm for image conversion (brew install poppler)
• defusedxml — used by unpack.py, pack.py, comment.py, and the run/redline helpers. Declared inline via uv script metadata — uv run scripts/... installs on first run.

Scripts & Templates

The helpers referenced throughout this skill live under scripts/ next to SKILL.md — not embedded in this document.

Python scripts (scripts/):

XML templates (scripts/templates/): comments.xml, commentsExtended.xml, commentsExtensible.xml, commentsIds.xml, people.xml — minimal valid root documents used when bootstrapping a new comments payload.

Invoke scripts with uv run scripts/<path> (deps auto-install from each script's inline metadata) or python scripts/<path> if you've pre-installed defusedxml. Scripts add their parent dir to sys.path at import time, so running from the skill root, the scripts/ dir, or any other cwd all work.