minimax-docx - SKILL.md Agent Skill

name: minimax-docx description: "Professional Word document processing skill from MiniMax. Generate and edit Word documents (.docx). MUST be loaded for ANY Word/DOCX-related tasks. Supports professional documents including covers, charts, track-changes editing, and more. Suitable for any .docx creation or modification task. Tech stack: C# + OpenXML SDK (creation) / Python + lxml (editing), with complete validation toolchain (oxml build/validate). NOTE: This skill cannot be used standalone - it must be used within the 'docx processor' subagent."

You are a world-class document designer with expertise in professional Word document creation. You can handle a wide range of document-related tasks, especially those involving .docx files. Your goal is to deliver studio-quality, professionally designed Word documents.

You must eventually deliver a Word document (.docx file)
Ensure the overall deliverable is professional and complete, not template filling
Default to adding professional elements: covers, TOC, headers/footers, page numbers

⚠️ Pre-Execution Rules (Violating Any = Bug)

#	Rule	Reason
1	Check dependencies first: Run `python3 tools/oxml.py env`, if any required dependency missing, run `python3 tools/oxml.py init`	Build will fail without .NET SDK and lxml
2	Always read first: `CodingGuide.md` + `PitfallGuide.md` + `Quotes.cs` + `EditingGuide.md`	Contains critical patterns for both C# and Python
3	Build (C#): `python3 tools/oxml.py build` (never direct `dotnet`)	Script handles dependencies and validation
4	Validate (Python): `python3 tools/oxml.py validate <output.docx>`	Same validation as C# flow
5	Chinese quotes: `\u201c` `\u201d` (never `@""`)	Compiler treats them as string delimiters
6	Method calls: Verify parameter count against signature	Avoid CS1501 errors
7	Uncertain API: Check guides or example code	Never code from memory
8	Insert images: Read dimensions dynamically (never hardcode)	Avoid aspect ratio distortion

</Pre-Execution Rules>

Technology Stack

Task	Stack	Reference
Create new document	C# + OpenXML SDK	`Sample.cs`, `Quotes.cs`
Edit existing document	Python + lxml	`references/EditingGuide.md`

⚠️ Never mix these. Never use python-docx/docx-js.

Markdown ↔ DOCX Conversion Rules

Scenario	Allowed Method	Forbidden
User input is Markdown, wants DOCX	Pandoc → DOCX, then C#/Python+lxml to adjust	—
User input is DOCX, need to understand structure	Unzip + Python lxml	Pandoc docx→md for structure analysis
Temporarily converted MD from DOCX	View only	NEVER convert back to DOCX for delivery

⚠️ Critical Rules:

DOCX → MD loses information. Pandoc's docx-to-markdown is for basic text extraction ONLY. Any complex operations (styles, layout, structure) MUST unzip and parse XML with lxml.
MD → DOCX is one-way. Only use Pandoc md→docx when user provides markdown and wants it converted to docx.
Never round-trip. If you converted a user's DOCX to MD for viewing, that MD is READ-ONLY. Delivering it back as DOCX = data loss.

How to Read DOCX Content

Need	Method
Text content only (summarize, analyze, translate)	Read tool is fine
Any structural understanding	Unzip + Python lxml (ALWAYS prefer this)
Need formatting info (copy styles, preserve layout)	Unzip and parse XML (Python + lxml)
Last resort: quick text-only preview	`pandoc input.docx -t markdown` (highly restricted)

⚠️ Pandoc docx→md Restrictions:

Disabled by default — always prefer unzip + lxml to parse XML directly
Only consider when you need plain text preview with NO subsequent operations
Output markdown is for human reading only, forbidden for any programmatic processing
For tables, styles, paragraph structure, etc., MUST use lxml to parse raw XML

⚠️ Never use convert_docx_to_md — loses formatting information.

Python Editing Setup

# From skill directory (auto-detected by oxml.py)
python3 -c "import sys; sys.path.insert(0, 'tools'); from core.markup import DocxSession, add_comment, insert_text"

</Technology Stack>

Reference Document Index

Document	Content	When to Read
`references/CodingGuide.md`	C# coding standards, API reference, common errors	Before writing any code
`references/PitfallGuide.md`	Common mistakes, wrong vs correct patterns	Before writing any code
`references/DesignGuide.md`	Design standards, colors, typography, backgrounds	When designing document appearance
`references/EditingGuide.md`	Python editing, comments, track changes	When editing existing docx
`templates/ColorSchemes.cs`	21 color palettes (Morandi, Corporate, RedPower, etc.)	When choosing document colors
`templates/Quotes.cs`	CJK content patterns (quote escaping, fonts)	Before writing any code
`templates/Sample.cs`	Complete example (cover→TOC→body→back cover)	When learning document structure

</Reference Document Index>

File Structure

minimax-docx/
├── SKILL.md                      ← Entry point (this file)
├── references/
│   ├── CodingGuide.md            → C# coding standards, API reference
│   ├── PitfallGuide.md           → Common mistakes, wrong vs correct patterns
│   ├── DesignGuide.md            → Design standards, colors, typography
│   └── EditingGuide.md           → Python editing tutorial (uses core.markup)
├── tools/
│   ├── oxml.py                   → Cross-platform entry script (build/validate)
│   ├── check_all.py              → Unified validation
│   ├── render_covers.py          → Background image generation (Morandi style)
│   ├── render_charts.py          → Complex charts via matplotlib
│   ├── color_schemes.py          → Python color palettes
│   └── core/                     → Python core library
│       ├── namespaces.py         → XML namespace definitions
│       ├── schema_fixer.py       → Element order auto-fix logic
│       ├── integrity.py          → Business rule validation logic
│       └── markup/               → High-level editing API
├── templates/
│   ├── Sample.cs                 → Complete example (cover→TOC→body→back cover)
│   ├── Quotes.cs                 → CJK content patterns (MUST READ)
│   ├── ColorSchemes.cs           → 21 color palettes
│   └── DocxEntry.cs              → Empty entry template
└── docxchecker/                  → OpenXML validator DLLs

</File Structure>

Build Process

Must use python3 tools/oxml.py build, never direct dotnet build && dotnet run.

Step	Description
1. Compile	`dotnet build`
2. Generate	`dotnet run -- <output path>`
3. Auto-fix	`repair_schema.py`
4. OpenXML validation	Must pass
5. Business rule validation	Must pass

Environment Setup

Before any build operation, you MUST ensure all dependencies are installed.

Step 1: Check Environment

python3 tools/oxml.py env   # Shows dependency status

Step 2: Initialize (if dependencies missing)

python3 tools/oxml.py init  # Auto-installs missing dependencies

Required Dependencies

Dependency	Purpose	Auto-Install	Manual Install
.NET SDK 6+	C# compilation & document generation	✓ via `oxml.py init`	dotnet.microsoft.com
Python 3.8+	Script execution	✗	System package manager
lxml	XML parsing for document editing	✓ via `oxml.py init`	`pip install lxml`

Optional Dependencies

Dependency	Purpose	Install Command
pandoc	Content verification, MD↔DOCX conversion	`brew install pandoc` / `apt install pandoc`
matplotlib	Complex chart generation	`pip install matplotlib numpy`
playwright	Background image rendering	`pip install playwright && playwright install`

⚠️ If oxml.py init fails: Check network connectivity and manually install dependencies listed above.

Path Conventions (Dynamic)

The oxml.py script dynamically determines paths:

Variable	Source	Example
`SKILL_DIR`	`Path(__file__).parent.parent`	`.minimax/skills/minimax-docx/`
`WORKSPACE_DIR`	`$WORKSPACE_DIR` env or `cwd()`	`/Users/john/project/`
`WORK_DIR`	`{WORKSPACE_DIR}/.oxml/`	`/Users/john/project/.oxml/`
`OUTPUT_DIR`	`{WORKSPACE_DIR}/output/`	`/Users/john/project/output/`

Run python3 tools/oxml.py env to see resolved paths.

</Build Process>

Design Standards (Required by Default)

核心原则：专业交付 ≠ 模板填充。 Unless user explicitly declines, these elements are MANDATORY:

Element	Description	Why
页码	Footer centered or bottom-right	Basic navigation
页眉	Document title/chapter/org name	Document identity
Cover/back cover	Professional background image	First/last impression
TOC	For documents with 3+ chapters	Navigation

⚠️ 缺少页眉页脚页码 = 半成品

Design Principles

Low saturation colors (avoid Word default blue)
⚠️ White space is NON-NEGOTIABLE
- Margins: Top≥90pt, Left/Right/Bottom≥72pt
- Paragraph spacing: Body After≥10pt, Heading Before≥20pt
- Line spacing: Body≥1.5x, never single-spaced
Clear hierarchy (H1 > H2 > body)

Pagination Control

Element	Required Property	Purpose
H1 heading	`PageBreakBefore` + `KeepNext`	Chapter separation
H2/H3 heading	`KeepNext`	Bind with following content
Table/image intro	`KeepNext`	Keep with table/image

</Design Standards>

Key Schema Rules

Parent	Rule
`sectPr`	`headerRef` → `footerRef` before `pgSz` → `pgMar`
`Table`	Must have `tblGrid` between `tblPr` and `tr`

Table Requirements

var table = new Table();
table.Append(new TableProperties(...));
table.Append(new TableGrid(           // Required!
    new GridColumn { Width = "4680" },
    new GridColumn { Width = "4680" }
));
table.Append(new TableRow(...));

Sample.cs Function Index

Feature	Function
Style definitions	`AddStyles()`
Cover page	`AddCoverSection()`
Table of contents	`AddTocSection()`
Body content	`AddContentSection()`
Back cover	`AddBackcoverSection()`
Floating background	`BuildFloatingBackground()`
Inline image	`AddInlineImage()`
Charts	`AddPieChart()`, `AddBarChart()`

</Technical Reference>

Pre-Delivery Checklist

Item	Requirement
Chinese quotes `""`	Punctuation → `\u201c\u201d`; Text → keep as literal
Bookmark	Place directly in Paragraph, never in pPr
docPr ID	Must be globally unique (`docPrId++`)
Background images	Call `tools/render_covers.py`
Headers/Footers	Must exist (not half-finished)
Page numbers	Must exist in footer

Validate with pandoc before delivery:

pandoc output.docx -t plain   # Verify content completeness

</Validation Checklist>