TL;DR
Render documentation to DOCX format via render_docx.py. Specialized utility, activate only when DOCX export is explicitly requested.
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.
Workflow
- Prefer visual review (layout, tables, diagrams).
- If
soffice and pdftoppm are available, convert DOCX -> PDF -> PNGs.
- Or use
scripts/render_docx.py (requires pdf2image and Poppler).
- If these tools are missing, install them or ask the user to review rendered pages locally.
- Use
python-docx for edits and structured creation (headings, styles, tables, lists).
- After each meaningful change, re-render and inspect the pages.
- If visual review is not possible, extract text with
python-docx as a fallback and call out layout risk.
- Keep intermediate outputs organized and clean up after final approval.
Temp and output conventions
- Use
tmp/docs/ for intermediate files; delete when done.
- Write final artifacts under
output/doc/ when working in this repo.
- Keep filenames stable and descriptive.
Dependencies (install if missing)
Prefer uv for dependency management.
Python packages:
uv pip install python-docx pdf2image
If uv is unavailable:
python3 -m pip install python-docx pdf2image
System tools (for rendering):
# macOS (Homebrew)
brew install libreoffice poppler
# Ubuntu/Debian
sudo apt-get install -y libreoffice poppler-utils
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:
python 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.
1---2name: codex-doc-renderer3description: Use when the task involves reading, creating, or editing `.docx` documents, especially when formatting or layout fidelity matters; prefer `python-docx` plus the bundled `scripts/render_docx.py` for visual checks.4---5
6
7## TL;DR
8Render documentation to DOCX format via `render_docx.py`. Specialized utility, activate only when DOCX export is explicitly requested.
9
10# DOCX Skill
11
12## When to use
13- Read or review DOCX content where layout matters (tables, diagrams, pagination).
14- Create or edit DOCX files with professional formatting.
15- Validate visual layout before delivery.
16
17## Workflow
181. Prefer visual review (layout, tables, diagrams).
19 - If `soffice` and `pdftoppm` are available, convert DOCX -> PDF -> PNGs.
20 - Or use `scripts/render_docx.py` (requires `pdf2image` and Poppler).
21 - If these tools are missing, install them or ask the user to review rendered pages locally.
222. Use `python-docx` for edits and structured creation (headings, styles, tables, lists).
233. After each meaningful change, re-render and inspect the pages.
244. If visual review is not possible, extract text with `python-docx` as a fallback and call out layout risk.
255. Keep intermediate outputs organized and clean up after final approval.
26
27## Temp and output conventions
28- Use `tmp/docs/` for intermediate files; delete when done.
29- Write final artifacts under `output/doc/` when working in this repo.
30- Keep filenames stable and descriptive.
31
32## Dependencies (install if missing)
33Prefer `uv` for dependency management.
34
35Python packages:
36```
37uv pip install python-docx pdf2image
38```
39If `uv` is unavailable:
40```
41python3 -m pip install python-docx pdf2image
42```
43System tools (for rendering):
44```
45# macOS (Homebrew)
46brew install libreoffice poppler
47
48# Ubuntu/Debian
49sudo apt-get install -y libreoffice poppler-utils
50```
51
52If installation isn't possible in this environment, tell the user which dependency is missing and how to install it locally.
53
54## Environment
55No required environment variables.
56
57## Rendering commands
58DOCX -> PDF:
59```
60soffice -env:UserInstallation=file:///tmp/lo_profile_$$ --headless --convert-to pdf --outdir $OUTDIR $INPUT_DOCX
61```
62
63PDF -> PNGs:
64```
65pdftoppm -png $OUTDIR/$BASENAME.pdf $OUTDIR/$BASENAME
66```
67
68Bundled helper:
69```
70python scripts/render_docx.py /path/to/file.docx --output_dir /tmp/docx_pages
71```
72
73## Quality expectations
74- Deliver a client-ready document: consistent typography, spacing, margins, and clear hierarchy.
75- Avoid formatting defects: clipped/overlapping text, broken tables, unreadable characters, or default-template styling.
76- Charts, tables, and visuals must be legible in rendered pages with correct alignment.
77- Use ASCII hyphens only. Avoid U+2011 (non-breaking hyphen) and other Unicode dashes.
78- Citations and references must be human-readable; never leave tool tokens or placeholder strings.
79
80## Final checks
81- Re-render and inspect every page at 100% zoom before final delivery.
82- Fix any spacing, alignment, or pagination issues and repeat the render loop.
83- Confirm there are no leftovers (temp files, duplicate renders) unless the user asks to keep them.
majiayu000