Word DOCX Documents skill for Codex

Done well means: the document uses styles (not direct formatting) so it restyles cleanly, headings drive the navigation pane and TOC, tables repeat their header row, an edited template keeps its look, and a structural check passes before the file is handed over.

Before writing code

1. Read AGENTS.md and the manifest: Python service → python-docx; Node/TypeScript → docx (docx.js). Installing either needs network; ask for approval if the sandbox blocks it.
2. If the user has a branded template (.docx or .dotx), build from it. Styles, headers, numbering and theme fonts come free; recreating them in code is slower and worse.
3. Inspect what you are editing: python3 scripts/docx_inspect.py template.docx --text prints styles in use, outline, tables, fields, tracked changes and leftover placeholders.
4. Decide the route:

Need	Route
Generate a new document from data	python-docx / docx.js (this skill)
Many documents from one Word template with loops and conditions	$docx-templates (docxtpl / docxtemplater)
Letters to a mailing list	$mail-merge
Show edits as tracked changes or add review comments	$word-tracked-changes
Convert to PDF, HTML or Markdown	$document-conversion

python-docx: generate

from docx import Document
from docx.enum.section import WD_ORIENT
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.oxml import OxmlElement
from docx.oxml.ns import qn
from docx.shared import Cm, Pt, RGBColor

doc = Document("brand-template.docx")       # or Document() for the default template

normal = doc.styles["Normal"]
normal.font.name = "Calibri"
normal.font.size = Pt(10.5)
normal.paragraph_format.space_after = Pt(6)

doc.core_properties.title = "Q3 Operations Review"
doc.core_properties.author = "Ops Analytics"

doc.add_heading("Q3 Operations Review", level=0)       # Title style
doc.add_heading("Summary", level=1)
doc.add_paragraph("Throughput rose 12% while cost per order fell.")
for item in ("Two new carriers onboarded", "Returns backlog cleared"):
    doc.add_paragraph(item, style="List Bullet")

doc.add_heading("Regional results", level=1)
rows = [("North", 1204, "4.1%"), ("South", 980, "3.7%")]
table = doc.add_table(rows=1, cols=3)
table.style = "Table Grid"                  # must exist in the template's styles
hdr = table.rows[0]
for cell, label in zip(hdr.cells, ("Region", "Orders", "Defect rate")):
    cell.text = label
    cell.paragraphs[0].runs[0].bold = True
tr_pr = hdr._tr.get_or_add_trPr()           # repeat header row on every page
flag = OxmlElement("w:tblHeader")
flag.set(qn("w:val"), "true")
tr_pr.append(flag)
for region, orders, rate in rows:
    cells = table.add_row().cells
    cells[0].text, cells[1].text, cells[2].text = region, f"{orders:,}", rate
    for c in cells[1:]:
        c.paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.RIGHT

doc.add_picture("chart.png", width=Cm(16))
doc.paragraphs[-1].alignment = WD_ALIGN_PARAGRAPH.CENTER

landscape = doc.add_section()               # new section for a wide appendix
landscape.orientation = WD_ORIENT.LANDSCAPE
landscape.page_width, landscape.page_height = landscape.page_height, landscape.page_width

doc.save("q3-review.docx")

Page numbers, hyperlinks and other XML-level features

python-docx has no high-level API for fields or for writing hyperlinks. Use small helpers:

def add_field(paragraph, instr):
    """Insert a field such as 'PAGE', 'NUMPAGES' or 'TOC \\o "1-3" \\h \\z \\u'."""
    run = paragraph.add_run()
    for kind, text in (("begin", None), (None, instr), ("separate", None), ("end", None)):
        if kind:
            el = OxmlElement("w:fldChar")
            el.set(qn("w:fldCharType"), kind)
        else:
            el = OxmlElement("w:instrText")
            el.set(qn("xml:space"), "preserve")
            el.text = f" {text} "
        run._r.append(el)


def add_hyperlink(paragraph, url, text):
    r_id = paragraph.part.relate_to(
        url, "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink",
        is_external=True,
    )
    link = OxmlElement("w:hyperlink")
    link.set(qn("r:id"), r_id)
    run = OxmlElement("w:r")
    rpr = OxmlElement("w:rPr")
    style = OxmlElement("w:rStyle")
    style.set(qn("w:val"), "Hyperlink")
    rpr.append(style)
    run.append(rpr)
    t = OxmlElement("w:t")
    t.text = text
    run.append(t)
    link.append(run)
    paragraph._p.append(link)


footer = doc.sections[0].footer.paragraphs[0]
footer.alignment = WD_ALIGN_PARAGRAPH.RIGHT
footer.add_run("Page ")
add_field(footer, "PAGE")
footer.add_run(" of ")
add_field(footer, "NUMPAGES")

A TOC field is inserted empty; Word fills it on open only if asked. Add <w:updateFields w:val="true"/> to settings so Word offers to update fields:

upd = OxmlElement("w:updateFields")
upd.set(qn("w:val"), "true")
doc.settings.element.append(upd)

The Hyperlink character style exists in Word’s default template; in a custom template, check doc.styles and fall back to blue underlined run formatting.

python-docx: edit an existing document safely

Word splits text into runs at arbitrary points (spell-check, revisions, formatting), so "{{client}}" may be stored as "{{cli" + "ent}}". Replace at paragraph level:

def iter_paragraphs(doc):
    yield from doc.paragraphs
    for t in doc.tables:
        for row in t.rows:
            for cell in row.cells:
                yield from cell.paragraphs
    for s in doc.sections:
        for part in (s.header, s.footer, s.first_page_header, s.first_page_footer):
            if not part.is_linked_to_previous:   # reading a linked one creates a new part
                yield from part.paragraphs


def replace_in_paragraph(p, old, new):
    if old not in p.text:
        return False
    runs = p.runs
    full = "".join(r.text for r in runs)
    start = full.index(old)
    end = start + len(old)
    pos = 0
    for r in runs:                          # keep formatting of the run where the match starts
        r_start, r_end = pos, pos + len(r.text)
        pos = r_end
        if r_end <= start or r_start >= end:
            continue
        keep_before = r.text[: max(start - r_start, 0)]
        keep_after = r.text[max(end - r_start, 0):] if r_end > end else ""
        r.text = keep_before + (new if r_start <= start < r_end else "") + keep_after
    return True

Call it in a loop until it returns False for repeated placeholders. Nested tables need recursion over cell.tables. For anything beyond a few placeholders, switch to $docx-templates.

docx.js (Node)

import { writeFileSync } from "node:fs";
import {
  AlignmentType, Document, Footer, HeadingLevel, Packer, PageNumber,
  Paragraph, Table, TableCell, TableRow, TextRun, WidthType,
} from "docx";

const rows = [["North", "1,204"], ["South", "980"]];
const cell = (text, bold = false) =>
  new TableCell({ children: [new Paragraph({ children: [new TextRun({ text, bold })] })] });

const doc = new Document({
  creator: "Ops Analytics",
  title: "Q3 Operations Review",
  styles: { default: { document: { run: { font: "Calibri", size: 21 } } } }, // half-points
  sections: [{
    footers: {
      default: new Footer({
        children: [new Paragraph({
          alignment: AlignmentType.RIGHT,
          children: [new TextRun({ children: ["Page ", PageNumber.CURRENT, " of ", PageNumber.TOTAL_PAGES] })],
        })],
      }),
    },
    children: [
      new Paragraph({ text: "Q3 Operations Review", heading: HeadingLevel.TITLE }),
      new Paragraph({ text: "Regional results", heading: HeadingLevel.HEADING_1 }),
      new Table({
        width: { size: 100, type: WidthType.PERCENTAGE },
        rows: [
          new TableRow({ tableHeader: true, children: [cell("Region", true), cell("Orders", true)] }),
          ...rows.map((r) => new TableRow({ children: r.map((v) => cell(v)) })),
        ],
      }),
    ],
  }],
});

writeFileSync("q3-review.docx", await Packer.toBuffer(doc));

docx.js builds new documents only; it cannot open and edit an existing .docx. For edits in Node, use docxtemplater ($docx-templates) or unzip and patch the XML deliberately.

Hard rules

• Never insert empty paragraphs for spacing or manual page breaks for layout; use paragraph_format.space_before/after, keep_with_next, and page_break_before.
• Never fake headings with bold Normal text; use Heading 1-3 so the outline, TOC and accessibility tree work.
• Set fonts on styles, not runs. East Asian text also needs style.element.rPr.rFonts.set(qn("w:eastAsia"), "Yu Gothic") on the style.
• Units: python-docx uses EMU internally; always pass Pt, Cm, Inches. docx.js font size is in half-points and widths in twips (1/20 pt) unless a WidthType says otherwise.
• table.style = "..." raises KeyError if the style is not in the document; the default template has Table Grid and Light Grid Accent 1, many corporate templates do not.
• Images: size explicitly (width only keeps aspect ratio); provide alt text where supported.
• Save to a new filename; never overwrite the user’s source template.

Verification

python3 scripts/docx_inspect.py q3-review.docx --strict
soffice --headless --convert-to pdf --outdir /tmp/preview q3-review.docx   # optional visual check

• The inspector shows the expected heading outline, every table has a repeating header, no leftover {{placeholders}}, no spacing paragraphs, no unexpected tracked changes.
• Re-open with Document("q3-review.docx") in a test and assert key paragraphs and table cell values.
• If LibreOffice is available, render to PDF and look at page breaks, table widths and footer numbering; Word and LibreOffice differ slightly, so confirm critical layout in Word.

Output summary

**Created:** reports/q3-review.docx (from brand-template.docx)
**Structure:** Title, 4 Heading 1 sections, 2 tables (header rows repeat), 1 chart image
**Fields:** PAGE / NUMPAGES footer; TOC refreshes when opened in Word
**Checks:** docx_inspect --strict clean; PDF preview reviewed (6 pages)