xlsx

Fires when

• ▸user has an .xlsx/.xlsm/.csv/.tsv file they want read, edited, or fixed
• ▸user wants to build a financial model with industry-standard color coding (blue input, black formula, green cross-sheet, red external, yellow assumption)
• ▸user wants to convert messy tabular data into a proper spreadsheet
• ▸user wants formulas computed (SUMIFS, SUMPRODUCT, growth rates) instead of Python-side hardcoded values
• ▸user references a spreadsheet by name or path in passing and wants something done to it

Skip when

• ✕user wants the deliverable as a Word doc, HTML report, or Google Sheets API call
• ✕user is on a system without LibreOffice and cannot install it (recalc.py is unusable, formulas stay un-evaluated)
• ✕user needs human-text commentary containing strings like "#N/A" or "#DIV/0!" in cells (recalc.py's scanner will misreport them as errors)
• ✕user expects working examples to ship as runnable .py files (only inline snippets ship; no requirements.txt)

Takes

• file:xlsx any .xlsx/.xlsm; .csv/.tsv supported via pandas
• structured-data:pandas DataFrame for fresh-build workflows, an in-memory DataFrame is the typical seed

Returns

• file:xlsx formulas, formatting, multi-sheet structure preserved by openpyxl write; cached values remain None until recalc.py succeeds
• structured-data:JSON error report (from scripts/recalc.py) only produced when LibreOffice is available; scanner uses substring match so plain-text cells containing error tokens are false-flagged

Install

pip install openpyxl pandas

• macos: brew install --cask libreoffice (REQUIRED for scripts/recalc.py to evaluate any formula)
• linux: apt-get install libreoffice (or equivalent — required for recalc.py)

No requirements.txt or pyproject.toml ships with the skill folder; deps must be read off SKILL.md prose. recalc.py imports from a sibling 'office' package (scripts/office/) and must be run from the scripts/ parent dir or with PYTHONPATH set. The script does not handle FileNotFoundError on soffice — it crashes with a raw traceback instead of returning the documented JSON contract.

Caveats

• scripts/recalc.py hard-crashes with an unhandled FileNotFoundError if soffice is missing — it does NOT emit the documented JSON error contract, breaking any caller that parses stdout as JSON
• recalc.py error scanner uses substring match (`if err in cell.value`) — any cell whose text mentions "#N/A", "#DIV/0!", "#REF!" etc. as plain commentary is silently flagged as a formula error, sending the SKILL.md verify-and-fix loop on a wild goose chase
• openpyxl-written formulas have no cached value, so a downstream consumer that opens the file with `data_only=True` sees `None` for every formula cell until LibreOffice has touched the file at least once — the workbook looks "empty" in any read-only pipeline
• opening with data_only=True and saving silently strips all formulas (SKILL.md mentions this in Best Practices but it is one bullet buried far from the workflow section — agents reading top-down often miss it)
• no requirements.txt or runnable example files ship; the SKILL.md inline snippets are copy-paste, not importable, and the scripts/ folder contains only recalc.py + office/ helpers (no end-to-end build example)
• recalc.py relies on installing a LibreOffice user-level macro on first run — sandboxed CI without ~/Library or ~/.config write access will silently fail at setup_libreoffice_macro()