# DOCX

> 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.

- Skill: `haomingz/docx` (Agent Skill, multi-file: 38 files)
- Install (CLI): `npx skillmds@latest add haomingz/docx`
- Raw SKILL.md: https://api.skillmd.com/api/skills/haomingz/docx/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: haomingz (https://skillmd.com/u/haomingz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/haomingz/docx

---


# 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.

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

## Hard Rules

1. **No manual markdown-to-docx.** Do not write markdown then convert with pandoc. If you are the Orchestrator with upstream .md from sub-agents, use md2docx. Otherwise, always Create (C#).
2. **Target .docx exists (template, document to edit, format reference) → always WIR**, never rewrite from scratch.
3. Clean up iteration artifacts — no `v1`/`v2`/`final` clutter in the output directory. Deliver clean, clearly named files only.
4. Name output files by topic and match the user's language (e.g., Chinese query → `储能电站分析报告.docx`, English query → `Energy_Storage_Report.docx`). Never `output.docx`.
5. Language consistency — user's conversation language across all elements (body, headings, headers/footers, TOC, chart labels, filenames).
6. Default to the skill's own toolchain; avoid external libraries unless necessary.
7. After choosing a route, read the corresponding reference file **in full** before writing any code. Do not skim or skip sections — traps and required patterns appear throughout.

## 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.

**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