docx

name	docx
description	Create and edit Word documents (.docx) — C# + OpenXML SDK for creation, WIR engine for editing/comments/tracked changes. Use for any .docx task including document creation, editing, comments, revisions, footnotes, TOC, and Markdown-to-Word conversion.

Part 1: Routing

read file / cat only extracts plain text from .docx — all formatting is lost. If the task involves appearance or structure, use WIR engine's session.read() instead.

Route = What You Have

1. WIR (references/wir-reference.md) — A .docx exists whose format/style matters to the output.

The user provides a template, a document to edit/modify/review/annotate, or any file whose formatting should be preserved or referenced. This file is your output foundation — read it, modify it, fill it.

For existing .docx edits or redesigns, WIR is the required first path; use Create only when the file is merely a data source or after a named WIR failure.

If the .docx is merely a content/data source (e.g., reference papers, raw data exports) and its formatting is irrelevant, just read file to extract text — that is NOT a WIR case.

.doc format → convert first: libreoffice --headless --convert-to docx

2. md2docx (references/md2docx-reference.md) — When you are the Orchestrator (you have create_subagent and dispatch task) and your sub-agents have returned .md files. Convert their output to a formatted Word document using the md2docx pipeline.

If you do NOT have create_subagent / task tools, you are not an Orchestrator and md2docx does not apply. Do not write markdown yourself and convert with pandoc — the result is mediocre. Use Create (C#) for high-quality output.

3. Create (references/openxml-sdk-reference.md) — Neither of the above.

No target .docx, no upstream .md. Build the document from scratch using C# + OpenXML SDK via ./scripts/docx build.

---

Part 2: Execution

File Structure

docx/
├── SKILL.md                       ← This file (routing + rules)
├── references/
│   ├── openxml-sdk-reference.md   → Creation: patterns, traps, all you need
│   ├── wir-reference.md           → WIR editing interface + patterns
│   ├── md2docx-reference.md       → Citation pipeline → Word conversion
│   ├── chart-reference.md         → Native Word charts (pie, bar, line)
│   ├── omml-reference.md          → OMML math equation patterns
│   └── matplotlib-guide.md        → Charts Word can't do natively
├── scripts/
│   ├── docx                       → Unified entry point (the only script to call)
│   ├── engine/                    → WIR engine (editing core)
│   ├── md2docx/                   → Citation → Word pipeline
│   ├── generate_backgrounds.py    → Style reference: Morandi curves (read for technique, don't call directly)
│   ├── generate_inkwash_backgrounds.py  → Style reference: ink wash
│   ├── generate_swiss_backgrounds.py    → Style reference: Swiss grid
│   ├── generate_geometric_backgrounds.py → Style reference: geometric blocks
│   ├── generate_gradient_backgrounds.py  → Style reference: gradient ribbons
│   └── generate_formal_backgrounds.py    → Style reference: formal double border
└── assets/templates/
    ├── Example.cs                 → English document demo (conditional required)
    └── CJKExample.cs              → Chinese/CJK document demo (conditional required)

Validation

• Creation: ./scripts/docx build runs the full pipeline (compile → generate → auto-fix element order → OpenXML validate → business rules)
• Editing: The engine validates internally; after saving, spot-check high-risk areas; for layout-sensitive edits, convert to PDF/images when available to visually confirm the result

Hard Rules

1. WIR first for editing — no ad-hoc XML surgery; no python-docx unless a specific WIR operation has failed and you can name the failure. Consult references/wir-reference.md before falling back.
2. Process large documents in windows — no oversized replacement blocks.
3. On warnings or errors, stop, re-read, then continue.

Quality Standards

Low-saturation color palette. Pick ONE hue direction, build 3 tiers: Primary (headings) / Dark (body text) / Light (captions). Never pure #FF0000/#0000FF. Cover text color must contrast with its background AND be visually distinct from body text (larger size, different weight, generous spacing).

Cover/backcover backgrounds. If the document needs a cover, generate a unique background from scratch — read one of the generate_*.py scripts to learn the Playwright + SVG technique, then write your own HTML/SVG with original shapes and colors matching the document's palette. Never reuse or directly call existing background scripts. Cover text must feel like a separate visual space from the body, not just a bigger first paragraph.

Content constraints. Word count target "X字左右" means ±20% is acceptable. Document filename by topic (e.g., Energy_Report.docx). Language consistency across all elements.

Delivery checklist (verify before delivering):

1. Document opens without errors
2. OpenXML + business rule validation passes
3. Headers, footers, page numbers present and correctly positioned
4. No placeholder text remains ([Company Name], TODO, etc.)
5. All images render (build output shows X images — if 0, images were not inserted)
6. Cover/backcover text visibly contrasts with background
7. For formatting-sensitive edits, re-read representative edited regions and verify direct paragraph/run formatting, including mixed-script font channels, matches the intended style; style changes may not override inline formatting.
8. When applying broad formatting passes, first define protected regions/elements whose formatting must remain distinct, then exclude or re-audit them after the pass.