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 deep thought on content, functionality, and styling. Users often don't explicitly request advanced features (covers, TOC, backgrounds, back covers, footnotes, charts)—deeply understand needs and proactively extend.

Language Consistency

Document language = User conversation language (including filename, body text, headings, headers, TOC hints, chart labels, and all other text).

Headers and Footers - REQUIRED BY DEFAULT

Most documents MUST include headers and footers. The specific style (alignment, format, content) should match the document's overall design.

• Header: Typically document title, company name, or chapter name
• Footer: Typically page numbers (format flexible: "X / Y", "Page X", "— X —", etc.)
• Cover/Back cover: Use TitlePage setting to hide header/footer on first page

Professional Elements (Critical)

Create documents that exceed user expectations, proactively add professional elements, don't wait for users to ask. Delivery standard: Visual quality of a top designer in 2024.

Cover & Visual:

• Formal documents (proposals, reports, financials, bids, contracts) / creative documents (invitations, greeting cards) must have cover and back cover
• Covers must have designer-quality background images
• Body pages can optionally include backgrounds to enhance visual appeal

Structure:

• Long documents (3+ sections) add TOC, must add refresh hint after TOC

Data Presentation:

• When comparing data or showing trends, use charts instead of plain text lists
• Tables use light gray headers or three-line style, avoid Word default blue

Links & References:

• URLs must be clickable hyperlinks
• Multiple figures/tables add numbering and cross-references ("see Figure 1", "as shown in Table 2")
• Academic/legal/data analysis citation scenarios implement correct in-text click-to-jump references with corresponding footnotes/endnotes

TOC Refresh Hint

Word TOC is field code, page numbers may be inaccurate when generated. Must add gray hint text after TOC, informing users to manually refresh:

Table of Contents
─────────────────
Chapter 1 Overview .......................... 1
Chapter 2 Methods ........................... 3
...

(Hint: On first open, right-click the TOC and select "Update Field" to show correct page numbers)

Hint text requirements:

• Visually subtle — gray color, smaller font size, should not compete with actual TOC entries
• Language: Matches user conversation language

Only When User Explicitly Requests

Feature	Reason
Watermark	Changes visual state. SDK limitation: VML watermark classes don't serialize correctly; must write raw XML to header.
Document protection	Restricts editing
Mail merge fields	Requires data source

Chart Selection Strategy (Critical)

Default to native Word charts, editable, small file size, professional.

Chart Type	Method	Notes
Pie chart	Native	Example.cs → AddPieChart()
Bar chart	Native	Example.cs → AddBarChart()
Line chart	Native	Reference bar chart structure, use c:lineChart
Horizontal bar	Native	Reference bar chart structure, use barDir="bar"
Heatmap, 3D, radar	matplotlib	Word native doesn't support
Complex statistics (box plot, etc.)	matplotlib	Word native doesn't support

Native charts are preferred (editable, smaller files), but matplotlib is acceptable for data analysis scenarios.

Inserting Images/Charts

Any PNG (matplotlib charts, backgrounds, photos) must be inserted using AddInlineImage():

AddInlineImage(body, mainPart, "/path/to/image.png", "Description", docPrId++);

Critical:

• Chart labels/titles must match document language (e.g., Chinese labels for Chinese docs)
• Build output shows X images — if 0, images were not inserted

Content Constraints

Word/Page Count Requirements

User Request	Execution Standard
Specific word count (e.g., "3000 words")	Actual output within ±20%
Specific page count (e.g., "5 pages")	Exact match
Range (e.g., "2000-3000 words")	Within range
Minimum (e.g., "at least 5000 words")	No more than 2x the requirement

Forbidden: Padding word count with excessive bullet point lists. Maintain information density.

Outline Adherence

• User provides outline: Follow strictly, no additions, deletions, or reordering
• No outline provided: Use standard structure
  • Academic: Introduction → Literature → Methods → Results → Discussion → Conclusion
  • Business: Executive Summary → Analysis → Recommendations
  • Technical: Overview → Principles → Usage → Examples → FAQ

Scene Completeness

Think one step ahead of the user, complete elements the scenario needs. Examples below are not exhaustive — apply this principle to ALL document types:

• Exam paper → Name/class/ID fill areas, point allocation per question (consider total), grading section
• Contract → Signature and seal areas for both parties, date, contract number, attachment list
• Meeting minutes → Attendees, absentees, action items with owners, next meeting time

Design Philosophy

Color Scheme

Low saturation tones, avoid Word default blue and matplotlib default high saturation.

Flexibly choose color schemes based on document scenario:

Style	Palette	Suitable Scenarios
Morandi	Soft muted tones	Artistic, editorial
Earth tones	Brown, olive, natural	Environmental, organic
Nordic	Cool gray, misty blue	Minimalist, tech
Japanese Wabi-sabi	Gray, raw wood, zen	Traditional, contemplative
French elegance	Off-white, dusty pink	Luxury, feminine
Industrial	Charcoal, rust, concrete	Manufacturing, engineering
Academic	Navy, burgundy, ivory	Research, education
Ocean mist	Misty blue, sand	Marine, wellness
Forest moss	Olive, moss green	Nature, sustainability
Desert dusk	Ochre, sandy gold	Warm, regional

Color scheme must be consistent within the same document.

Layout

White space (margins, paragraph spacing), clear hierarchy (H1 > H2 > body), proper padding (text shouldn't touch borders).

Pagination Control

Word uses flow layout, not fixed pages. Control pagination with these properties:

Property	XML	Effect
Keep with next	<w:keepNext/>	Heading stays on same page as following paragraph
Keep lines together	<w:keepLines/>	Paragraph won't break across pages
Page break before	<w:pageBreakBefore/>	Force new page (for H1)
Widow/orphan control	<w:widowControl/>	Prevent single lines at top/bottom of page

// Example: H1 always starts on new page, stays with next paragraph
new ParagraphProperties(
    new ParagraphStyleId { Val = "Heading1" },
    new PageBreakBefore(),
    new KeepNext(),
    new KeepLines()
)

Table pagination:

// Allow row to break across pages (avoid large blank areas)
new TableRowProperties(
    new CantSplit { Val = false }  // false = can split
)

// Repeat header row on each page
new TableRowProperties(
    new TableHeader()
)

---

Part 4: Technical Reference

Choose your path:

Task	Stack	Reference
Create new document	C# + OpenXML SDK	4.1-4.6 + Example.cs
Edit existing document	Python + lxml	4.7 + references/EditingGuide.md

---

4.1 SDK Fundamentals

Schema Compliance (MEMORIZE THESE)

OpenXML has strict element ordering requirements. Wrong order = Word cannot open the file.

Required Styles

// Normal style must exist - all Heading styles use basedOn="Normal"
styles.Append(new Style(
    new StyleName { Val = "Normal" },
    new StyleParagraphProperties(
        new SpacingBetweenLines { After