What is automating-excel?

A skill that automates Microsoft Excel on macOS using JXA with AppleScript dictionary discovery, focused on workbooks, worksheets, ranges, 2D arrays, performance toggles, and a VBA escape hatch.

Why is dictionary discovery important?

Dictionary discovery lets you map Excel's AppleScript terms to robust JXA commands, ensuring reliable control of Excel objects and operations.

How do I handle features not exposed in the dictionary?

Use the VBA escape hatch via Excel.run when necessary, and refer to the automating-mac-apps patterns for UI scripting guidance.

automating-excel

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

Files (1)

SKILL.md

3.1 KB

Automating Excel (JXA-first, AppleScript discovery)

Relationship to the macOS automation skill

Standalone for Excel, but aligned with automating-mac-apps patterns.
Use automating-mac-apps for permissions, shell, 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

Excel AppleScript dictionary is AppleScript-first; use Script Editor for discovery.
JXA is the production language for logic and data processing.
Collections are specifiers; read via methods, set via assignments.
Handle errors from Excel operations using try/catch blocks and Application error checking.

Workflow (default)

Discover dictionary terms in Script Editor (Excel).
Prototype a minimal AppleScript command.
Port to JXA and add defensive checks.
Use bulk read/write (2D arrays) for performance.
Use VBA run() when dictionary coverage is missing.

Validation Steps

Test with empty documents to verify error handling
Verify data integrity after batch operations
Check Excel UI responsiveness after automation runs
Log errors with specific Excel object paths for debugging

Examples

Basic workbook read:

const Excel = Application('Microsoft Excel');
const workbook = Excel.workbooks[0];
const worksheet = workbook.worksheets['Sheet1'];
const range = worksheet.ranges['A1:B10'];
const data = range.value();  // Returns 2D array

Bulk write with performance toggle:

Excel.screenUpdating = false;
Excel.calculation = 'manual';
try {
  const range = worksheet.ranges['C1:D100'];
  range.value = my2DArray;
} finally {
  Excel.calculate();
  Excel.screenUpdating = true;
}

VBA escape hatch:

Excel.run('MyMacro', {arg1: 'value', arg2: 123});  // Calls VBA subroutine

When Not to Use

For general macOS automation without Excel involvement
When AppleScript alone suffices (no JXA logic needed)
For Excel tasks requiring complex UI interactions (use automating-mac-apps for that)
When cross-platform compatibility is required

What to load

JXA Excel basics: automating-excel/references/excel-basics.md
Recipes (ranges, 2D arrays, formatting): automating-excel/references/excel-recipes.md
Advanced patterns (performance toggles, VBA bridge): automating-excel/references/excel-advanced.md
Pivot table guidance: automating-excel/references/excel-pivots.md
Charting guidance: automating-excel/references/excel-charts.md
Dictionary translation table: automating-excel/references/excel-dictionary.md
PyXA (Python) alternative: automating-excel/references/excel-pyxa.md

Source

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

View on GitHub

Overview

Automates Microsoft Excel on macOS using JXA with AppleScript dictionary discovery. It focuses on workbooks, worksheets, ranges, and 2D arrays, with performance toggles and a VBA escape hatch for gaps in dictionary coverage.

How This Skill Works

Start by discovering the Excel AppleScript dictionary in Script Editor, then implement the logic in JXA. Use collections/specifiers to access workbooks, worksheets, and ranges, and perform bulk read/write with 2D arrays for speed. Include defensive checks and try/catch error handling; if dictionary coverage is missing, fall back to VBA via run().

When to Use It

Automating Excel spreadsheets on macOS end-to-end
Scripting Excel with JXA and AppleScript dictionary discovery
Bulk Excel data operations requiring high performance (2D arrays)
Need a VBA bridge when dictionary terms are incomplete
Integrating Excel automation within broader macOS automation workflows

Quick Start

Step 1: Discover dictionary terms in Script Editor (Excel)
Step 2: Prototype a minimal AppleScript command for a target task
Step 3: Port to JXA and add defensive checks

Best Practices

Discover dictionary terms in Script Editor for Excel before coding
Prototype a minimal AppleScript command, then port to JXA with defensive checks
Use bulk read/write with 2D arrays to maximize performance
Toggle performance-related settings (screenUpdating, calculation) during bulk ops
Use VBA run() as a last-resort escape hatch when dictionary coverage is missing

Example Use Cases

Basic workbook read: load a 2D range into a JavaScript array via JXA
Bulk write with performance toggle: disable screenUpdating and set calculation to manual during write
VBA escape hatch: call a VBA macro using Excel.run to perform an unsupported operation
Error-handling pattern: wrap operations in try/catch and log precise Excel object paths
Dictionary-driven discovery: identify Excel dictionary terms with Script Editor to map AppleScript to JXA

Frequently Asked Questions

Add this skill to your agents