---
name: create-docx
description: "Create, read, and edit Word documents (.docx) with professional formatting."
whenToUse: "User asks to create a Word document, .docx file"
---

# Skill: Create Word Document (DOCX)

## Description
Create, read, and edit Word documents (.docx) with professional formatting, tables, images, headers/footers, and Chinese font support. Use this when user wants a Word document deliverable.

## When to Use
- User asks to create a Word document, .docx file
- User says "帮我做个Word文档" or "create a docx"
- User wants a formatted report/proposal/spec as Word (not PDF)
- User wants to edit an existing .docx file

## Prerequisites
- Python with `python-docx` library
- Install if needed: `pip install python-docx`

## Creating Documents with python-docx

### 1. Basic Setup
```python
from docx import Document
from docx.shared import Inches, Pt, Cm, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.enum.style import WD_STYLE_TYPE

doc = Document()

# Set default font (Chinese support)
style = doc.styles['Normal']
font = style.font
font.name = 'Microsoft YaHei'
font.size = Pt(11)

# For East Asian font fallback
from docx.oxml.ns import qn
style.element.rPr.rFonts.set(qn('w:eastAsia'), 'Microsoft YaHei')
```

### 2. Content Elements

#### Headings
```python
doc.add_heading('Title', level=0)  # Document title
doc.add_heading('Section', level=1)  # Major section
doc.add_heading('Subsection', level=2)  # Minor section
```

#### Paragraphs
```python
p = doc.add_paragraph('Normal paragraph text.')
p.alignment = WD_ALIGN_PARAGRAPH.JUSTIFY

# Bold, italic, colored text
p = doc.add_paragraph()
run = p.add_run('Bold text ')
run.bold = True
run = p.add_run('and normal text.')
```

#### Bullet Lists
```python
doc.add_paragraph('First item', style='List Bullet')
doc.add_paragraph('Second item', style='List Bullet')
doc.add_paragraph('Numbered item', style='List Number')
```

#### Tables
```python
table = doc.add_table(rows=3, cols=3, style='Light Grid Accent 1')
# Set header row
hdr_cells = table.rows[0].cells
hdr_cells[0].text = 'Column 1'
hdr_cells[1].text = 'Column 2'
hdr_cells[2].text = 'Column 3'
# Add data
row = table.rows[1].cells
row[0].text = 'Data 1'
row[1].text = 'Data 2'
row[2].text = 'Data 3'
```

#### Images
```python
doc.add_picture('image.png', width=Inches(4))
```

#### Page Breaks
```python
doc.add_page_break()
```

### 3. Headers and Footers
```python
section = doc.sections[0]
header = section.header
header_para = header.paragraphs[0]
header_para.text = "CONFIDENTIAL"
header_para.alignment = WD_ALIGN_PARAGRAPH.RIGHT

footer = section.footer
footer_para = footer.paragraphs[0]
footer_para.text = "Page "
# Note: auto page numbers require XML manipulation
```

### 4. Page Setup
```python
from docx.shared import Cm
section = doc.sections[0]
section.page_height = Cm(29.7)  # A4
section.page_width = Cm(21.0)
section.top_margin = Cm(2.54)
section.bottom_margin = Cm(2.54)
section.left_margin = Cm(2.54)
section.right_margin = Cm(2.54)
```

### 5. Custom Styles
```python
# Create a custom style
custom_style = doc.styles.add_style('CustomQuote', WD_STYLE_TYPE.PARAGRAPH)
custom_style.font.italic = True
custom_style.font.color.rgb = RGBColor(0x66, 0x66, 0x66)
custom_style.font.size = Pt(10)
custom_style.paragraph_format.left_indent = Cm(1.5)
```

### 6. Save
```python
import os, tempfile
output_path = os.path.join(tempfile.gettempdir(), 'document.docx')
doc.save(output_path)
```

## Reading Existing Documents
```python
doc = Document('existing.docx')

# Read all paragraphs
for para in doc.paragraphs:
    print(f"[{para.style.name}] {para.text}")

# Read all tables
for table in doc.tables:
    for row in table.rows:
        for cell in row.cells:
            print(cell.text, end='\t')
        print()
```

## Table Styles Available
Common built-in styles (no need to define):
- `Table Grid` — Simple borders
- `Light Grid Accent 1` — Blue header with light grid
- `Light Shading Accent 1` — Blue shaded header
- `Medium Shading 1 Accent 1` — Stronger blue styling

## Important Notes
- **Chinese fonts**: Always set both `font.name` and `w:eastAsia` for proper Chinese rendering
- **Never use `\n` in paragraphs** — create new Paragraph objects instead
- **Table widths**: Set column widths explicitly for consistent rendering
- **Images**: Always specify width to avoid oversized images
- **Compatibility**: python-docx creates Office-compatible .docx files that work in Word, Google Docs, and LibreOffice
- **For complex layouts**: Consider using create-pdf-report skill instead (more control over positioning)

## Output & Delivery
- Save to temp: system temp directory (e.g. `tempfile.gettempdir()`) as `{filename}.docx`
- Send via email: Use email-with-attachment skill (Outlook REST API)
  - ContentType: `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
