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:
| Platform | Setup | Env check |
|---|---|---|
| macOS / Linux / WSL | bash <skill_dir>/scripts/setup.sh |
bash <skill_dir>/scripts/env_check.sh --level <lvl> |
| Windows (PowerShell 5.1+) | powershell -ExecutionPolicy Bypass -File <skill_dir>\scripts\setup.ps1 |
powershell -ExecutionPolicy Bypass -File <skill_dir>\scripts\env_check.ps1 -Level <lvl> |
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.
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:
| In the example | Windows substitute |
|---|---|
<skill_dir>/scripts/foo.sh |
<skill_dir>\scripts\foo.ps1 (every .sh has a .ps1 peer) |
python3 <skill_dir>/scripts/foo.py |
python <skill_dir>\scripts\foo.py (the .py files are cross-platform) |
/tmp/docx-<thing> |
$env:TEMP\docx-<thing> |
bash <skill_dir>/scripts/setup.sh |
powershell -ExecutionPolicy Bypass -File <skill_dir>\scripts\setup.ps1 |
forward slashes in paths |
backslashes; quote any path containing spaces |
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_DOCXRead
docs/router.mdonly to settle the route. Do not readdocs/evidence.md,docs/backends.md, anddocs/acceptance.mdbefore route selection.
2. For generation routes, choose style family / recipe before backend.
The old benchmarked generation core stays in this skill. For
CREATE_DOCXandAPPLY_TEMPLATE, the first substantive decision is the visual system, not the backend. Reuse these files as the generation core:
references/typography_guide.mdreferences/design_principles.mdreferences/cjk_typography.mdscripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples*.csThese are not optional decoration. They are the quality-preserving recipe layer.
3. Backend comes after route + recipe.
Dis the default write backend for formal DOCX creation, template application, and most edits.Sis only for OpenXML graph work beyond the builtin CLI surface.Xis only for deterministic local XML patch / inspection work.- Formal
CREATE_DOCXis 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(orsoffice --headless --convert-to pdfas 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
| Intent | Guide | What happens next |
|---|---|---|
| CREATE_DOCX — author a new report / proposal / contract / memo / thesis / 公文 | docs/task-create.md |
normalize source -> choose recipe family -> choose D/S -> write -> acceptance |
| APPLY_TEMPLATE — preserve content but move into a template / institutional visual system | docs/task-apply-template.md |
choose template mode -> align recipe family -> read only the needed structure -> choose D/S -> write -> strict rendered acceptance |
| EDIT_FILL_DOCX — mutate content in an existing DOCX while keeping it the same document | docs/task-edit-fill.md |
choose edit mode -> choose X/D/S -> mutate -> acceptance |
READ / DIAGNOSE / REPAIR a DOCX
| Intent | Guide | Primary truth |
|---|---|---|
| READ_CONTENT — summarize / quote / retrieve text | docs/task-read-content.md |
content |
| READ_STRUCTURE — inspect styles / sections / numbering / TOC / comments / revisions | docs/task-read-structure.md |
structure |
| READ_RENDERED — inspect what the pages actually look like | docs/task-read-rendered.md |
rendered + structure |
| REPAIR_LAYOUT — fix page-level defects | docs/task-repair-layout.md |
rendered -> structure -> rendered |
| COMPARE_TWO_DOCX — explain before/after or source/template differences | docs/task-compare-two-docx.md |
content + structure + rendered |
Deep docs — only after the route is clear
| File | Use when |
|---|---|
docs/router.md |
settle route choice |
docs/evidence.md |
the selected route needs truth-source clarification |
docs/backends.md |
the selected route needs backend arbitration |
docs/acceptance.md |
you are ready to validate deliverables |
docs/rendered-delivery.md |
rendered issue report shape is required |
Generation core references
Use these after CREATE_DOCX / APPLY_TEMPLATE is selected:
| File | Role |
|---|---|
references/scenario_a_create.md |
create-from-scratch mechanics |
references/scenario_c_apply_template.md |
template transfer and multi-section rules |
references/typography_guide.md |
font pairings, sizes, spacing, page layout, table rules |
references/design_principles.md |
visual judgment rules when exact specs are missing |
references/cjk_typography.md |
CJK fonts, 字号, mixed-script rules, 公文 defaults |
scripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples*.cs |
benchmarked recipe families; choose one instead of inventing values |
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-> runsw:r=rPr-> text-like childrenw:tbl=tblPr->tblGrid-> rowsw:bodyends withsectPr- 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