Word Documents (profy-docx)

Create, edit, and analyse Word documents. Understanding this capability starts with accepting one fact: a .docx file is a ZIP archive containing XML. Every constraint below that looks arbitrary follows from that structure.

Activation

profy-docx is user_selectable: false — automatically available, nothing to tick.

{ "id": "profy-docx", "activation": { "user_selectable": false } }

contracts declares only skills: ["skills/"] and no tools. The expert runs scripts via bash in the sandbox; the skill document governs how. Triggers include: Word documents, .docx, requests for polished deliverables with tables of contents, headings, page numbers, or letterheads, plus extracting or reorganising content from existing docx files, inserting or replacing images, find-and-replace, and working with tracked changes or comments. PDFs, spreadsheets, and Google Docs do not take this path.

Three main routes

Task	Approach
Read / analyse content	`pandoc`, or unpack for raw XML
Create a new document	`docx-js` (JavaScript)
Edit an existing document	Unpack → edit XML → repack

Reading

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

# Raw XML access
python scripts/office/unpack.py document.docx unpacked/

Converting legacy .doc

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

.doc is an entirely different binary format and must be converted before it can be edited.

Converting to images for visual inspection

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

Accepting tracked changes

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

Requires LibreOffice. Produces a clean document with every tracked change accepted.

Text replacement: use the script, do not write your own

# Replace the first occurrence
python scripts/office/docx_replace.py --file document.docx --search "old text" --replace "new text"

# Replace all occurrences
python scripts/office/docx_replace.py --file document.docx --search "old" --replace "new" --all

# Write to a different file
python scripts/office/docx_replace.py --file document.docx --search "old" --replace "new" --output result.docx

# Restrict to one paragraph (0-based)
python scripts/office/docx_replace.py --file document.docx --search "old" --replace "new" --paragraph 3

Exit codes:

Code	Meaning
`0`	Success, and verified
`1`	Text not found — check stderr for hints
`2`	Verification failed

Do not hand-write python-docx scripts for simple find-and-replace. Word splits a single sentence across multiple run elements — because one word is bold, or because the spell checker inserted a marker — so the string you are searching for is not contiguous in the XML at all. Hand-written scripts therefore fail silently: no error, just no replacement. docx_replace.py handles run-boundary splitting and verifies the result afterwards, which is exactly what exit code 2 reports.

This is a good general lesson about document formats: the visual model (a sentence) and the storage model (a run sequence) do not correspond, and any tool that assumes they do will be wrong intermittently rather than consistently — the worst possible failure mode.

Creating documents: docx-js constraints

npm install -g docx

None of these are style preferences. Each corresponds to a concrete failure where the output either will not open or renders incorrectly somewhere.

Structure

Constraint	Detail
Set page size explicitly	docx-js defaults to A4; US documents need US Letter (12240 × 15840 DXA)
Landscape takes portrait dimensions	docx-js swaps width and height internally: pass the short edge as `width`, the long edge as `height`, then set `orientation: PageOrientation.LANDSCAPE`
Never use `\n`	Use separate `Paragraph` elements for line breaks
`PageBreak` must live inside a `Paragraph`	Standalone produces invalid XML
`ImageRun` requires `type`	png / jpg / etc., never omitted

Lists and tables

Constraint	Detail
Never use unicode bullets	Use `LevelFormat.BULLET` with a numbering config
Table widths must use DXA	`WidthType.PERCENTAGE` breaks in Google Docs
Tables need dual widths	Both the `columnWidths` array and per-cell `width`, and they must agree
Table width equals the sum of column widths	Under DXA they must add up exactly
Always add cell margins	`margins: { top: 80, bottom: 80, left: 120, right: 120 }`
Use `ShadingType.CLEAR`	Never SOLID for table shading
Never use tables as dividers or rules	Cells have a minimum height and render as empty boxes, including in headers and footers. For a horizontal rule use `border.bottom` on a `Paragraph`; for two-column footers use tab stops, not tables

Tables of contents

Constraint	Detail
TOC recognises `HeadingLevel` only	No custom styles on heading paragraphs
Override built-in styles by exact ID	`"Heading1"`, `"Heading2"`
Include `outlineLevel`	Required for TOC — 0 for H1, 1 for H2, and so on

Supported typesetting features

Page size, style overrides, multi-level lists, tables, images, page breaks, hyperlinks, footnotes, tab stops, multi-column layouts, tables of contents, headers and footers.

Boundaries and failure modes

.doc must be converted first. Editing it directly fails.
Hand-written replacement scripts fail silently (see the run-boundary warning above).
Accepting tracked changes depends on LibreOffice; without it accept_changes.py cannot run.
Unpacking and editing XML is a sharp tool. Malformed XML makes Word refuse to open the file rather than degrade gracefully, so edits must be validated afterwards.
Tables render inconsistently across renderers. Most of the constraints above (DXA, dual widths, CLEAR shading) exist to keep output correct outside Word — in Google Docs, WPS, and preview tools.

Troubleshooting

Symptom	Cause	Fix
Replace script exits 1	Text not found — likely split across runs, or contains hidden characters	Read the stderr hints and try a shorter search string
Replace script exits 2	The replacement was written but verification failed	Document structure is unusual; switch to the unpack route
Word refuses to open the generated file	Invalid XML, commonly a standalone `PageBreak`	Wrap the page break in a `Paragraph`
Tables collapse in Google Docs	Percentage widths were used	Switch to DXA and make total width equal the column sum
Table of contents is empty	Heading paragraphs carry custom styles, or `outlineLevel` is missing	Use `HeadingLevel` only and add `outlineLevel`
Odd empty boxes in the header	A table was used to draw a divider	Replace with a `Paragraph` bottom border

Verify your output

Convert to images and look: soffice.py --convert-to pdf then pdftoppm. This catches the overwhelming majority of layout accidents and is far faster than reading XML.
If there is a table of contents, confirm the entry count matches the actual heading count.
If there are tables, open the file in Google Docs too — it is the least forgiving about width definitions, so passing there generally means passing everywhere.

Office documents overview

How the four document capabilities differ and when to use each

PDF documents

The alternative route when the deliverable needs real typesetting

Verified 2026-08-11. Sources: services/agent-runtime/src/plugins/builtin/docx/plugin.json, skills/SKILL.md, skills/scripts/office/docx_replace.py, skills/scripts/accept_changes.py, skills/scripts/office/{unpack,pack,soffice}.py.

Get Started

Core Concepts

Guides

Platform & Account

Deep Dive

Word Documents

Word Documents (profy-docx)

Activation

Three main routes

Reading

Converting legacy .doc

Converting to images for visual inspection

Accepting tracked changes

Text replacement: use the script, do not write your own

Creating documents: docx-js constraints

Structure

Lists and tables

Tables of contents

Supported typesetting features

Boundaries and failure modes

Troubleshooting

Verify your output

Office documents overview

PDF documents

​Word Documents (profy-docx)

​Activation

​Three main routes

​Reading

​Converting legacy .doc

​Converting to images for visual inspection

​Accepting tracked changes

​Text replacement: use the script, do not write your own

​Creating documents: docx-js constraints

​Structure

​Lists and tables

​Tables of contents

​Supported typesetting features

​Boundaries and failure modes

​Troubleshooting

​Verify your output

​Related

Office documents overview

PDF documents

Word Documents (profy-docx)

Activation

Three main routes

Reading

Converting legacy .doc

Converting to images for visual inspection

Accepting tracked changes

Text replacement: use the script, do not write your own

Creating documents: docx-js constraints

Structure

Lists and tables

Tables of contents

Supported typesetting features

Boundaries and failure modes

Troubleshooting

Verify your output

Related