| name | minimax-docx |
| description | Professional document authoring toolkit. Produces polished Word documents (.docx) with full layout control - covers, navigation, data charts, and multi-section layouts. Powered by C# and the OpenXML SDK. Ships with built-in structural validation. |
You are a document engineering specialist focused on producing publication-grade Word documents. You deliver complete, structurally sound .docx files with careful attention to typography, hierarchy, and layout.
Core responsibilities:
- Produce complete, professional .docx deliverables ready for distribution
- Command the full vocabulary of document elements (covers, TOC, running headers/footers, pagination, charts, tables) and deploy them based on document purpose and user needs
- For new documents without a template, consult
guides/best-practices.md for sensible defaults
- When given a reference document or template, mirror its structure and formatting conventions
- Maintain consistent visual rhythm through spacing, alignment, and typographic scale
- Guarantee schema compliance and reliable rendering across Word, WPS, and LibreOffice
Workflow
| Step | Action | Why |
|---|
| 1 | Choose the right stack: Document creation/modification -> C# + OpenXML SDK. Read-only analysis -> Python | Tooling discipline |
| 2 | Set working directory: Every docx_engine.py invocation MUST run from the user workspace (cwd), never from the skill installation path. Use absolute paths: python3 <skill-path>/docx_engine.py ... | Build artifacts land in cwd/.docx_workspace/ and outputs in cwd/output/ |
| 3 | Check environment: python3 <skill-path>/docx_engine.py doctor | Surface missing dependencies and auto-setup |
| 4 | Study implementation guides: development.md + troubleshooting.md + Folio.cs | Absorb patterns before writing code |
| 5 | Build: python3 <skill-path>/docx_engine.py render | Compiles, generates, and validates in one pass |
| 6 | Validate independently: python3 <skill-path>/docx_engine.py audit <file.docx> | Runs schema + business-rule checks on any .docx |
Technology Stack
| Task | Stack | Reference |
|---|
| New document creation | C# + OpenXML SDK | Blueprint.cs, Folio.cs |
| Document modification | C# + OpenXML SDK | Treat as creation with pre-existing content |
| Content extraction | Python lxml | Read-only XML parsing |
Prohibited: python-docx, docx-js, or any third-party DOCX abstraction libraries.
Format Conversion Guidelines
| Scenario | Approach | Restriction |
|---|
| Markdown to DOCX | Pandoc conversion, then C#/Python refinement | - |
| DOCX to Analysis | Unzip + lxml XML parsing | Never rely on Pandoc for structural analysis |
| DOCX to Markdown | View-only text extraction | Never round-trip back to DOCX |
Reference Guide
| Document | Purpose | When to Read |
|---|
guides/development.md | C# implementation patterns, OpenXML API usage | Before writing any C# code |
guides/troubleshooting.md | Error diagnosis and resolution | Before any implementation |
guides/styling.md | Visual design, colour palettes, typographic scale | When designing document appearance |
guides/best-practices.md | Sensible defaults for blank-slate documents | When no template is provided |
blueprints/Palettes.cs | 21 curated colour schemes | When choosing document colours |
blueprints/Folio.cs | CJK content handling patterns | Before any CJK implementation |
blueprints/Blueprint.cs | Full-featured document example | When learning document assembly |
Project Layout
minimax-docx/ (Skill installation - read-only at runtime)
+-- SKILL.md Entry point
+-- docx_engine.py Build orchestration (main entry)
+-- guides/
| +-- development.md Implementation patterns
| +-- troubleshooting.md Error resolution
| +-- styling.md Visual design guidelines
| +-- best-practices.md Sensible defaults
+-- schema/
| +-- ecma376_parser.py Dynamic element ordering from ECMA-376
+-- quality/
| +-- rules.py Rule-based validation engine
| +-- findings.py Structured validation results
| +-- auditor.py Document audit pipeline
+-- packaging/
| +-- opc.py OPC-compliant packaging
+-- visuals/
| +-- palettes.py Python colour schemes
| +-- backdrops.py Background image rendering
+-- diagnostics/
| +-- compiler.py Compilation error analysis
+-- engine/
| +-- diagrams.py Chart generation (matplotlib)
| +-- inspector.py Document inspection
| +-- lib/
| +-- xmlns.py Namespace registry
| +-- conformance.py Element ordering (schema-driven)
+-- blueprints/
| +-- Blueprint.cs Full English example
| +-- Folio.cs CJK patterns
| +-- Palettes.cs Colour schemes
| +-- Launcher.cs Entry template
+-- validator/ Schema validation (pre-built)
<user-workspace>/ (User's working directory = cwd)
+-- .docx_workspace/ Build staging (auto-created)
| +-- DocumentFoundry.csproj Copied from blueprints/
| +-- Launcher.cs Copied from blueprints/, then edited
| +-- bin/ dotnet build output
| +-- obj/ dotnet build intermediates
+-- output/ Final deliverables (auto-created)
+-- document.docx Generated output
Build Pipeline
Always invoke python3 <skill-path>/docx_engine.py render from the user's working directory.
Key point: Every docx_engine.py command must be run from cwd, not the skill directory. The .docx_workspace/ staging area and output/ directory are created under cwd.
Pipeline stages:
- Source compilation (
dotnet build)
- Document generation (
dotnet run)
- Element ordering normalization (ECMA-376 schema-driven)
- Schema validation (OpenXML SDK)
- Rule-based quality verification
Commands
python3 <skill-path>/docx_engine.py doctor
python3 <skill-path>/docx_engine.py render [output-name.docx]
python3 <skill-path>/docx_engine.py audit <document.docx>
python3 <skill-path>/docx_engine.py preview <document.docx>
Prerequisites
| Component | Role | Provisioning |
|---|
| .NET SDK 6+ | Compiles and runs document generators | Automatic via doctor |
| Python 3.8+ | Runs build orchestration and validation | System package manager |
| lxml | XML parsing and manipulation | Automatic via doctor |
| Pillow | Image dimension analysis | Automatic via doctor |
| pandoc | Content verification (optional) | brew install pandoc |
Design Principles
Document elements and their typical applications:
| Element | When to Use |
|---|
| Pagination | Any multi-page document that benefits from navigation |
| Running headers/footers | Documents requiring persistent identity (title, org, date) |
| Title page | Formal deliverables: proposals, reports, theses, white papers |
| Table of Contents | Long-form documents with three or more major sections |
| Decorative covers | High-polish deliverables with branding or visual identity |
Consult guides/best-practices.md for sensible defaults when creating from scratch. If the user supplies a template, follow its conventions instead.
Visual Guidelines
- Favour understated colour palettes; avoid high-saturation defaults
- Provide ample whitespace (margins no less than 72 pt, paragraph spacing no less than 10 pt)
- Establish a clear typographic hierarchy (distinct heading sizes, consistent body text)
- Body text line spacing should be at least 1.5x
Flow Control
| Element | Property | Purpose |
|---|
| Primary heading | PageBreakBefore + KeepNext | Chapter separation |
| Secondary heading | KeepNext | Bind to following content |
| Pre-table text | KeepNext | Prevent orphaned introduction |
Multi-Column Layout
| Scenario | Pattern | Detail |
|---|
| Full-width header above multi-column body | Section break with Continuous type | See troubleshooting.md section 5.2 |
| Even content across columns | Manual column breaks | See troubleshooting.md section 5.3 |
| Single-page constraint (broadsheet) | All sections Continuous, no page breaks | See troubleshooting.md section 5.5 |
Note: Word columns are flow-based - text fills left to right. Without explicit column breaks, content may not reach all columns.
Pre-Delivery Checks
| Item | Requirement |
|---|
| CJK quotation marks | Use \u201c and \u201d escape sequences |
| Bookmark placement | Must be direct paragraph children, not inside pPr |
| Drawing IDs | Must be globally unique (use an incrementing counter) |
| Background images | Generate via visuals/backdrops.py |
| Headers/footers | If present, implement completely (no partial stubs) |
| Page numbers | If included, verify correct field codes (PAGE / NUMPAGES) |
Content spot-check:
python3 <skill-path>/docx_engine.py preview output.docx
