docx

Replace <skill_dir> with the actual skill path shown by the loader.

Unified DOCX skill. SKILL.md is the dispatch layer. Pick the route that matches the user’s intent, read that route guide, then go straight into execution. Do not front-load every task with the full evidence/backend/acceptance waterfall.

Environment gates

The env gate ships in two equivalent dialects so the skill works on macOS, Linux/WSL, and Windows without any cygwin/git-bash hack:

Both dialects accept the same three levels (read | render | full, default full) and produce the same [OK] / [FAIL] / Status: READY|NOT READY lines, so a route may be gated on either one.

The skill loader runs only the read gate at load time, so missing dotnet/soffice does not block read-only routes.

Read gate

Checked at skill load time (automatic). Applies to: READ_CONTENT, READ_STRUCTURE, COMPARE_TWO_DOCX.

# macOS / Linux / WSL
bash <skill_dir>/scripts/env_check.sh --level read

# Windows
powershell -ExecutionPolicy Bypass -File <skill_dir>\scripts\env_check.ps1 -Level Read

Requires: python3 (or python launcher on Windows), unzip (or tar.exe on Windows 10+), UTF-8 console.

If the read gate fails, the skill cannot load at all.

Render gate

Run before READ_RENDERED routes. Includes all read-level checks plus:

bash <skill_dir>/scripts/env_check.sh --level render                                # *nix
powershell -ExecutionPolicy Bypass -File <skill_dir>\scripts\env_check.ps1 -Level Render   # Windows

Requires (in addition to read): soffice / soffice.exe, pdftoppm (or pdftocairo).

If the render gate fails, stop and report. Do not silently fall back to structure-only reads.

Full gate

Run before CREATE_DOCX, APPLY_TEMPLATE, EDIT_FILL_DOCX, REPAIR_LAYOUT routes.

bash <skill_dir>/scripts/env_check.sh --level full                                  # *nix
powershell -ExecutionPolicy Bypass -File <skill_dir>\scripts\env_check.ps1 -Level Full     # Windows

Requires (in addition to render): dotnet >= 9, pandoc, zip (or Compress-Archive on Windows), dotnet project built.

If the full gate fails, stop and report. Do not attempt generation with missing dependencies.

Capability matrix in ZCodium

The levels above assume a machine where the skill may install its own toolchain. In ZCodium the repo skills must not silently change the host, so scripts/setup.sh is report-only unless you opt in. Check the level you actually need before promising a deliverable:

.NET is a global SDK and the upstream installer fetched it with curl | sh, so this fork makes it opt-in: run bash scripts/setup.sh --install-dotnet (writes ~/.dotnet, no sudo) only after the user agrees. The setup script never edits ~/.zprofile / ~/.zshrc and never installs global npm packages; it prints the lines the user may want to add themselves.

On an air-gapped or intranet host the curl | sh and package-manager paths cannot work at all. Plan for read / render and use the full gate only where a pre-provisioned SDK exists.

Cross-platform path & temp-dir convention

Examples in docs/ and references/ are written for *nix shells. When you execute on Windows, do these substitutions consistently:

Never invoke a .sh script through git-bash on Windows — setup.sh will refuse to install anything on MINGW*/MSYS*/CYGWIN* and tell you to switch to powershell.exe / pwsh.exe.

Operational rules — read before doing anything

1. Dispatch by user intent, not by backend.

Start with the shortest route choice:

• creating a new formal Word deliverable -> CREATE_DOCX
• preserving content but changing template / institutional style -> APPLY_TEMPLATE
• editing an existing DOCX in place -> EDIT_FILL_DOCX
• reading text / structure / rendered pages -> matching read route
• fixing visible defects -> REPAIR_LAYOUT
• comparing two DOCX files -> COMPARE_TWO_DOCX

Read docs/router.md only to settle the route. Do not read docs/evidence.md, docs/backends.md, and docs/acceptance.md before route selection.

2. For generation routes, choose style family / recipe before backend.

The old benchmarked generation core stays in this skill. For CREATE_DOCX and APPLY_TEMPLATE, the first substantive decision is the visual system, not the backend. Reuse these files as the generation core:

• references/typography_guide.md
• references/design_principles.md
• references/cjk_typography.md
• scripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples*.cs

These are not optional decoration. They are the quality-preserving recipe layer.

3. Backend comes after route + recipe.

• D is the default write backend for formal DOCX creation, template application, and most edits.
• S is only for OpenXML graph work beyond the builtin CLI surface.
• X is only for deterministic local XML patch / inspection work.
• Formal CREATE_DOCX is never routed to pandoc as a generation backend.
• If a chosen backend gate fails, stop and report it. Do not silently switch.

4. Rendered acceptance is a post-write gate, not a pre-dispatch hop.

For template, layout, TOC, multi-section, header/footer, and page-number work, finish the write first, then run rendered acceptance from docs/acceptance.md / docs/rendered-delivery.md.

5. Keep DOCX execution inside this skill.

Do not bounce rendered diagnosis to another skill. Do not treat raw XML string replace as a valid editing strategy. Do not use readlink, $0, or shell path tricks in skill docs; use <skill_dir> only.

6. DOCX→PDF is native to this skill. If the user asks to convert an existing Word/DOCX document to PDF while preserving layout, do it here via python3 <skill_dir>/scripts/docx_to_pdf.py (or soffice --headless --convert-to pdf as fallback), then verify the PDF. Do not route DOCX→Markdown/HTML→PDF for a preservation task: DOCX already carries page geometry, sections, headers/footers, fields, numbering, and table layout. HTML/PDF belongs to redesign/recomposition after native render fails or when explicitly requested.

Routes — pick one, then read that guide

WRITE / GENERATE a DOCX

READ / DIAGNOSE / REPAIR a DOCX

Deep docs — only after the route is clear

Generation core references

Use these after CREATE_DOCX / APPLY_TEMPLATE is selected:

Runtime shorthands

# macOS / Linux / WSL
CLI="dotnet run --project <skill_dir>/scripts/dotnet/MiniMaxAIDocx.Cli --"
TMPDIR_DOCX="${TMPDIR:-/tmp}"

# Windows PowerShell
$CLI = "dotnet run --project <skill_dir>\scripts\dotnet\MiniMaxAIDocx.Cli --"
$TmpDocx = $env:TEMP

Common commands (substitute $TMPDIR_DOCX / $TmpDocx for the literal /tmp examples elsewhere in docs/):

$CLI analyze --input in.docx --json
$CLI diff --before before.docx --after after.docx
$CLI merge-runs --input out.docx
$CLI validate --input out.docx --xsd <skill_dir>/assets/xsd/wml-subset.xsd
$CLI validate --input out.docx --business
$CLI validate --input out.docx --gate-check <skill_dir>/assets/xsd/business-rules.xsd
python3 <skill_dir>/scripts/docx_to_pdf.py --input in.docx --output "$TMPDIR_DOCX/docx-render.pdf"
python3 <skill_dir>/scripts/render_docx_pages.py in.docx --output-dir "$TMPDIR_DOCX/docx-pages"

On Windows substitute python3 -> python, / -> \, and $TMPDIR_DOCX -> $env:TEMP. The underlying .py scripts use tempfile.TemporaryDirectory and Path(...).expanduser().resolve() so they do not care which slash style you pass in.

Structural non-negotiables

• w:p = pPr -> runs
• w:r = rPr -> text-like children
• w:tbl = tblPr -> tblGrid -> rows
• w:body ends with sectPr
• heading styles need OutlineLevel
• direct formatting contamination must be stripped unless explicitly preserved
• template and multi-section work must preserve section graph, titlePg, and per-section headers/footers

Out of scope

• PDF / PPT deliverables -> use pdf / pptx
• casual plain-text drafting with no DOCX output
• pretending a Word-authored DOCX can be safely round-tripped through pandoc for formal output