Office CLI and coding-agent Skill
The CLI performs deterministic local file work. The Skill teaches a coding agent when and how to call that CLI, inspect structured results, preserve the source file, and verify the output. They are one workflow, so setup and usage live on this page instead of in separate product documents.
1. Install the CLI
Confirm the executable and inspect a file without changing it.
Use --json for coding-agent workflows. Structured results are stable inputs
for decisions and assertions; terminal prose is for people.
2. Install the Skill when an agent needs Office access
Download the A3S Office SkillDownload and extract it into the agent's personal Skill directory.
The archive includes SKILL.md and focused references for Writer,
Spreadsheet, Presentation, Markdown, PDF, and MCP operation.
When a CLI host already has a Skill cache, verify the exact package before using it:
The manifest exposes byte counts and SHA-256 values for SKILL.md and every
bundled reference, so an agent can reload stale guidance instead of making a
decision from an older cache.
3. Run an exact mutation and verify it
A mutation should be followed by a semantic read or validation command. The agent should not treat a zero exit code as proof that the requested document state exists.
4. Ask a coding agent
Reference the Skill, source file, desired change, and verification outcome in one request.
The Skill does not replace application logic or upload files automatically. It provides a bounded workflow around the local CLI. The agent still follows its normal permissions and sandbox policy.
5. Operate the five browser editors
Native CLI commands mutate saved Office artifacts. Browser interaction needs a separate, observable contract. From an Office source checkout, use the Commander-based local operator instead of composing shell conditionals:
The declarative matrix covers Writer, Spreadsheet, Presentation, Markdown, and
PDF. It currently exposes 103 deterministic ACL contracts and 78 visual
contracts. Writer includes character position, scale, spacing, emphasis, hidden
text, OpenType, content controls, review conflicts, paired move revisions,
phone track changes, WPS formatting/review shortcuts, WPS layout/font-grid
parity, and WPS numeric fields; Spreadsheet includes
AutoSum, Paste Special, conditional
formatting, date/time, cell styles, rich text, table totals, orientation and
visibility, appearance/color, custom-list, table-owned, left-to-right,
partial-range, Simplified Chinese text sorting, diagonal borders, linear/path
gradients, and pattern fills, plus WPS font aliases, direct-color resets, and
copy-from-above formula/value copy with target-style preservation,
Spreadsheet phone task-pane, context-menu, Find, worksheet-rename, hyperlink,
and advanced-underline workflows, Presentation IME/large-window, phone chart-pane and comments-review
workflows, and PDF large-file workflows.
A focused gate regenerates ignored fixtures and parses the selected A3S
Test ACLs. With --run, A3S Test is the primary interaction gate; Playwright
is only a supplemental desktop/compact pixel baseline. Evidence is written to
.a3s-test/office-ops/; committed visual baselines are never changed and the
command never waits for CI.
plan <surface> --json is the machine-readable handoff for Codex. It expands
one matrix row into typed fixture, ACL, gate, visual, agent, and (for Writer)
WPS reference commands, so the runner does not need per-surface shell logic.
The Writer row also exposes the shortcut, layout-parity, and font/grid suites
and their generated DOCX fixtures; use that inventory before changing UI code.
doctor --json reports the installed A3S Test version and fails closed unless
the supported 1.x line is selected. Windows dispatch keeps selectors and agent
action JSON in typed argv rather than shell tokenization.
On Windows, supplying --cdp-port makes the operator compile and use the
native .exe CDP adapter under .a3s-test/office-ops, which calls the pinned
standalone agent-browser driver directly with --cdp <port>. This keeps
selectors and action JSON out of .cmd argument parsing. It does not detach a
second connection daemon or poll a session port file, and it resolves after the
native process exits so completed ACL actions cannot be held open by inherited
stdio handles.
The Writer text-box contract also observes toolbar overflow and phone-surface
scrolling before semantic clicks; this is part of the tested user path rather
than a product-level focus workaround.
Run one primary ACL directly when narrowing a failure:
The Writer connector ACL also exercises the WPS-aligned line and arrow-style
controls: solid, dash, dot, and dash-dot values plus open and stealth endpoint
arrows are authored through the contextual ribbon, while the WPS fixture
verifies VML dashstyle and startarrow/endarrow import. The Windows COM
probe records DashStyle=4 and the bounded 3/4 arrow reference; it is evidence
for the mapping, not a CI prerequisite.
Exploratory sessions use the bounded A3S Test agent lifecycle:
start → observe → one act → observe → finish/abort. Use the typed action
schema and never reuse a ref after a state-changing action. Inspect the CUA
Driver/MCP lock before native GUI work:
The operator also provides typed agent subcommands for common actions, so a
Codex host does not need to hand-escape action JSON. Targets use
@e7, css=<selector>, role=<role>|<name>, label=<text>,
placeholder=<text>, testid=<id>, automation=<id>, or text=<text>:
Each wrapper dispatches exactly one A3S Test action. Observe again after every
state-changing action, and only use a3s agent act --action-json for an action
outside the typed wrapper set.
The locked CUA Driver 0.10.0 Windows profiles are currently unsupported
(there is no reviewed Windows application backend). The operator fails closed
for Windows CUA claims and uses A3S Test Web/CDP for browser-editor evidence;
a3s cua certify is reserved for a contract-tested platform and explicit CUA
policy/proxy configuration.
Use the narrower commands while diagnosing a failure:
Classify failures before changing product code. A loaded editor with a wrong semantic, focus, responsive, or diagnostic assertion is a product failure. A stale selector, fixture, or route is a test-contract failure. A missing preview, browser, CDP attachment, or unsupported locked CUA profile is an infrastructure classification.
On Windows, the bounded WPS COM reference is explicit and isolated from the product runtime:
For Writer field parity, the typed WPS probe captures the numeric field instructions emitted by the installed WPS build:
The probe records PAGE, NUMPAGES, SECTION, and PAGEREF with bounded
ROMAN, ALPHABETIC, Ordinal, hyperlink, and MERGEFORMAT switches. The
word-wps-numeric-fields.acl fixture then checks the same instructions through
the browser editor, including screenshot, accessibility, console, and page-error
evidence. Unknown switches remain cached and diagnosed rather than guessed.
Use --profile common to capture the same numeric baseline plus WPS DATE,
TIME, NUMWORDS, and NUMCHARS instructions for the field-settings workflow.
The word-field-settings.acl fixture covers typed authoring and editing in the
desktop and 390px compact ribbon; the COM probe remains a local reference and
never a CI prerequisite.
To review the real WPS Writer shell before changing a command or dialog, use the typed UI profile probe:
shell records the WPS window plus the Ribbon and status-bar shell;
fields adds the field, form-field, mail-merge, header/footer, and related
command bars with their native command IDs; all records the complete
CommandBars inventory. Each run owns one hidden WPS COM instance and closes it
explicitly. The JSON receipt is UI/UX reference evidence, not a browser-layout
assertion, product runtime dependency, or Windows CUA pass.
Record the exact DOCX output and WPS version, inspect it through A3S Office, and remove only exact temporary probe files after comparison. Do not use WPS COM as a CI prerequisite or treat COM properties as browser-layout proof.
Responsibilities
For every command and native mutation contract, use the complete CLI reference.