/kimi-docx

name: kimi-docx
description: Generate and edit Word documents (.docx). Supports professional documents including covers, charts, track-changes editing, and more. Suitable for any .docx creation or modification task.

Part 1: Goals

⚠️ When to Unzip vs Read

**To preserve ANY formatting from the source document, MUST unzip and parse XML.**

Read tool returns plain text only — fonts, colors, alignment, borders, styles are lost.

| Need | Method | |------|--------| | Text content only (summarize, analyze, translate) | Read tool is fine | | Formatting info (copy styles, preserve layout, template filling) | Unzip and parse XML | | Structure + comments/track changes | `pandoc input.docx -t markdown` |

Core Principles

1. **Preserve formatting** — When editing existing documents, retain original formatting. Clone and modify, never recreate.

2. **Correct feature implementation** — Comments need multi-file sync. Track Changes need revision marks. Use the right structure.

**Never use python-docx/docx-js as fallback.** These libraries produce lower quality output than direct XML manipulation.

Source Principle

**Template provided = Act as form-filler, not designer.**

• Format is the user's decision
• Task: replace placeholders, not redesign
• Like filling a PDF form—do not redesign

**No template = Act as designer.** Design freely based on scenario.

For .doc (legacy format), first convert with `libreoffice --headless --convert-to docx`.

---

Part 2: Execution

File Structure

docx/
├── SKILL.md                      ← This file (entry point + reference)
├── references/
│   └── EditingGuide.md           → Complete Python editing tutorial (comments, track changes, 5-file sync)
├── scripts/
│   ├── docx                      → Unified entry (the only script to call)
│   ├── fix_element_order.py      → Auto-fix XML element ordering
│   ├── validate_docx.py          → Business rule validation
│   ├── generate_backgrounds.py       → Morandi style backgrounds
│   ├── generate_inkwash_backgrounds.py → Ink-wash style backgrounds
│   └── generate_chart.py         → matplotlib (only for heatmaps/3D/radar; simple charts must use native)
├── assets/
│   └── templates/
│       ├── KimiDocx.csproj       → Project file template (for creating new docs)
│       ├── Program.cs            → Program entry template
│       ├── Example.cs            → Complete example (cover+TOC+charts+back cover)
│       ├── CJKExample.cs         → CJK content patterns (quote escaping, fonts)
│       └── xml/                  → XML templates for comments infrastructure
└── validator/                    → OpenXML validator (pre-compiled binary, AI does not modify)

**Creating new documents**: Use C# SDK with `./scripts/docx build` → See `Example.cs` for patterns, `CJKExample.cs` for CJK content **Editing existing documents**: Use Python + lxml → See `references/EditingGuide.md` for complete tutorial

⚠️ **Do NOT mix these approaches.** C# SDK for creation, Python for editing. Never use python-docx/docx-js.

Environment Setup

First time, execute in the SKILL directory:

cd /app/.kimi/skills/kimi-docx/
./scripts/docx init

**Fixed Path Conventions** (cannot be changed):

| Path | Purpose | |------|---------| | `/app/.kimi/skills/kimi-docx/` | SKILL directory, where commands are executed | | `/tmp/docx-work/` | Working directory, edit `Program.cs` here | | `/mnt/okcomputer/output/` | Output directory, final deliverables | | `/mnt/okcomputer/upload/` | User upload location (input files) |

**Script Commands** (`./scripts/docx <cmd>`):

| Command | Purpose | |---------|---------| | `env` | Show environment status (no changes) | | `init` | Setup dependencies + workspace | | `build [out]` | Compile, run, validate (default: output/output.docx) | | `validate FILE` | Validate existing docx |

The script automatically handles:

• Detects dotnet/python3 (required), pandoc/playwright/matplotlib (optional)
• Installed → use directly; Not installed → auto-install; Broken → repair
• Initializes working directory, copies template files

Build Process

**Must use `./scripts/docx build`**, do not execute `dotnet build && dotnet run` separately (skips validation).

Program.cs Output Path Convention (Critical)

**Program.cs must get output path from command line arguments**, otherwise build script cannot find the generated file:

// Correct - get output path from command line arguments
string outputFile = args.Length > 0 ? args[0] : "/mnt/okcomputer/output/output.docx";

// Wrong - hardcoded path causes build failure
string outputFile = "my_document.docx";  // Script can't find file!

| Step | Action | Notes | |------|--------|-------| | 1. Compile | `dotnet build` | Provides fix suggestions on failure | | 2. Generate | `dotnet run -- <output path>` | Path passed via command line args | | 3. Auto-fix | `fix_element_order.py` | Fixes XML element ordering issues | | 4. OpenXML validation | `validator/` | Mandatory | | 5. Business rules | `validate_docx.py` | Mandatory | | 6. Statistics | Character + word count | Optional (requires pandoc) |

**Validation is mandatory**: On failure, file is kept but warnings are shown. Check error messages to fix issues.

Standalone Validation

cd /app/.kimi/skills/kimi-docx/
./scripts/docx validate /mnt/okcomputer/output/report.docx

Content Verification (Mandatory)

**pandoc is the SOURCE OF TRUTH.** OpenXML validator checks structure; pandoc shows actual content.

Before delivery, verify with pandoc:

• `pandoc output.docx -t plain` — check text completeness
• For revisions/comments: add `--track-changes=all` to verify marker positions

**⚠️ Critical**: `comments.xml` exists ≠ comments visible. Count mismatch = `doc_tree` not saved. See `references/EditingGuide.md` §5.3.

---

Part 3: Quality Standards

Delivery Standard

**Generic styling and mediocre aesthetics = mediocre delivery.**

Deliver studio-quality Word documents with d