Jaw DOCX

DOCX Skill

Use this skill for any .docx task: create, read, edit, review, template-fill, or QA verification. Triggers: "Word doc", ".docx", reports, memos, letters, templates.

OfficeCLI routing and consent rule:

• First check whether officecli is available with a probe that works in the agent's actual shell: command -v officecli on POSIX, Get-Command officecli -ErrorAction SilentlyContinue in PowerShell. command -v is not a PowerShell builtin or cmdlet — on Windows it prints nothing, sets no exit code, and raises no error, so it is indistinguishable from "not installed" and the agent asks to install a tool that is already there (#298). officecli --version is the portable fallback: a non-zero exit or no output means missing.
• If installed, recommend OfficeCLI first for high-fidelity DOCX mutations, validation, query, batch/resident flows, track changes, and CJK/rhwp-aware work.
• If missing, do not auto-install. Present choices before proceeding:
  1. Install forked OfficeCLI from https://github.com/lidge-jun/OfficeCLI via bash "$(npm root -g)/cli-jaw/scripts/install-officecli.sh".
  2. Continue with lightweight fallback tools for the current task, with limitations stated.
  3. Stop or cancel.
• Before taking a lightweight fallback path, ask the user again and state what fidelity/features may be lost.
• If the user chooses lightweight mode, save that preference to memory for future Office work.
• Use upstream/vanilla iOfficeAI/OfficeCLI only when the user explicitly asks for upstream behavior.

OfficeCLI is the recommended advanced backend for add/set/remove, validate, query, and track-change accept/reject workflows. Lightweight fallback: Python OOXML scripts (scripts/*.py) for what OfficeCLI cannot do, or when the user chooses lightweight mode: tracked-change creation, OMML equations, bulk pattern matching, unpack/edit/repack. See §3.

DOCX only. Do NOT use this skill for PDFs, spreadsheets, HWPX, Google Docs, or any other format.

OfficeCLI discovery rule: before guessing paths, element names, or properties, ask the installed CLI. Use officecli --help for workflow entry points and officecli help docx ... --json for machine-readable schema.

Same-file execution rule: run OfficeCLI commands against the same .docx sequentially. Do not run officecli view, officecli validate, officecli query, or officecli get in parallel against one package. If a file lock occurs, stop and report the exact command and path before making a copy or retrying.

1. Quick Decision

2. Reference-Based Editing (Edit > Create from Scratch)

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

Workflow

1. Copy the source: cp source.docx target.docx — inherits all styles, margins, numbering, headers, footers
2. Open with officecli open target.docx — daemon starts; command returns immediately (do NOT run as run_in_background shell)
3. Remove body content only — keep /styles, /numbering, /header, /footer
4. Add new paragraphs using style names that already exist (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 10× longer than necessary

Template Sources (priority order)

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

Example — Assignment Case

# 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 ...

3. Reference Materials & Script Map

officecli covers most DOCX tasks. For the rest, use these reference docs + Python scripts.

References (references/)

Scripts (scripts/) — Python OOXML Toolkit

Editing Escalation Ladder

When officecli can't 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 — officecli cannot generate these)
• 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 → §2 Reference-Based Editing first
• Task still fails after L1+L2 → Read relevant references/*.md BEFORE giving up

4. Subskill References

Additional detail lives in companion files. Load only the one you need.

Decision flow

Is the document an academic paper (thesis, journal, conference)?
  YES --> read officecli-academic-paper/SKILL.md
  NO  --> continue with this file
User provided a source file to match?
  YES --> §2 Reference-Based Editing + ./editing.md
  NO  --> ./creating.md

5. Design Principles for Business Documents

5.0 Design Read & Document Anti-Slop

Intent discovery (before building): ask audience (board / exec / internal team / public), formality register (formal report · memo · whitepaper · proposal), and density (dense reference vs spacious) — then match the type scale, palette restraint, and whitespace. If the user names a target ("McKinsey-style", "academic", "startup memo"), map to it.

Named document anti-slop (AI-tells — pattern → fix):

1. Calibri-everything — single default font → a deliberate heading+body pair (§5.3), committed.
2. Fake-heading bold — manual bold+size instead of real styles → use Heading 1/2/3 styles (§5.1) so TOC/navigation work.
3. Wall of text — dense unbroken prose → break into lists, callouts, tables, sectioned headings.
4. Default-Word-template look — no palette/style identity → a restrained palette (§5.2) + consistent scale.
5. Over-coloring — many accents / colored body text → one accent; body near-black.
6. Justified-everything + orphan headings — full-justify body, headings stranded at page bottom → left-align body; keep headings with content.
7. Placeholder leakage — "Acme Corp"/lorem/TBD in delivered output → realistic specific content, never invented data.

Named palettes + font pairings + personality→doc-type map: references/design-system.md.

5.1 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

5.2 Color Palette

Use professional, muted tones only:

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

5.3 Font Selection

The CJK fork auto-applies East Asian fonts, but verify with:

officecli raw report.docx /document | grep rFonts

5.4 Typography

Choose a readable body font (Calibri, Cambria, Georgia, Times New Roman). Keep body at 11-12pt. Headings should step up: H1=18pt minimum (20pt preferred for long documents), H2=14pt bold, H3=12pt bold.

5.5 Spacing & Page Setup

Use paragraph spacing (spaceBefore/spaceAfter) instead of empty paragraphs. Line spacing of 1.15x-1.5x for body text.

Always set margins explicitly. US Letter default: pageWidth=12240, pageHeight=15840, margins=1440 (1 inch).

5.6 Table of Contents

TOC generation depends entirely on heading styles. Before inserting TOC:

1. Confirm all headings use proper Heading1/Heading2/Heading3 styles (not manual bold+size).
2. Run officecli view FILE outline to verify hierarchy.
3. Generate TOC via the subskill method.

5.7 Table Design & Color Usage

Alternate row shading for readability. Header row with contrasting background. Consistent cell padding. Use color sparingly -- accent color for headings or table headers, not rainbow formatting.

5.8 Content-to-Element Mapping

6. Mandatory Verification (NEVER SKIP)

Delivery Gate — treat verification as a gate, not a confirmation. Any failure = REJECT, do not deliver. Fix → re-run the checks → repeat until a pass finds zero new issues. After 3 rounds without convergence, STOP and report the likely root cause for the user to decide.

After ANY DOCX creation or edit, ALWAYS execute both steps:

# 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

• Skip PDF verification = unverified output. Inform user if soffice is unavailable.
• If validate reports errors, fix them before delivering the file.

7. Prerequisite Check

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

# LibreOffice: check only; ask before installing when PDF conversion is needed.
which soffice >/dev/null 2>&1 || echo "ASK USER: LibreOffice is not installed; install it for PDF conversion or skip PDF output."

# OfficeCLI: check only; do not auto-install from a skill.
if ! command -v officecli >/dev/null 2>&1; then
  echo "ASK USER: install forked OfficeCLI from https://github.com/lidge-jun/OfficeCLI, continue lightweight, or stop."
  echo "Install command after approval: bash \"\$(npm root -g)/cli-jaw/scripts/install-officecli.sh\""
fi

8. 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

Drill into a specific area:

officecli help docx add paragraph
officecli help docx add picture
officecli help docx set run
officecli help docx set style
officecli help all --jsonl | grep '"format":"docx"'

9. Core Workflows

9.1 Execution Model

Run commands one at a time. Do not write all commands into a shell script and execute it 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.

9.2 Reading & 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

9.3 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

9.4 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

9.5 Headers & Footers

Standard footer setup (always use this pattern for documents with a cover page):

--prop field=page works (verified v1.0.115) — add --type footer --prop field=page injects a live PAGE field directly. The old raw-set <w:fldChar> workaround is no longer needed.

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

# Step 2. Default footer with a live PAGE field — no raw-set needed
officecli add doc.docx / --type footer --prop field=page --prop type=default --prop align=center --prop size=9pt --prop font=Calibri

# Verify: officecli get doc.docx "/footer[2]" --depth 3   # shows the fldChar PAGE field

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]" (or "/footer[1]") to confirm the <w:fldChar> element is present.

LibreOffice rendering note: Page number fields may display as static "Page" in LibreOffice PDF preview -- this is a LibreOffice limitation. Open in Microsoft Word to see actual page numbers. Confirm the field with officecli get doc.docx "/footer[2]" -- output must show fldChar children.

9.6 Resident Mode (Performance)

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

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

Do NOT run officecli open as a background shell job (e.g. via run_in_background). It returns immediately and the daemon lives in the background automatically. Running it as a monitored shell creates zombies and file locks. If stuck: pkill -9 -f "officecli.*resident" then retry.

9.7 Batch Mode (Performance)

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.

Batch fields: command, path, parent, type, from, to, index, after, before, props (dict), selector, mode, depth, part, xpath, action, xml.

parent = container to add into (for add). path = element to modify (for set, get, remove, move, swap).

Error decoding: 'X' is an invalid start of a value = shell syntax leaked into JSON (unquoted $, stray shell metachar). Use heredoc cat <<'EOF' | officecli batch FILE with single-quoted 'EOF' delimiter — prevents shell expansion.

10. Common Pitfalls

11. Known Issues

12. 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("xxxx")'
officecli query doc.docx 'p:contains("placeholder")'

Pre-Delivery Checklist

• Metadata set (title, author)
• PAGE field in footer -- add --type footer --prop field=page (works v1.0.115); verify with officecli get doc.docx "/footer[2]" --depth 3 (shows fldChar). If no first-page footer, use "/footer[1]".
• First-page footer added (--prop type=first --prop text="") if document has a cover page
• Cover page content fills >= 60% of the page (accent bars, subtitle, author, date, contact info)
• TOC present when document has 3+ headings (--type toc --prop levels="1-3" --prop title="Table of Contents" --prop hyperlinks=true --prop pagenumbers=true --index 0)
• Last page content fills >= 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've completed at least one fix-and-verify cycle.

QA display notes:

• view text shows "1." for ALL numbered list items regardless of actual rendered number. This is a display limitation -- not a defect.
• view issues flags "body paragraph missing first-line indent" on cover page paragraphs, centered headings, list items, callout boxes, etc. These warnings are expected. First-line indent is only required in APA/academic body text.

13. 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. See the Headers & Footers section for the correct 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.
• Chinese comments in output: Some subskill reference files contain Chinese-language code comments (operational notes). NEVER copy these into user-facing document output. Treat them as internal annotations only.
• Ignoring reference materials: If a complex task fails with officecli, READ references/*.md + check scripts/*.py (§3) BEFORE giving up or falling back to inline text. The Pre-officecli OOXML workflow is still available via scripts.
• Recreating existing styles: When user provides a source file ("format like X.docx"), copy it and modify — do not rebuild styles from scratch. See §2.

14. Dependencies

Fork build (development only)

dotnet publish -c Release -o build-local