docx

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.md
Edit existing document	Unpack → edit XML → repack
Redlining (tracked changes)	Use Document library — see references/ooxml.md

Converting .doc to .docx

Legacy .doc files must be converted before editing:

python scripts/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
python scripts/unpack.py document.docx unpacked/

Converting to Images

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

Accepting Tracked Changes

To produce a clean document with all tracked changes accepted (requires LibreOffice):

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

---

Creating New Documents

Generate .docx files with JavaScript. See references/docx-js.md for the complete API reference.

Workflow

1. MANDATORY — READ ENTIRE FILE: Read references/docx-js.md completely before proceeding.
2. Create a JavaScript/TypeScript file using Document, Paragraph, TextRun components.
3. Validate: python scripts/validate.py --original <any_existing.docx> unpacked/ or after packing.

---

Editing Existing Documents

Follow all 3 steps in order.

Step 1: Unpack

python scripts/unpack.py document.docx unpacked/

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

Note the suggested RSID printed by the unpack script — use it for tracked changes.

Step 2: Edit XML

Edit files in unpacked/word/. See references/ooxml.md for XML patterns and the Document Library API.

Two approaches:

1. Direct XML editing — Use the agent's native edit tool for string replacements. Best for simple tracked changes and straightforward edits.
2. Document Library (Python) — Use for complex batched operations, programmatic node finding, and redlining workflows. See "Document Library" section in references/ooxml.md.

Using the Document Library

# Set PYTHONPATH to the skill root, then run your script
PYTHONPATH=/path/to/docx-skill uv run your_script.py

from scripts.document import Document, DocxXMLEditor

doc = Document("unpacked", author="Claude", initials="C")
node = doc["word/document.xml"].get_node(tag="w:r", contains="old text")
doc["word/document.xml"].replace_node(node, "<w:del>...<w:ins>...")
doc.save()

Adding Comments

Use comment.py to handle boilerplate across multiple XML files:

python scripts/comment.py unpacked/ 0 "Comment text with & and ’"
python scripts/comment.py unpacked/ 1 "Reply text" --parent 0  # reply to comment 0

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

Step 3: Pack

python scripts/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

---

Redlining Workflow for Document Review

This workflow is for comprehensive tracked changes on someone else's document. See references/ooxml.md for the complete Document Library API and XML patterns.

Batching Strategy: Group related changes into batches of 3-10 changes. This makes debugging manageable while maintaining efficiency.

Principle: Minimal, Precise Edits Only mark text that actually changes. Repeating unchanged text makes edits harder to review and appears unprofessional. Break replacements into: [unchanged text] + [deletion] + [insertion] + [unchanged text].

Tracked changes workflow

1. Get markdown representation: pandoc --track-changes=all path-to-file.docx -o current.md
2. Identify and group changes: Organize into logical batches (by section, type, or proximity)
3. Read documentation and unpack:
   • MANDATORY: Read references/ooxml.md completely
   • Unpack: python scripts/unpack.py file.docx dir
   • Note the suggested RSID
4. Implement changes in batches: Use the Document Library for complex operations, or edit XML directly for simple ones
5. Pack: python scripts/pack.py dir reviewed.docx --original file.docx
6. Final verification: pandoc --track-changes=all reviewed.docx -o verification.md

---

Dependencies

• pandoc: Text extraction (apt-get install pandoc)
• docx: npm install -g docx (new documents)
• LibreOffice: PDF conversion, tracked change acceptance (via scripts/soffice.py)
• Poppler: pdftoppm for images (apt-get install poppler-utils)
• defusedxml: Secure XML parsing (pip install defusedxml)