Can I use PyXA with this skill?

Yes. The skill includes PyXA examples and references PyXA as an alternative path, with guidance to install and run Python-based Word automation alongside the JXA approach.

Is this limited to Word on macOS?

Yes. It targets Microsoft Word on macOS, utilizing JXA and the Word AppleScript dictionary. For broader macOS automation, see the automating-mac-apps skill.

Which Word features are supported?

Supported features include documents, ranges, find/replace, tables, export, and ObjC bridge patterns, with guidance to load the reference materials and the dictionary translation table.

automating-word

npx machina-cli add skill SpillwaveSolutions/automating-mac-apps-plugin/automating-word --openclaw

Files (1)

SKILL.md

3.6 KB

Automating Word (JXA-first, AppleScript discovery)

Relationship to the macOS automation skill

Standalone for Word, aligned with automating-mac-apps patterns.
Use automating-mac-apps skill for permissions, shell execution, and UI scripting guidance.
PyXA Installation: To use PyXA examples in this skill, see the installation instructions in automating-mac-apps skill (PyXA Installation section).

Core framing

Word dictionary is AppleScript-first; discover there.
JXA provides logic, data handling, and ObjC bridge access.
Objects are specifiers; read via methods, write via assignments.
Handle errors from Word operations using try/catch blocks and Application error checking.

Implementation Workflow

Discover AppleScript Dictionary: Open Script Editor, browse Word's AppleScript dictionary to understand available objects and methods.
Translate to JXA: Use discovered AppleScript syntax as reference for JXA equivalents, consulting the dictionary translation table.
Set Up JXA Script: Initialize Word application object and document references.
Implement Operations: Apply find/replace, table manipulation, or export using JXA methods.
Test and Validate: Run script and verify document changes match expectations.

Quick Examples

Document opening:

// JXA
const word = Application('Microsoft Word');
word.documents.open('/path/to/document.docx');

# PyXA (Recommended)
import PyXA
word = PyXA.Word()
word.documents().open("/path/to/document.docx")

Find and replace:

// JXA
const range = word.activeDocument.content;
range.find.text = 'old text';
range.find.replacement.text = 'new text';
range.find.execute({replace: 'all'});

# PyXA
doc = word.active_document()
find_obj = doc.content().find()
find_obj.text = 'old text'
find_obj.replacement.text = 'new text'
find_obj.execute(replace='all')

Table creation:

// JXA
const table = word.activeDocument.tables.add(word.activeDocument.content, 3, 4);
table.cell(1, 1).range.text = 'Header';

# PyXA
table = doc.tables().add(doc.content(), 3, 4)
table.cell(1, 1).range().text = 'Header'

For PyObjC Scripting Bridge examples, see automating-word/references/word-pyxa.md.

Validation Checklist

After implementing Word automation:

Test script execution without errors
Verify document changes applied correctly
Check ObjC bridge objects return expected values
Run find/replace operations and confirm replacements
Export documents and validate output formats

When Not to Use

For general macOS automation (use automating-mac-apps)
For Excel automation (use automating-excel)
For non-Microsoft Office applications
For web-based document processing (use web APIs or Playwright)

What to load

Word JXA basics: automating-word/references/word-basics.md (core concepts only; see references for advanced usage)
Recipes (ranges, find/replace, tables): automating-word/references/word-recipes.md
Advanced patterns (export enums, ObjC bridge): automating-word/references/word-advanced.md
Dictionary translation table: automating-word/references/word-dictionary.md
PyXA (Python) alternative: automating-word/references/word-pyxa.md

Source

git clone https://github.com/SpillwaveSolutions/automating-mac-apps-plugin/blob/main/plugins/automating-mac-apps-plugin/skills/automating-word/SKILL.md

View on GitHub

Overview

Automates Microsoft Word on macOS using a JXA-first approach coupled with AppleScript dictionary discovery. It covers documents, ranges, find/replace, tables, export, and ObjC bridge patterns, translating AppleScript concepts into JavaScript for Word automation.

How This Skill Works

Start by opening Word's AppleScript dictionary to understand available objects and methods. Then translate those AppleScript references to JXA equivalents, initialize the Word application object and document references, and implement operations such as find/replace, table manipulation, or export. Errors are handled with try/catch blocks and Word-specific error checking to ensure reliable automation.

When to Use It

Automate Word documents in batch workflows (opening, editing, and saving multiple files).
Perform find and replace across documents or selections to standardize text.
Script Word using JXA for behavior driven by macOS automation routines.
Create new Word documents programmatically with predefined structures (text, tables, formatting).
Export Word documents to other formats (PDF, DOCX variants) as part of a pipeline.

Quick Start

Step 1: Discover AppleScript dictionary in Script Editor to identify Word objects and methods.
Step 2: Translate discovered AppleScript syntax to JXA equivalents and initialize Word.app references.
Step 3: Implement a small workflow (e.g., open document, perform find/replace, and export) and test carefully.

Best Practices

Always discover Word's AppleScript dictionary first from Script Editor to identify available objects and methods.
Use the dictionary translation table to map AppleScript terms to their JXA equivalents before coding.
Initialize Word and document references upfront to avoid runtime failures during operations.
Wrap operations in try/catch and validate results (especially find/replace and exports) for robust scripts.
Test scripts with representative documents and iterate on dictionary mappings and ObjC bridge usage.

Example Use Cases

Open a Word document via JXA and confirm it loads correctly before making edits.
Run a find/replace operation to update a template string across the active document.
Create a 3x4 table in the active document and populate header cells with labels.
Export the modified document to PDF and verify the output file is created.
Leverage ObjC bridge patterns to access lower-level Word properties when needed.

Frequently Asked Questions

Add this skill to your agents