docx-creation-skill

What I do

• Create new .docx via docx-js; read via pandoc or raw XML; edit by unpack → modify XML → repack
• Tracked changes (insertions/deletions), comments, images, tables, TOCs, letterheads
• Convert .doc→.docx, .docx→PDF, .docx→images

Use for: "Word doc" / .docx mentions; reports, memos, letters, templates; tracked-changes review.
NOT for: PDFs, spreadsheets, Google Docs, unrelated coding.

Prerequisites

pandoc (extraction) · npm install -g docx (creation) · LibreOffice via scripts/soffice.py (PDF) · Poppler pdftoppm (images)

House scripts

python scripts/soffice.py --headless --convert-to docx document.doc   # legacy .doc → .docx
pandoc --track-changes=all document.docx -o output.md                 # read incl. tracked changes
python scripts/unpack.py document.docx unpacked/                      # raw XML access
python scripts/accept_changes.py input.docx output.docx               # accept all tracked changes
python scripts/soffice.py --headless --convert-to pdf document.docx && pdftoppm -jpeg -r 150 document.pdf page

Creating new documents (docx-js) — critical rules

Full code patterns: `reference.md` (setup, styles, numbering, tables, images, hyperlinks, TOC, headers/footers).

• Set page size explicitly — docx-js defaults to A4; US Letter = 12240 × 15840 DXA (1440 DXA = 1″)
• Never \n — separate Paragraph elements
• Never unicode bullets — numbering.config with LevelFormat.BULLET; same reference continues numbering, different reference restarts
• PageBreak must sit inside a Paragraph — standalone is invalid XML
• ImageRun requires type (png/jpg/…) and altText with title+description+name
• Tables: dual widths — columnWidths array AND per-cell width, both DXA, summing to table width; WidthType.DXA only (percentages break in Google Docs)
• ShadingType.CLEAR, never SOLID (black backgrounds)
• TOC requires HeadingLevel only — override built-in styles by exact ID ("Heading1") and include outlineLevel (0 for H1), else TOC won't generate

Validate after creation: python scripts/validate.py doc.docx — on failure, unpack, fix XML, repack.

Editing existing documents — 3 steps, in order

1. python scripts/unpack.py document.docx unpacked/ (pretty-prints, merges runs)
2. Edit unpacked/word/*.xml — patterns in `reference.md` (tracked changes, comments, images, element order)
3. python scripts/pack.py unpacked/ output.docx --original document.docx (validates + auto-repairs)

House rules: tracked-change/comment author = "Claude" unless the user names another; smart quotes via XML entities (’ “ ”) for new content.

Design aesthetics — no generic AI slop

Documents must look designed, not generated. Avoid: Word-gallery defaults (blue headings, Calibri-everything), identical cookie-cutter sections, one font size throughout, equal-width thin-bordered tables, default blue/gray, unbroken walls of text, uneven spacing.

Every document gets ≥1 signature element: 3+ levels of typographic hierarchy (title 28–36pt bold / H1 20–24 / H2 16–18 / body 11–12), 1–2 consistent accent colors, styled table headers (fill + white text, horizontal borders only), pull quotes/callout boxes, generous whitespace (1–1.5″ margins), non-blank header/footer.

Before formatting ask: what is this document's visual identity, what should the reader feel, would a designer approve? (Per-type styling table in `reference.md`.)

Verification

validate.py passes · opens in Word/LibreOffice clean · page size correct · tables/images/TOC/headers render · tracked changes visible in review pane.