miyazawai/dsh-melody-launcher-overture/officecli-docx

OfficeCLI DOCX Skill

Setup

If officecli is missing:

• macOS / Linux: curl -fsSL https://d.officecli.ai/install.sh | bash
• Windows (PowerShell): irm https://d.officecli.ai/install.ps1 | iex

Verify with officecli --version (open a new terminal if PATH hasn't picked up). If install fails, download a binary from https://github.com/iOfficeAI/OfficeCLI/releases.

⚠️ Help-First Rule

This skill teaches what good docx looks like, not every command flag. When a property name, enum value, or alias is uncertain, consult help BEFORE guessing.

officecli help docx                         # List all docx elements
officecli help docx <element>               # Full element schema (e.g. paragraph, field, numbering, watermark, toc)
officecli help docx <verb> <element>        # Verb-scoped (e.g. add field, set section)
officecli help docx <element> --json        # Machine-readable schema

Help is pinned to the installed CLI version. When this skill and help disagree, help is authoritative.

Mental Model

A .docx is a ZIP of XML parts (document.xml, styles.xml, numbering.xml, header*.xml, footer*.xml, comments.xml, …). Everything the user sees — headings, tables, page numbers, TOC, tracked changes — is XML inside that ZIP. officecli gives you a semantic-path API (/body/p[1]/r[2]) over it, so you almost never touch raw XML; when you must, use raw-set (see the XML appendix).

Shell & Execution Discipline

docx paths contain []; some prop values contain $. Both are shell metacharacters. Escaping happens at three layers — keep them separate.

1. Shell. ALWAYS quote element paths: "/body/p[1]", not /body/p[1] (zsh/bash glob [N]). Single-quote any value containing $: --prop text='$50M' — at any length, the whole value inside one pair of single quotes. Unquoted $50M is stripped to M; mixing '…$var…' and "…$50…" on one long string is where the $50 silently vanishes.
2. CLI (`text=`). The two-char escapes \n and \t ARE interpreted in --prop text= — \n becomes a <w:br/> soft line break, \t a <w:tab/> — consistently across docx / pptx / xlsx. Double them (\\n) for a literal backslash-n (rarely wanted). This applies to row-level table c1…cN shortcuts too (\n → <w:br/> within the cell).
3. JSON (batch). A real newline can also be passed as "\n" in the JSON string of a batch heredoc; same result.

If in doubt, view text after writing and compare character-for-character.

Incremental execution. officecli mutates the file on every call. Run commands one at a time and check each exit code — a 50-command script that fails at command 3 cascades silently. After any structural op (new style, table, TOC, section break) run get on it before stacking more.

Open/save lifecycle: officecli open <file> at the start, officecli save <file> at the end to flush to disk — save only writes and leaves the resident warm for follow-up edits; reach for officecli close <file> only to release the resident on a one-shot handoff. Both are always safe (never error or lose work). For many paragraphs of one style, use batch (one pass for the whole array). Flush only at the non-officecli boundary: officecli's own reads always see your edits; run save/close only before a non-officecli program reads the file (python-docx, Word, a renderer, delivery).

`$FILE` convention. All commands use "$FILE" — set it once (FILE="your-doc.docx"). Never copy a literal doc.docx / review.docx into output — always substitute your actual target.

Requirements for Outputs

Deliverable standards every document MUST meet — know these before reaching for a command.

Clear hierarchy. Every non-trivial document has Title → Heading 1 → Heading 2 → body, not a wall of unstyled Normal paragraphs. If view outline shows one flat list, the hierarchy is missing.

Explicit heading sizes (Word default style sizes drift between templates): H1 ≥ 18pt (20pt for long reports), H2 = 14pt bold, H3 = 12pt bold, body = 11–12pt, line spacing 1.15–1.5x. Prefer style=Heading1 over inline sizes so a retheme touches the definition once — but set explicit sizes when you can't trust the template's styles.

One body font, one accent. One readable body font (Calibri, Cambria, Georgia, Times New Roman); accent color for heading emphasis or table headers, not rainbow formatting.

Spacing through properties. Use spaceBefore / spaceAfter on paragraphs. Rows of empty paragraphs break pagination and are flagged by view issues.

Typographic quality. New content uses curly quotes (' ' " "), not ASCII — Unicode directly or XML entities (‘/’/“/”) inside raw-set. En-dash – for ranges (2024–2026), em-dash — for parenthetical breaks.

Headers, footers, page numbers on any document > 1 page. Page numbers go through a live PAGE field (--prop field=page), never the literal text "Page 1" — the CLI injects <w:fldChar> for you (see Headers & Footers).

Preserve existing templates. When editing a file that already has a look, match it — existing conventions override these guidelines.

Visual delivery floor (applies to EVERY document)

Before declaring done, run officecli view "$FILE" html and Read the returned HTML path to confirm ALL of these:

• No placeholder tokens rendered as data. $xxx$, {var}, {{name}}, <TODO>, lorem, xxxx must never appear in a heading, body, cover, TOC, caption, header, or footer. A literal {name} meant for a human to fill belongs inside a visible instruction paragraph ("Replace {name} before sending"), never as finished content.
• No truncated titles or overflowing cells. Widen the column or set wrapText rather than trimming content.
• TOC present when the document has 3+ headings (--type toc).
• Cover page ≥ 60% filled, last page ≥ 40% filled. Pad a thin cover with subtitle / author / date / scope / key highlights; pad a "Thank you" last page with conclusion / next steps / contact / legal.
• No `\$`, `\t`, `\n` literals in document text. If view text shows these, a shell-escape layer leaked — delete the paragraph and re-enter it.

If any fails, STOP and fix before declaring done.

Common Workflow

Six steps. Every non-trivial build follows this shape.

1. Open the file. officecli open "$FILE" (resident default). New file: officecli create "$FILE" first.
2. Orient. Existing file: officecli view "$FILE" outline — heading tree, section count, whether a TOC / watermark / tracked changes already exist. Never edit blind.
3. Build incrementally. Structural first, content next, formatting last: styles & numbering defs → sections / page setup → headings & body → tables / images / fields / TOC → headers / footers → comments. After each structural op, get it back before stacking on top.
4. Format to spec. Explicit heading sizes, spacing, widths, alignment, tabs, list indents — formatting is part of the deliverable, not optional polish.
5. Save, then trust structure over cached text. officecli save "$FILE" writes the XML. TOC / PAGE / NUMPAGES / SEQ / PAGEREF fields carry cached values that may be stale or empty until a human recalculates (F9 in Word). Confirm fields exist (get --depth 3 finds <w:fldChar>) rather than trusting the visible text.
6. QA — assume there are problems. You are done after one fix-and-verify cycle finds zero new issues, not when your last command exited 0. See QA.

Quick Start

Minimal viable docx: a heading, a body paragraph, a subheading, and a footer with a live page-number field. Adapt, don't copy-paste — your file, your content.

FILE="review.docx"
officecli create "$FILE"
officecli open "$FILE"
officecli add "$FILE" /body --type paragraph --prop text="Q4 2026 Review" --prop style=Heading1 --prop size=20pt --prop bold=true --prop spaceAfter=12pt
officecli add "$FILE" /body --type paragraph --prop text="Revenue grew 18% year-over-year, ahead of plan." --prop size=11pt --prop spaceAfter=8pt
officecli add "$FILE" /body --type paragraph --prop text="Key Drivers" --prop style=Heading2 --prop size=14pt --prop bold=true --prop spaceBefore=12pt --prop spaceAfter=6pt
officecli add "$FILE" /body --type paragraph --prop text="Enterprise renewals, upsell, and a new EMEA region." --prop size=11pt
officecli add "$FILE" / --type footer --prop type=default --prop size=9pt --prop text="Page " --prop field=page
officecli set "$FILE" "/footer[1]/p[1]" --prop align=center
officecli save "$FILE"
officecli validate "$FILE"

Verified: validate returns no errors found; get /footer[1] --depth 3 shows the 5-run PAGE field chain (begin / instrText / separate / cached value / end).

Reading & Analysis

Start wide, then narrow. outline tells you what's already there; jump into view text / get / query once you know where to look.

officecli view "$FILE" outline            # heading tree, section count, table/image counts, watermark, tracked-changes presence — orient here first
officecli view "$FILE" html               # Read the returned HTML path: first visual check after a batch of edits (hierarchy, empty-para spacing, missing TOC)
officecli view "$FILE" text --start 1 --end 80   # text for content QA; paths shown as [/body/p[N]] so you can jump back with get
officecli view "$FILE" annotated          # values + style/font/size + warnings per run
officecli view "$FILE" stats              # paragraph counts, font usage, style distribution
officecli view "$FILE" issues             # empty paras, missing alt text, spacing anomalies

officecli watch "$FILE" keeps a live preview running for the human user to open at their discretion — agent self-check uses view html. Final visual verification is the user opening the .docx in Word / WPS / Pages.

Inspect one element. XPath-style semantic paths (1-based). Always quote — shells glob [N]. Use [last()] (with parens) for the last element; [last] errors. Add --json for machine output.

officecli get "$FILE" /                          # document root: metadata, page setup
officecli get "$FILE" "/body/p[1]"                # one paragraph
officecli get "$FILE" "/body/p[1]/r[1]"           # one run (character-level formatting)
officecli get "$FILE" "/body/tbl[1]" --depth 3    # table with rows and cells
officecli get "$FILE" "/footer[1]" --depth 3      # footer — check for fldChar
officecli get "$FILE" "/styles/Heading1"          # style definition
officecli get "$FILE" /numbering --depth 2        # numbering abstractNum + num bindings

Query across the document. CSS-like selectors, for systematic checks rather than hand-walking. Operators: =, !=, ~= (contains), >=, <=, [attr] (exists). Full reference: officecli query --help.

officecli query "$FILE" 'paragraph[style=Heading1]'       # all H1s
officecli query "$FILE" 'p:contains("quarterly")'         # text match
officecli query "$FILE" 'p:empty'                         # empty paragraphs (clutter)
officecli query "$FILE" 'image:no-alt'                    # accessibility gaps
officecli query "$FILE" 'paragraph[size>=24pt]'           # numeric comparison
officecli query "$FILE" 'field[fieldType!=page]'          # fields other than PAGE

query --json wraps results in .data.results[] — jq '.data.results | length' to count.

Large documents. Navigate by heading with view outline and jump with query; don't dump the whole body into context.

Creating & Editing

Verbs: add (new element), set (change a prop), remove, move, swap, batch, raw-set (last-resort XML). Ninety percent of a build is paragraphs, runs, tables, a couple of images, a TOC, and a footer.

Paragraphs, runs, styles