agentbull/ankole/docx

OfficeCLI DOCX Skill

For visual styling, use design-md when the user requests the internal design system or VIS, skip it when they opt out or choose another style instead, and treat it as optional when no style source is specified.

Setup

The Worker image build installs OfficeCLI and checks its version. Run officecli --version and officecli help docx. If both commands succeed, continue with the installed CLI. Version numbers in upstream references and known-issue notes are not runtime requirements. If either command fails, report the command and error as the runtime blocker. Worker image maintenance happens outside the Job.

Playbooks

A Playbook carries the extra rules for one kind of document. Before you plan the document, list the Playbooks and read every one that matches the request:

bun /repo/app/library/agent-plugins/office/tools/list_playbooks.ts docx

Each line gives the Playbook name, its absolute path, and the condition that selects it. A Playbook inherits every rule in this skill and adds to it, so read this skill first and keep both. When no Playbook matches, build from this skill alone.

⚠️ 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.

officecli help docx ... covers schema elements only. Use a top-level command's own help for its syntax, such as officecli batch --help, officecli open --help, or officecli view --help.

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=`). Newline rules depend on the operation and element:

• add --type paragraph: literal \n or a real newline creates separate paragraphs with the same style and properties. Literal \v or a real vertical tab creates a <w:br/> soft line break within one paragraph. This also applies when adding paragraphs under a table cell.
• set on an existing paragraph, or row-level table c1…cN shortcuts: \n and \v create soft line breaks within one paragraph, including when passed as real control characters.
• Direct cell text=: a newline stays in the text node, without <w:br/>; \v is rejected. Use row shortcuts for cell soft line breaks, or add paragraphs under the cell for separate paragraphs.
• \t in paragraph text creates a <w:tab/>.

1. JSON (batch). For a batch without a legacy dumpVersion marker, JSON "\n" passes a real newline and follows the operation and element rules above. To add a paragraph with a soft line break, use JSON "\u000b". JSON "\\n" and "\\v" stay as literal text: batch does not decode the single-command CLI escapes. "\v" is not a valid JSON escape. Use a single-quoted heredoc delimiter to preserve these escapes.

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. Those names resolve on the reader's machine. The worker installs only IBM Plex Sans SC, IBMPlexMonoSCHalf, and 寒蝉锦书宋 (ChillJinshuSong), so any other family falls back whenever the worker renders the file itself, and Chinese text needs one of the three. For the internal VIS, take the families from design-md.

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 -o "${FILE%.docx}.html" and Read the explicit HTML output file 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 fieldChar) 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 -o "${FILE%.docx}.html"               # Read the explicit HTML output file: 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