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 Creating New Documents below | | Edit existing document | Unpack -> edit XML -> repack |

Reading Content

# Text extraction with tracked changes
pandoc --track-changes=all document.docx -o output.md

Converting .doc to .docx

python scripts/office/soffice.py --headless --convert-to docx document.doc

Creating New Documents

Generate .docx files with JavaScript. Install: npm install -g docx

Setup

const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,
        Header, Footer, AlignmentType, PageOrientation, LevelFormat, ExternalHyperlink,
        TableOfContents, HeadingLevel, BorderStyle, WidthType, ShadingType,
        VerticalAlign, PageNumber, PageBreak } = require('docx');

const doc = new Document({ sections: [{ children: [/* content */] }] });
Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));

Critical Rules for docx-js

• Set page size explicitly — defaults to A4; use US Letter (12240 x 15840 DXA) for US docs
• Landscape: pass portrait dimensions — docx-js swaps internally
• Never use \n — use separate Paragraph elements
• Never use unicode bullets — use LevelFormat.BULLET with numbering config
• PageBreak must be in Paragraph — standalone creates invalid XML
• ImageRun requires type — always specify png/jpg/etc
• Always set table width with DXA — never use WidthType.PERCENTAGE (breaks in Google Docs)
• Tables need dual widths — columnWidths array AND cell width, both must match
• Use ShadingType.CLEAR — never SOLID for table shading
• TOC requires HeadingLevel only — no custom styles on heading paragraphs
• Override built-in styles — use exact IDs: "Heading1", "Heading2", etc.
• Include outlineLevel — required for TOC (0 for H1, 1 for H2, etc.)

Editing Existing Documents

Follow all 3 steps in order.

Step 1: Unpack

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

Step 2: Edit XML

Edit files in unpacked/word/. Use "Claude" as the author for tracked changes and comments.

Use the Edit tool directly for string replacement. Do not write Python scripts.

Step 3: Pack

python scripts/office/pack.py unpacked/ output.docx --original document.docx

XML Reference

Tracked Changes

Insertion:

  inserted text

Deletion:

  deleted text

Dependencies

• pandoc: Text extraction
• docx: npm install -g docx (new documents)
• LibreOffice: PDF conversion
• Poppler: pdftoppm for images

Source & license

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

• Author: Leo-Atienza
• Source: Leo-Atienza/atlas-claude
• License: MIT

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