document-skills-xlsx

name	document-skills-xlsx
description	Read, edit, create, or fix spreadsheet files - .xlsx, .xlsm, .xltx, .csv, .tsv. Use this Skill whenever a spreadsheet is the primary input or output: opening and inspecting workbooks, editing cells or adding sheets, writing real formulas instead of pasted values, cleaning messy data, adding charts and formatting, converting between tabular formats, or diagnosing corrupted or slow-opening files.

XLSX workbench

Spreadsheets are where agents do the most damage by being clever: pasted values where formulas belong, dates written as text, whole-number floats displayed as 3.0000000001. Follow the contracts below.

Step 0 - Check the toolchain

python -c "import defusedxml, openpyxl; print(openpyxl.__version__, defusedxml.__version__)"

• .csv/.tsv -> standard library csv module is fine and often better (streaming).
• .xlsx/.xlsm/.xltx -> openpyxl.
• Safe package preflight requires defusedxml==0.7.1; do not fall back to the standard XML parser for untrusted OOXML parts.
• Macro preservation: openpyxl keeps VBA in .xlsm only with keep_vba=True on load and save.
• Before any openpyxl.load_workbook() of an existing package, copy and use the bounded same-handle loader in references/package.md. read_only=True does not bound shared strings, styles, or other package parts parsed during initialization.

Step 1 - Classify the task

Request	Route
Open, inspect, profile a workbook	references/read.md
Edit cells, add sheets, fix formatting	references/edit.md
Build a new workbook (data + formulas + chart)	references/create.md
CSV/TSV in or out, messy data cleanup	references/csv.md
Conditional formatting, structured tables, pivot-style aggregation	references/formatting.md
Safely open an existing OOXML package	references/package.md

Step 2 - Contracts that always apply

1. Formulas are formulas. If the user asks for a total/average/lookup, write =SUM(B2:B10) in the cell - never the computed number - unless the user explicitly asked to freeze values. openpyxl writes the formula; Excel/WPS/LibreOffice calculate on open.
2. data_only=True reads cached values (last calculated by a real app) and loses formulas on save. Use it only for reading values; never load, edit, and save with it.
3. Types: write int/float/datetime/bool, never formatted strings. Dates go in as datetime with number_format='yyyy-mm-dd'; currency as float plus number_format='#,##0.00' (or the locale-appropriate currency format string).
4. Formulas are not recalculated by openpyxl. After writing formulas, set wb.calculation.fullCalcOnLoad = True before saving so Excel/WPS/LibreOffice recalculate on open even when the workbook (typically one you loaded, which can carry fullCalcOnLoad=False) uses calculation mode manual - check wb.calculation.calcMode. You still cannot read results back without opening the file in a real spreadsheet app; verify formula strings and ranges structurally instead (see postcheck).
5. Dimensions: treat <dimension>, ws.max_row, and ws.max_column as untrusted hints. Discover logical cells with the sparse worksheet-XML scan in the read route; never expand an unknown rectangular range merely to find its bounds.
6. Save to a new path first; overwrite only on explicit request.

Step 3 - Postcheck (mandatory)

Save this as postcheck.py, copy load_validated_workbook() and its dependencies from references/package.md, then pass the output path followed by every sheet the task should produce, for example python postcheck.py output.xlsx Sales Summary:

import openpyxl
import sys

if len(sys.argv) < 3:
    raise SystemExit("usage: python postcheck.py OUTPUT.xlsx EXPECTED_SHEET [...]")
output_path, *expected_sheets = sys.argv[1:]
# Populate this whenever the task requested specific display formats.
expected_number_formats = {
    # "Sales": {"D2": "#,##0.00", "E2": "yyyy-mm-dd"},
}
# Populate every formula the task intends to create or preserve.
expected_formulas = {
    # "Sales": {"D2": "=C2*1.08"},
}
# Populate every expected sheet with the exact used range required by the task.
expected_dimensions = {
    # "Sales": "A1:E20",
    # "Summary": "A1:C8",
}
wb = load_validated_workbook(output_path)

def require(condition, message):
    if not condition:
        raise ValueError(message)

def formula_text(value):
    if isinstance(value, str):
        return value
    if text := getattr(value, "text", None):
        return text
    fields = ("ref", "r1", "r2", "dt2D", "dtr", "ca", "del1", "del2")
    details = ", ".join(
        f"{name}={getattr(value, name)!r}" for name in fields if hasattr(value, name)
    )
    return f"{type(value).__name__}({details})"

print("sheets:", wb.sheetnames)
missing = set(expected_sheets) - set(wb.sheetnames)
require(not missing, f"missing expected sheets: {sorted(missing)}")
require(
    set(expected_dimensions) == set(expected_sheets),
    "expected_dimensions must declare the exact used range for every expected sheet",
)
calc = wb.calculation
print("calcMode:", getattr(calc, "calcMode", None),
      "fullCalcOnLoad:", getattr(calc, "fullCalcOnLoad", None))
if any(expected_formulas.values()):
    require(
        getattr(calc, "fullCalcOnLoad", False) is True
        or getattr(calc, "calcMode", None) == "auto",
        "formula output is not configured to recalculate in spreadsheet viewers",
    )
for ws in wb.worksheets:
    print(f"{ws.title} dims:", ws.dimensions)
    if ws.title in expected_dimensions:
        require(
            ws.dimensions == expected_dimensions[ws.title],
            f"{ws.title}: expected used range {expected_dimensions[ws.title]!r}, "
            f"got {ws.dimensions!r}",
        )
    # `expected_formulas` is the task contract, so verify those coordinates directly.
    # Never call unbounded iter_rows(): one styled extreme cell can make the rectangle huge.
    actual_formulas = {}
    for coordinate, expected_formula in expected_formulas.get(ws.title, {}).items():
        cell = ws[coordinate]
        actual_formula = formula_text(cell.value) if cell.data_type == "f" else None
        actual_formulas[coordinate] = actual_formula
        require(
            actual_formula == expected_formula,
            f"{ws.title}!{coordinate}: expected formula {expected_formula!r}, "
            f"got {actual_formula!r}",
        )
    print(f"{ws.title} expected formula cells:", list(actual_formulas.items())[:10])
    for coordinate, expected_format in expected_number_formats.get(ws.title, {}).items():
        actual_format = ws[coordinate].number_format
        require(actual_format == expected_format, (
            f"{ws.title}!{coordinate}: expected format {expected_format!r}, got {actual_format!r}"
        ))
wb.close()

Confirm: expected sheet names exist; used range matches expectations; intended formula cells contain formula strings; when the task wrote formulas, the printout shows fullCalcOnLoad: True (or calcMode: auto) so viewers will recalculate — otherwise set it and re-save; every task-specific formatted cell is listed in expected_number_formats and matches. Report what was verified and note that final rendered values require opening in a spreadsheet application.