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)

1. Discover dictionary terms in Script Editor (Excel).
2. Prototype a minimal AppleScript command.
3. Port to JXA and add defensive checks.
4. Use bulk read/write (2D arrays) for performance.
5. 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