xlsx

Spreadsheet workflows

Keep workbook artifacts under /home/qubicl. Obtain this skill's resourceRoot from skill_view and run its helpers with /opt/qubicl/skills-venv/bin/python. The computer and workstation presets contain the pinned spreadsheet libraries; do not install packages during a task.

Useful helpers beneath <resourceRoot>/scripts/:

• xlsx_read.py FILE --sheets|--json|--cells|--csv|--formulas|--notes|--names
• xlsx_create.py SPEC.json OUTPUT.xlsx
• xlsx_edit.py FILE for values, rows, sheets, tables, names, links, notes, and protection
• xlsx_restructure.py FILE for reference-aware row or column changes
• csv_to_xlsx.py INPUT.csv OUTPUT.xlsx
• xlsx_to_csv.py INPUT.xlsx OUTPUT.csv
• xlsx_recalc.py FILE when LibreOffice is available

Read references/restructuring.md before inserting or deleting rows or columns in a formula-heavy workbook.

Inspect workbook structure and formulas before editing. Preserve formulas unless replacement is intentional, use a new output for risky transformations, and read the result back afterward. LibreOffice recalculation is available only on workstation computers; explain that limitation rather than manufacturing cached formula values.

xlsx_read.py --formulas includes normal, array and what-if data-table formulas. Typed entries include formula_type and their result ref; array entries include the expression in formula, while data-table entries include all input references and flags in attributes. JSON/CSV sheet dumps represent typed formulas as JSON objects rather than Python object names; standalone xlsx_to_csv.py uses the same typed-formula and duration serialization. Elapsed-time values such as [h]:mm use signed ISO 8601 durations (P1DT3H15M for 27 hours 15 minutes), preserving days and fractional seconds. Dates and times retain their ISO date/time format.

For a typed client-facing read, use --cells (active sheet by default, or --sheet NAME). Each stored cell includes its coordinate, normalized value, type, original OOXML rawValue/storageType, numberFormat, and formula metadata with its result range. rawValue is storage data, including shared-string indexes, not display text. Both --cells and --formulas explicitly report cachedValueAvailable, cacheStatus and per-cell missing-cache warnings; a present empty-string, zero or error result remains distinct from a missing cache. The reader never recalculates or invents display values. Use the existing render workflow on a copy when appearance matters; recalculated render results do not establish that the original file contained those caches. Literal strings starting with = remain text and are not listed as formulas.

Use the common rendering receipt for PDF, DOCX, XLSX and PPTX: /opt/qubicl/skills-venv/bin/python /opt/qubicl/artifact-render.py FILE --outdir DIR. Each invocation captures its source, uses an isolated Office profile, and writes a unique run directory with PDF, exact numbered PNGs and manifest.json. Read sourceSha256, pages, warnings and validation, then inspect the generated pages. Old previews are never returned as this run's outputs. visuallyInspected: false is intentional: the tool renders; the agent performs visual review. Office rendering needs workstation.

Rendering and xlsx_recalc.py report formula errors, missing cached results and changed OOXML package parts. recalculated: true does not mean error-free, correct formulas, or perfect Excel fidelity. Preserve the source and review formulas, formats, charts, print areas and the rendered pages before delivering converted workbooks.

CSV imports preserve leading-zero/long identifiers and mixed-type columns; strings beginning with = stay literal by default, including headers. Default UTF-8 decoding accepts an initial BOM and preserves noninitial U+FEFF characters. Use --column-types '{"A":"text","B":"number"}' for deliberate types or --allow-formulas only when formulas are intended. Explicit typed empty cells become blanks; --empty-cells reject requires nonempty typed values. Numeric overflow/nonfinite values and invalid typed conversions fail with CSV row, column and cell context before saving. Imports preflight Excel's 1,048,576-row, 16,384-column, 32,767-character cell and 8,192-character formula limits; oversized input fails instead of silently truncating. The saved archive is reopened to verify dimensions and text/formulas before atomically replacing the destination, so a failed conversion preserves an existing output. Review the conversion report. xlsx_to_csv.py --data-only refuses missing formula caches before writing; --allow-missing-results explicitly permits them and reports affected cells. Restructuring supports native table column insertion/deletion, unique generated headers, calculated/totals formulas, filter criteria and sort ranges. It updates structured references throughout the workbook; deleted columns/tables become #REF!, while partially deleted column ranges retain surviving endpoints. Inserted table rows receive calculated-column formulas, and removing a header preserves the surviving data as a headerless table. Read the JSON transformation report and inspect the saved workbook.