Word Documents

.docx create, edit, read, and visual verification

Overview

The docx skill handles the full lifecycle of Word documents: creation from scratch, editing existing files, reading and analysis, template-based generation, tracked-change management, and mandatory visual QA verification. It is scoped exclusively to .docx files — not PDFs, spreadsheets, HWPX, or Google Docs.

The primary tool is officecli, a CLI on PATH that covers ~80% of tasks (add, set, remove, validate, query, track-change accept/reject). For tasks officecli cannot handle — tracked-change creation, OMML equations, bulk pattern matching — the skill falls back to Python OOXML scripts in scripts/.

Triggers

Quick Reference

"~해줘" Usage Examples

Reference-Based Editing

When a user says "format like X.docx", "match existing style", "based on template", or provides a source file — always start from the source file. Never rebuild from scratch.

Workflow

1. Copy the source: cp source.docx target.docx — inherits all styles, margins, numbering, headers, footers
2. Open: officecli open target.docx — daemon starts; command returns immediately
3. Remove body content only — keep /styles, /numbering, /header, /footer
4. Add new paragraphs using existing style names (e.g. --prop style=Heading1) — they auto-apply

Why This Matters

Pandoc-generated and Word-generated documents have specific style IDs (e.g. Heading1, BodyText, FirstParagraph) unique to that document. Adding a new style with the same name causes:

• officecli validate errors about duplicate style IDs
• Word/LibreOffice rendering falls back to defaults
• The task takes 10x longer than necessary

Template Priority

1. User-provided source file — first-class template
2. tests/fixtures/*.docx — pre-built working examples shipped with the skill
3. officecli create blank — only when nothing else applies

# CORRECT: inherit Pandoc styles
cp Assignment1.docx Assignment2.docx
officecli open Assignment2.docx
officecli remove Assignment2.docx "/body/p[1]"   # remove old body (keep styles/headers/footers)
# ... remove more paragraphs ...
officecli add Assignment2.docx /body --type paragraph --prop text="New title" --prop style=Heading1
officecli close Assignment2.docx

# WRONG: recreate styles that already exist -- validate fails
officecli add doc.docx /styles --type style --prop name=Heading1 --prop size=20pt ...

Escalation Ladder

When officecli cannot do the job, escalate in this order:

Escalation Signals

• officecli shows "silently ignored" → L2 (raw-set)
• Need OMML/MathML equations → L4 (inject <m:oMath> XML)
• Need to CREATE tracked changes (officecli only accepts/rejects) → L3 or L4
• Bulk find/replace across 100+ targets → L3 (docx_cli.py search/replace)
• Pandoc-generated doc with custom style IDs → Reference-Based Editing first
• Task still fails after L1+L2 → Read relevant references/*.md before giving up

Core Workflows

Execution Model

Run commands one at a time. Do not write all commands into a shell script and execute as a single block. OfficeCLI is incremental: every add, set, and remove immediately modifies the file and returns output.

1. One command at a time, then read the output. Check the exit code before proceeding.
2. Non-zero exit = stop and fix immediately. Do not continue building on a broken state.
3. Verify after structural operations. After adding a style, table, chart, or section, run get or validate before building on top of it.

Reading and Analyzing

officecli view doc.docx text                    # Full text extraction
officecli view doc.docx text --max-lines 200    # Truncated extraction
officecli view doc.docx text --start 1 --end 50 # Range extraction
officecli view doc.docx outline                 # Structure: stats, headings, headers/footers
officecli view doc.docx annotated               # Style/font/size per run, equations as LaTeX
officecli view doc.docx stats                   # Paragraph count, style/font distribution

Element Inspection

officecli get doc.docx /                        # Document root (metadata, page setup)
officecli get doc.docx /body --depth 1           # List body children
officecli get doc.docx "/body/p[1]"              # Specific paragraph
officecli get doc.docx "/body/p[1]/r[1]"         # Specific run
officecli get doc.docx "/body/tbl[1]" --depth 3  # Table structure
officecli get doc.docx /styles                   # Style definitions
officecli get doc.docx "/styles/Heading1"        # Specific style
officecli get doc.docx "/header[1]"              # Header/footer
officecli get doc.docx /numbering                # Numbering definitions
officecli get doc.docx "/body/p[1]" --json       # JSON output for scripting

CSS-like Queries

officecli query doc.docx 'paragraph[style=Heading1]'            # By style
officecli query doc.docx 'p:contains("quarterly")'              # By text content
officecli query doc.docx 'p:empty'                              # Empty paragraphs
officecli query doc.docx 'image:no-alt'                         # Images without alt text
officecli query doc.docx 'p[align=center] > r[bold=true]'      # Compound selectors
officecli query doc.docx 'paragraph[size>=24pt]'                # By size
officecli query doc.docx 'field[fieldType!=page]'               # Fields by type

Headers and Footers

# Step 1. Empty footer for cover page (auto-enables differentFirstPage)
officecli add doc.docx / --type footer --prop type=first --prop text=""

# Step 2. Default footer with static "Page " text
officecli add doc.docx / --type footer --prop text="Page " \
  --prop type=default --prop align=center --prop size=9pt --prop font=Calibri

# Step 3. Inject PAGE field via raw-set
# (footer[2] = default when first-page footer also exists)
officecli raw-set doc.docx "/footer[2]" \
  --xpath "//w:p" \
  --action append \
  --xml '<w:r ...><w:fldChar w:fldCharType="begin"/></w:r>
         <w:r ...><w:instrText xml:space="preserve"> PAGE </w:instrText></w:r>
         <w:r ...><w:fldChar w:fldCharType="end"/></w:r>'

Footer index rule: When both a first-page footer and a default footer are added, the default footer is /footer[2]. If there is no first-page footer, the default footer is /footer[1]. Always verify with officecli get doc.docx "/footer[2]".

Resident Mode (Performance)

Always use open/close — it is the smart default. Every command benefits from no repeated file I/O.

officecli open doc.docx           # Load once into memory (returns IMMEDIATELY)
officecli add doc.docx ...        # All commands run in memory -- fast
officecli set doc.docx ...
officecli close doc.docx          # Write once to disk

Batch Mode

Execute multiple operations in a single open/save cycle:

cat <<'EOF' | officecli batch doc.docx
[
  {"command":"add","parent":"/body","type":"paragraph",
   "props":{"text":"Introduction","style":"Heading1"}},
  {"command":"add","parent":"/body","type":"paragraph",
   "props":{"text":"This report covers Q4 results.","font":"Calibri","size":"11pt"}}
]
EOF

Batch supports: add, set, get, query, remove, move, swap, view, raw, raw-set, validate.

Subskill References

Additional detail lives in companion files loaded on demand:

Decision Flow

Is the document an academic paper (thesis, journal, conference)?
  YES --> read officecli-academic-paper/SKILL.md
  NO  --> continue with main skill

User provided a source file to match?
  YES --> Reference-Based Editing + editing.md
  NO  --> creating.md

Python OOXML Scripts

When officecli reaches its limits, the skill falls back to these Python scripts:

Reference Materials

Design Principles for Business Documents

Heading Hierarchy

• H1: Document title (one per document)
• H2: Major sections
• H3: Subsections under H2
• Never skip levels (H1 → H3 is invalid). Table of Contents depends on correct heading structure.

# Verify heading hierarchy
officecli view report.docx outline

Color Palette

Never use rainbow colors, bright primary colors, or more than 3 accent colors in a single document.

Font Selection

Typography

Body text: 11-12pt. Headings step up: H1 = 18pt minimum (20pt preferred for long documents), H2 = 14pt bold, H3 = 12pt bold. Line spacing of 1.15x-1.5x for body text.

Content-to-Element Mapping

Mandatory Verification

# Step 1: Structural validation
officecli validate output.docx

# Step 2: Visual PDF verification
soffice --headless --convert-to pdf --outdir /tmp output.docx
# Open/inspect PDF to confirm: formatting, tables, images, headers/footers

• Skipping PDF verification = unverified output
• If validate reports errors, fix them before delivering the file

QA Checklist

Assume there are problems. Your job is to find them.

Issue Detection

officecli view doc.docx issues
officecli view doc.docx issues --type format
officecli view doc.docx issues --type content
officecli view doc.docx issues --type structure

Content QA

officecli view doc.docx text
officecli view doc.docx outline
officecli query doc.docx 'p:empty'
officecli query doc.docx 'image:no-alt'

# Check for leftover placeholders
officecli query doc.docx 'p:contains("lorem")'
officecli query doc.docx 'p:contains("placeholder")'

Pre-Delivery Checklist

• Metadata set (title, author)
• PAGE field injected in footer via raw-set — verify with officecli get doc.docx "/footer[2]" --depth 3
• First-page footer added if document has a cover page
• Cover page content fills at least 60% of the page
• TOC present when document has 3+ headings
• Last page content fills at least 40% of the page
• Heading hierarchy correct (no skipped levels)
• No empty paragraphs used as spacing
• All images have alt text
• Tables have header rows
• Document validates with officecli validate
• No placeholder text remaining

Verification Loop

1. Generate document
2. Run view issues + view outline + view text + validate
3. List issues found (if none, look again more critically)
4. Fix issues
5. Re-verify — one fix often creates another problem
6. Repeat until a full pass reveals no new issues

Do not declare success until you have completed at least one fix-and-verify cycle.

Common Pitfalls

Known Issues

Anti-Patterns (Must Avoid)

• Placeholder data: Never leave "Acme Corp", "Alice Chen", "Lorem ipsum" in output. If the user has not provided data, ask.
• Footer PAGE fields: When setting page numbers via raw-set, the XML structure must be exact (fldChar/instrText/fldChar sequence).
• Empty paragraphs for spacing: Use spacing-after properties.
• Manual bullet characters (-, *): Use listStyle=bullet or listStyle=number.
• Manual font XML injection: Use --prop font=... when it suffices.
• Ignoring reference materials: If a complex task fails with officecli, read references/*.md and check scripts/*.py before giving up.
• Recreating existing styles: When user provides a source file, copy it and modify — do not rebuild styles from scratch.

Tool Discovery

Always confirm syntax from help before guessing:

officecli --help
officecli help docx
officecli help docx add
officecli help docx set
officecli help docx query
officecli help docx add paragraph --json
officecli help docx set run --json

Dependencies

Prerequisite Check

# Required
python3 -c "import docx, lxml" || echo "MISSING: pip install python-docx lxml"

# On-demand: LibreOffice
which soffice >/dev/null 2>&1 || echo "INFO: LibreOffice not installed"

# On-demand: OfficeCLI
which officecli >/dev/null 2>&1 || echo "INFO: OfficeCLI not installed"