Docx

DOCX creation, editing, and analysis

Where to look

| Task | Go to | |------|-------| | Create a new .docx (reports, memos, letters, formatted output) | references/docx-js.md | | Edit an existing .docx (find-replace, tweak XML, add tracked changes) | ## Editing Existing Documents below | | Raw OOXML / schema (tracked changes, comments, images at XML level) | references/ooxml.md | | Accept all tracked changes | scripts/accept_changes.py | | Add a comment | scripts/comment.py | | Unpack / repack / validate | scripts/office/{unpack,pack,validate}.py |

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:

Here’s a quote: “Hello”

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

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 `` with whitespace

Auto-repair won't fix:

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

Common Pitfalls

• **Replace entire ` elements**: When adding tracked changes, replace the whole ... block with ......` as siblings. Don't inject tracked change tags inside a run.
• **Preserve ` formatting**: Copy the original run's ` 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/):

| Path | Purpose | |------|---------| | accept_changes.py | Accept all tracked changes via LibreOffice | | comment.py | Add comments to a DOCX | | office/unpack.py | Unpack DOCX/PPTX/XLSX for XML editing | | office/pack.py | Repack an unpacked directory into a valid DOCX/PPTX/XLSX | | office/soffice.py | LibreOffice wrapper with sandbox-friendly env setup | | office/validate.py | Validate DOCX structure and content | | office/helpers/merge_runs.py | Merge adjacent runs with identical formatting | | office/helpers/simplify_redlines.py | Collapse adjacent w:ins / w:del | | office/validators/base.py | Shared BaseSchemaValidator (XML, namespace, ID-uniqueness, XSD, relationship checks) | | office/validators/docx.py | DOCXSchemaValidator — full WordprocessingML schema + tracked-change + relationship validation | | office/validators/pptx.py | PPTXSchemaValidator — PresentationML schema validation (shared code used by the pptx/xlsx skills too) | | office/validators/redlining.py | RedliningValidator — tracked-change integrity (accept-all round-trip test) |

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/ (deps auto-install from each script's inline metadata) or python scripts/ 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: npow
• Source: npow/claude-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.