xlsx

name	xlsx
description	Produce, edit, or clean spreadsheets (.xlsx/.csv/.tsv) as real files — reconciliations, trackers, budgets, data cleanups, format conversions. Use whenever the deliverable is a spreadsheet or an existing one needs work, including messy tabular data that needs restructuring. Not for Word/PDF/deck outputs.

Spreadsheets with openpyxl

Write the workbook with execute_code using openpyxl, save into the fenced project folder (or configured output_dir), report the path. Plain .csv /.tsv work uses the stdlib csv module — don't drag a workbook library into a text-file job.

Creating

from openpyxl import Workbook
from openpyxl.styles import Font
from openpyxl.utils import get_column_letter

wb = Workbook()
ws = wb.active
ws.title = "Summary"
ws.append(["Item", "Owner", "Amount"])
for cell in ws[1]:
    cell.font = Font(bold=True)
for row in rows:
    ws.append(row)
ws.freeze_panes = "A2"
for i, _ in enumerate(ws[1], 1):
    ws.column_dimensions[get_column_letter(i)].width = 18
wb.save(path)

Formulas — the one big trap

openpyxl writes formula strings (ws["C10"] = "=SUM(C2:C9)") but never computes them, and reading a formula cell back gives the formula, not a value. So:

• If the operator will open the file in Excel: write formulas — they compute on open, and edits stay live.
• If a downstream step (or your verification) needs the values: compute in Python and write both, or write values only. Never report a total you didn't compute yourself.

Cleaning messy data

Read with load_workbook(src, read_only=True), normalize in Python (strip junk rows, promote the real header, coerce types), write a fresh workbook. Keep the original untouched; name the output <name>-clean.xlsx.

Verify before reporting

Re-open the saved file and spot-check: row count, a couple of cell values, a computed total. State the numbers you verified in the summary.

Save it as a versioned artifact

Once the file is written and verified, register it in the Artifact panel with save_file_artifact(path, title=…) when that tool is available (the artifact plugin, protoAgent v0.107.0+). It stores the bytes, shows a Download card with a readable preview (a sheet table), and keeps an edit history — pass the same artifact_id to save a later revision as v2/v3. Report the saved path and that it's in the panel. If the tool isn't available, just report the path.