Excel & Spreadsheet Builder

Spreadsheet Skill (Create, Edit, Analyze, Visualize)

When to use

• Build new workbooks with formulas, formatting, and structured layouts.
• Read or analyze tabular data (filter, aggregate, pivot, compute metrics).
• Modify existing workbooks without breaking formulas or references.
• Visualize data with charts/tables and sensible formatting.

IMPORTANT: System and user instructions always take precedence.

How the file actually reaches the user

You BUILD the workbook in the sandbox and DELIVER it with export_file. A file written to the working directory and never exported does not reach the user at all — they see your description and no download. Never end a build turn without export_file.

Any spreadsheet the user uploaded in this conversation is already staged in the sandbox working directory under its (sanitized) filename: characters outside A-Za-z0-9._- become _. List the directory if unsure:

import os; print(sorted(os.listdir(".")))

The sandbox has NO internet and no sudo: never try pip install, uv pip install, brew install or apt-get install. Everything below is pre-baked — openpyxl, pandas, pyarrow, matplotlib, LibreOffice (soffice), poppler-utils (pdftoppm), pymupdf (fitz). An install attempt is a guaranteed failure that also burns one of the turn's limited tool calls, which can push export_file past the budget and cost the user the file.

On export, the house visual post-pass (zeplik-xlsx) is applied to every .xlsx automatically — header paint, banded rows, inferred number formats, column widths, freeze panes. It never touches your values or formulas, so build for correctness and let the post-pass own the styling.

Workflow

1. Confirm the file type and goals (create, edit, analyze, visualize).
2. Use openpyxl for .xlsx edits and pandas for analysis and CSV/TSV workflows.
3. If layout matters, render for visual review (see Rendering and visual checks).
4. Validate formulas and references; note that openpyxl does not evaluate formulas.
5. Re-open the saved file and assert it is intact (sheet names, row count, a spot value) — print the evidence.
6. export_file the workbook, then tell the user in one short line that it is ready. Do not restate the whole table as text.

Temp and output conventions

• Write the deliverable into the working directory with a stable, descriptive filename; that is the path you pass to export_file.
• Keep intermediate files out of the way (a tmp/ subfolder) and never export them.

Primary tooling

• Use openpyxl for creating/editing .xlsx files and preserving formatting.
• Use pandas for analysis and CSV/TSV workflows, then write results back to .xlsx or .csv.
• If you need charts, prefer openpyxl.chart for native Excel charts.

Rendering and visual checks

LibreOffice and Poppler are both pre-baked, so a visual check is always available — do it whenever layout matters:

soffice --headless --convert-to pdf --outdir out book.xlsx
pdftoppm -png out/book.pdf out/page

Look at the PNG: headers distinct, no text spilling between cells, numbers formatted, nothing clipped. Fix and re-render rather than shipping unseen. Never ask the user to review the output locally — they have no copy until you export it.

Environment

No required environment variables.

Examples

• Runnable Codex examples (openpyxl): references/examples/openpyxl/

Formula requirements

• Use formulas for derived values rather than hardcoding results.
• Keep formulas simple and legible; use helper cells for complex logic.
• Avoid volatile functions like INDIRECT and OFFSET unless required.
• Prefer cell references over magic numbers (e.g., =H6*(1+$B$3) not =H6*1.04).
• Guard against errors (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?) with validation and checks.
• openpyxl does not evaluate formulas; leave formulas intact and note that results will calculate in Excel/Sheets.

Citation requirements

• Cite sources inside the spreadsheet using plain text URLs.
• For financial models, cite sources of inputs in cell comments.
• For tabular data sourced from the web, include a Source column with URLs.

Formatting requirements (existing formatted spreadsheets)

• Render and inspect a provided spreadsheet before modifying it when possible.
• Preserve existing formatting and style exactly.
• Match styles for any newly filled cells that were previously blank.

Formatting requirements (new or unstyled spreadsheets)

• Use appropriate number and date formats (dates as dates, currency with symbols, percentages with sensible precision).
• Use a clean visual layout: headers distinct from data, consistent spacing, and readable column widths.
• Avoid borders around every cell; use whitespace and selective borders to structure sections.
• Ensure text does not spill into adjacent cells.

Color conventions (if no style guidance)

• Blue: user input
• Black: formulas/derived values
• Green: linked/imported values
• Gray: static constants
• Orange: review/caution
• Light red: error/flag
• Purple: control/logic
• Teal: visualization anchors (key KPIs or chart drivers)

Finance-specific requirements

• Format zeros as "-".
• Negative numbers should be red and in parentheses.
• Always specify units in headers (e.g., "Revenue ($mm)").
• Cite sources for all raw inputs in cell comments.

Investment banking layouts

If the spreadsheet is an IB-style model (LBO, DCF, 3-statement, valuation):

• Totals should sum the range directly above.
• Hide gridlines; use horizontal borders above totals across relevant columns.
• Section headers should be merged cells with dark fill and white text.
• Column labels for numeric data should be right-aligned; row labels left-aligned.
• Indent submetrics under their parent line items.

Zeplik output presentation

Present the final deliverable as a single polished artifact: clear headings, tables where the content is tabular, fenced code where it is code. Lead with the deliverable itself; keep process commentary to a single short line. If the skill produced multiple files or sections, end with a compact list of them with one-line purposes.