Word Documents (.docx) skill for Claude Code

Done well means: the document uses real styles (Heading 1–3, Normal, List Bullet, a table style) so it navigates, reflows, and restyles in Word; edits preserve everything you did not intend to change, including tracked changes and comments; and the result was opened or converted to verify it renders, not just saved.

Setup and tool choice

pip install "python-docx>=1.2"     # Python; 1.2 adds comments
npm i docx                         # JavaScript generation (docx v9)
# optional: LibreOffice for rendering/conversion checks (soffice --headless)

Task	Use
Generate a new document from data (Python)	python-docx, starting from a template .docx that holds the styles
Generate in Node/browser	docx package (declarative tree, Packer.toBuffer)
Fill a branded template with placeholders and loops	docxtpl (Jinja2 in .docx) — keeps the template’s design intact
Edit an existing document	python-docx after inspecting it; raw OOXML only for features python-docx lacks
Convert to PDF or legacy .doc	soffice --headless --convert-to pdf file.docx
Markdown to .docx	pandoc (see markdown-publishing)
Plain text extraction	python-docx paragraphs + tables, or pandoc -t plain

Step 1: inspect before editing

python3 scripts/docx_inspect.py contract.docx
python3 scripts/docx_inspect.py contract.docx --fail-on-revisions   # exit 1 if tracked changes/comments

Standard library only. It reports tracked insertions/deletions/moves/format changes and their authors, whether Track Changes is on, comments, fields (TOC, PAGE, REF), styles in use, runs with direct formatting, the heading outline, tables, images, sections, macros, and metadata.

If tracked changes exist, stop and ask the user: accept/reject them first in Word, or preserve them. python-docx does not model revisions: paragraph.text skips text inside <w:ins> and ignores <w:del>, so naive find-and-replace on such a document produces wrong text and can corrupt the revision markup.

Generate a document

Start from a template so styles, fonts, margins, and headers come from design, not code:

from docx import Document
from docx.enum.section import WD_ORIENT
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.shared import Inches, Pt

doc = Document("template.docx")          # or Document() for Word's default styles

doc.core_properties.title = "Quarterly Report"
doc.core_properties.author = "Finance Team"

doc.add_heading("Quarterly Report", level=0)       # Title style
doc.add_heading("Summary", level=1)
doc.add_paragraph("Revenue grew 12% quarter over quarter.")
doc.add_paragraph("Churn fell below 2%", style="List Bullet")

p = doc.add_paragraph()
p.add_run("Note: ").bold = True
p.add_run("figures are unaudited.")

rows = [("Region", "Revenue"), ("EMEA", "1.2M"), ("APAC", "0.9M")]
table = doc.add_table(rows=len(rows), cols=2)
table.style = "Table Grid"                          # must exist in the template
for r, values in enumerate(rows):
    for c, value in enumerate(values):
        table.cell(r, c).text = value
for cell in table.rows[0].cells:
    cell.paragraphs[0].runs[0].bold = True
# Repeating header rows need the w:tblHeader element on the first row (raw XML or a template table style)

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

# Landscape section for a wide table
section = doc.add_section()
section.orientation = WD_ORIENT.LANDSCAPE
section.page_width, section.page_height = section.page_height, section.page_width

header = doc.sections[0].header.paragraphs[0]
header.text = "Acme Ltd - Confidential"

doc.save("report.docx")

Rules:

• Use styles for appearance. Define fonts and spacing in the template’s styles (or doc.styles["Normal"].font.name = "Calibri"; .size = Pt(11)), not per run.
• Use add_heading / heading styles for structure; never bold Normal text as a fake heading.
• Built-in style names must exist in the document: Word’s default template has them, a custom template may not (KeyError: no style with name ...). List them with [s.name for s in doc.styles].
• Images: set width only, so aspect ratio is kept; 6–6.5 in fits A4/Letter with default margins.
• A table of contents is a field; python-docx cannot compute it. Insert a TOC field in the template and tell the user to update fields (F9), or render via LibreOffice to refresh.

Template filling with docxtpl (pip install docxtpl):

from docxtpl import DocxTemplate
tpl = DocxTemplate("offer_template.docx")      # contains {{ name }}, {% for item in items %}...
tpl.render({"name": "Jane Doe", "items": [{"desc": "Laptop", "qty": 1}]})
tpl.save("offer_jane.docx")

Type placeholders in Word in one go; Word may split {{ name }} across runs if you edit it piecemeal, which breaks rendering. Retype the whole tag if a variable is not replaced.

JavaScript (docx package):

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

const doc = new Document({
  sections: [{
    children: [
      new Paragraph({ text: "Quarterly Report", heading: HeadingLevel.TITLE }),
      new Paragraph({ children: [new TextRun({ text: "Note: ", bold: true }), new TextRun("unaudited.")] }),
      new Table({ rows: [
        new TableRow({ tableHeader: true, children: [new TableCell({ children: [new Paragraph("Region")] }), new TableCell({ children: [new Paragraph("Revenue")] })] }),
        new TableRow({ children: [new TableCell({ children: [new Paragraph("EMEA")] }), new TableCell({ children: [new Paragraph("1.2M")] })] }),
      ] }),
    ],
  }],
});
writeFileSync("report.docx", await Packer.toBuffer(doc));

Edit an existing document

Replace text without destroying formatting. Word splits text into runs arbitrarily (spell-check, edits, formatting), so a phrase may span several runs:

def replace_in_paragraph(paragraph, old: str, new: str) -> bool:
    if old not in paragraph.text:
        return False
    runs = paragraph.runs
    full = "".join(r.text for r in runs)
    start = full.index(old)
    end = start + len(old)
    pos = 0
    for run in runs:
        r_start, r_end = pos, pos + len(run.text)
        pos = r_end
        if r_end <= start or r_start >= end:
            continue
        keep_before = run.text[: max(0, start - r_start)]
        keep_after = run.text[max(0, end - r_start):] if r_end > end else ""
        insert = new if r_start <= start < r_end else ""
        run.text = keep_before + insert + keep_after
    return True

The replacement inherits the formatting of the run where the match starts. Apply it to body paragraphs, table cells (for t in doc.tables: for row in t.rows: for cell in row.cells), and headers/footers (section.header.paragraphs, first_page_header, even_page_header). Text boxes, footnotes, and content controls are not exposed by python-docx; inspect the XML if the user expects changes there.

Add a review comment (python-docx 1.2+):

para = doc.paragraphs[3]
doc.add_comment(para.runs, text="Please confirm this figure.", author="Reviewer", initials="RV")

Extract content

from docx import Document
doc = Document("input.docx")
for block in doc.iter_inner_content():          # paragraphs and tables in document order
    if hasattr(block, "rows"):
        for row in block.rows:
            print(" | ".join(c.text for c in row.cells))
    else:
        print(block.text)

Merged cells appear repeated in each spanned position; de-duplicate by cell identity if exporting tables.

Gotchas

• .doc (legacy binary) is not supported; convert with LibreOffice first.
• Setting run.font.name changes only Latin text; East Asian text needs the w:eastAsia attribute on rFonts (raw XML).
• Deleting a paragraph: p._element.getparent().remove(p._element) — private API; keep it in one helper and test it.
• Saving overwrites without warning; write to a new filename unless the user asked to modify in place.
• Macro-enabled .docm files: python-docx can open them but you must keep the .docm extension and content type; never strip or add macros silently.

Verification

• Re-run scripts/docx_inspect.py on the output: outline matches the intended headings, styles are named styles (few direct-formatting runs), tracked changes and comments are as expected.
• Render to PDF (soffice --headless --convert-to pdf report.docx) and view a page image to check layout, tables, and images.
• For edits, diff extracted text before and after (python3 -c with iter_inner_content) and confirm only the intended changes appear.