document-xlsx

Document XLSX Skill - Quick Reference

This skill enables creation, editing, inspection, and safe distribution of .xlsx workbooks. Use it for report exports, spreadsheet models, spreadsheet QA, workbook automation, and Excel-compatible deliverables.

Modern best practices (July 2026):

• Prefer Excel Tables over loose ranges.
• Separate inputs, calculations, and outputs.
• Treat spreadsheets as software: checks, owners, change control, and review loops.
• Treat untrusted workbooks as hostile: formulas, hyperlinks, external links, hidden content, and macros all need review.
• If workbooks are shared externally, include accessibility hygiene and run Excel's Accessibility Checker.

Core Decision Rules (2026)

• First decide the runtime: local file generation, cloud workbook automation, or workbook audit/sanitization.
• Default to table-first exports: headers in row 1, frozen header row, autofilter, named table, bounded ranges.
• For native pivots: use Office Scripts or Excel automation; for headless exports prefer pre-computed summary tables.
• Libraries usually write formulas, but Excel calculates them when the file opens. If server-side computed values are required, calculate them in code and write values.
• XlsxWriter is write-only: it cannot open, read, or edit an existing .xlsx file. If the task is "edit this workbook" rather than "create a new one," reach for openpyxl (or ExcelJS in Node) instead — choosing XlsxWriter for an edit task is a common non-expert mistake that fails immediately.
• A formula written by openpyxl or XlsxWriter has no cached result until some calculation engine (Excel, LibreOffice headless, or a session-based tool such as xlwings) opens and recalculates the file. Reading that same file back with openpyxl(..., data_only=True) before any recalculation returns None, not the computed value — this looks like a bug but is expected behavior. If a downstream step (pandas, another script, an LLM) needs the number immediately, compute it in Python and write the literal value, or write both the formula and a plausible cached value only if you can guarantee it matches.
• ExcelJS is strong for workbook structure and styling, but it does not provide native chart generation; ExcelJS pivot-table support shipped as an experimental, limited feature only in recent 4.x releases — treat it as unstable and verify round-trip fidelity before relying on it in production.
• openpyxl can preserve VBA with keep_vba=True, but this skill does not author or execute macros.
• If ingesting untrusted workbooks with openpyxl, default to keep_links=False unless external links must be preserved.
• For very large exports (hundreds of thousands of rows or more), default openpyxl usage can balloon memory (a ~150MB source DataFrame has been observed using 2GB+ RAM with the default XML parser). Install lxml and use Workbook(write_only=True) for writing or load_workbook(read_only=True) for reading — both stream rather than build a full in-memory tree, and lxml alone materially cuts memory even outside those modes. Write-only workbooks can be saved exactly once; a second save() call raises WorkbookAlreadySaved, so batch all writes before saving.
• Row/column ceilings are fixed by the file format, not the library: 1,048,576 rows and 16,384 columns per worksheet. Exports approaching this need a pagination or multi-sheet strategy decided up front, not discovered at write time.