Word Document Builder

DOCX Skill

When to use

• Read or review DOCX content where layout matters (tables, diagrams, pagination).
• Create or edit DOCX files with professional formatting.
• Validate visual layout before delivery.

How the file actually reaches the user

You BUILD the document in the sandbox and DELIVER it with export_file. A file written to the working directory and never exported does not reach the user at all — they see your description and no download. Never end a build turn without export_file.

Any document the user uploaded in this conversation is already staged in the sandbox working directory under its (sanitized) filename: characters outside A-Za-z0-9._- become _. List the directory if unsure:

import os; print(sorted(os.listdir(".")))

The sandbox has NO internet and no sudo: never try pip install, uv pip install, brew install or apt-get install. python-docx, pandoc, LibreOffice (soffice), poppler-utils (pdftoppm) and pymupdf (fitz) are pre-baked. An install attempt is a guaranteed failure that also burns one of the turn's limited tool calls, which can push export_file past the budget and cost the user the file.

For a substantial written document (report, memo, whitepaper) prefer the house engine zeplik-docx, which takes Markdown and owns the layout — cover page, contents, running header, "Page X of Y" footer, banded tables. Reach for raw python-docx when you must edit an EXISTING .docx or hit a specific structural requirement the engine does not cover.

Workflow

1. Use python-docx for edits and structured creation (headings, styles, tables, lists).
2. After each meaningful change, render and inspect the pages: soffice --headless --convert-to pdf --outdir out doc.docx then pdftoppm -png out/doc.pdf out/page. Look at the PNGs — check pagination, table widths, and that nothing is clipped or orphaned. (scripts/render_docx.py is bundled but depends on pdf2image, which is NOT installed in this sandbox — use the soffice/pdftoppm pair above instead.)
3. Re-open the saved file and assert it is intact (paragraph count, a heading, a spot value) — print the evidence.
4. export_file the document, then tell the user in one short line that it is ready. Do not restate the document contents as text.

Temp and output conventions

• Write the deliverable into the working directory with a stable, descriptive filename; that is the path you pass to export_file.
• Keep intermediate files out of the way (a tmp/ subfolder) and never export them.
• Never ask the user to review rendered pages locally — they have no copy until you export it.

If installation isn't possible in this environment, tell the user which dependency is missing and how to install it locally.

Environment

No required environment variables.

Rendering commands

DOCX -> PDF:

soffice -env:UserInstallation=file:///tmp/lo_profile_$$ --headless --convert-to pdf --outdir $OUTDIR $INPUT_DOCX

PDF -> PNGs:

pdftoppm -png $OUTDIR/$BASENAME.pdf $OUTDIR/$BASENAME

Bundled helper:

python3 scripts/render_docx.py /path/to/file.docx --output_dir /tmp/docx_pages

Quality expectations

• Deliver a client-ready document: consistent typography, spacing, margins, and clear hierarchy.
• Avoid formatting defects: clipped/overlapping text, broken tables, unreadable characters, or default-template styling.
• Charts, tables, and visuals must be legible in rendered pages with correct alignment.
• Use ASCII hyphens only. Avoid U+2011 (non-breaking hyphen) and other Unicode dashes.
• Citations and references must be human-readable; never leave tool tokens or placeholder strings.

Final checks

• Re-render and inspect every page at 100% zoom before final delivery.
• Fix any spacing, alignment, or pagination issues and repeat the render loop.
• Confirm there are no leftovers (temp files, duplicate renders) unless the user asks to keep them.

Zeplik output presentation

Present the final deliverable as a single polished artifact: clear headings, tables where the content is tabular, fenced code where it is code. Lead with the deliverable itself; keep process commentary to a single short line. If the skill produced multiple files or sections, end with a compact list of them with one-line purposes.