{"id":101484,"plugin_id":"plugins_6af4333b6f008191806d76e5f43ec5f9","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-17T12:11:36.158Z","digest":"6c76af4cb93cf8955e27da88113585ac2c041dacb55c2f56208438d982389532","against":null,"payload":{"description":"Create, edit, analyze, and read Excel spreadsheets (.xlsx, .xlsm, .csv) with XlsxWriter, openpyxl, and pandas. Use whenever the user wants a spreadsheet as output — a report, tracker, export, budget, or financial model — or uploads one to analyze, clean, reformat, or extend, even if they only say “sheet”, “Excel”, or “table”.","included_files":[],"name":"xlsx","skill_md_contents":"---\nname: xlsx\ndescription: Create, edit, analyze, and read Excel spreadsheets (.xlsx, .xlsm, .csv) with XlsxWriter, openpyxl, and pandas. Use whenever the user wants a spreadsheet as output — a report, tracker, export, budget, or financial model — or uploads one to analyze, clean, reformat, or extend, even if they only say “sheet”, “Excel”, or “table”.\nlicense: Apache-2.0\ncompatibility: Tines 3B\n---\n\n# Excel spreadsheets\n\nWork with spreadsheets in Python through `execute`, adding packages to a `requirements.txt` in `files`: `XlsxWriter==3.2.9` to create workbooks, `openpyxl==3.1.5` to read and edit them, and `pandas` for analysis. In a workflow step, add them to the step’s `requirements.txt` instead.\n\nUser uploads arrive under `/3b/uploads/<id>/<file>`, which every execution can read. Write output to a persistent volume, such as `volumes: [\"documents\"]` and `/storage/documents/budget.xlsx`, then call `showStorageFile` so the user can preview it with sheet tabs and download it. Never overwrite the user’s upload: save edits as a new file, and call `showStorageFile` again after each change.\n\n## Reading\n\nLook before you parse. Real workbooks have title rows above the header, merged cells, hidden sheets, notes below the data, and several tables on one sheet.\n\n```python\nfrom openpyxl import load_workbook\n\nwb = load_workbook(\"/3b/uploads/abc/vendors.xlsx\", data_only=True)\nfor ws in wb.worksheets:\n    print(f\"--- {ws.title} ({ws.sheet_state}) {ws.dimensions}, merged: {list(ws.merged_cells.ranges)[:5]}\")\n    for row in ws.iter_rows(max_row=8, values_only=True):\n        print(row)\n```\n\n`data_only=True` returns the results Excel last saved for formula cells, and `data_only=False` returns the formulas themselves. Once you know where the header row is, load the data with pandas for analysis: `pd.read_excel(path, sheet_name=\"Vendors\", header=2)`. Dates can arrive as Excel serial numbers and IDs as floats, so check `dtypes` before computing anything.\n\n## Formulas need saved results\n\nAn xlsx file stores each formula next to its last result. Excel, Google Sheets, and Numbers recalculate when they open a file, but the 3B preview, pandas, and `data_only=True` only read the saved result. A formula saved without one shows as blank there, and a chart over those cells draws nothing.\n\nSo write every formula with its result. Compute the value in Python from the same data, and pass it to XlsxWriter’s `write_formula` as `value=`, naming the argument because the positional slot before it is the cell format. Without it, XlsxWriter saves 0, and the preview shows zeros until someone opens the file in a spreadsheet app. Use formulas wherever a person may change inputs, such as totals, lookups, and model outputs, so the workbook stays live, and write plain values for figures nobody will edit.\n\n## Creating\n\nCreate new workbooks with XlsxWriter:\n\n```python\nimport datetime\nimport xlsxwriter\n\nvendors = [\n    (\"Okta\", \"Identity\", 42000, datetime.date(2026, 11, 15)),\n    (\"CrowdStrike\", \"Endpoint\", 88000, datetime.date(2027, 3, 31)),\n    (\"1Password\", \"Identity\", 18500, datetime.date(2026, 10, 31)),\n]\nlast = len(vendors) + 1\n\nwb = xlsxwriter.Workbook(\"/storage/documents/vendors.xlsx\")\nmoney = wb.add_format({\"num_format\": '\"$\"#,##0'})\ntotal_money = wb.add_format({\"num_format\": '\"$\"#,##0', \"bold\": True})\nbold = wb.add_format({\"bold\": True})\n\nws = wb.add_worksheet(\"Vendors\")\nws.add_table(0, 0, last - 1, 3, {\n    \"name\": \"Vendors\",\n    \"style\": \"Table Style Medium 2\",\n    \"columns\": [\n        {\"header\": \"Vendor\"},\n        {\"header\": \"Category\"},\n        {\"header\": \"Annual cost\", \"format\": money},\n        {\"header\": \"Renewal\", \"format\": wb.add_format({\"num_format\": \"yyyy-mm-dd\"})},\n    ],\n    \"data\": [list(vendor) for vendor in vendors],\n})\nws.set_column(\"A:B\", 18)\nws.set_column(\"C:D\", 14)\nws.freeze_panes(1, 0)\nws.write(last, 0, \"Total\", bold)\nws.write_formula(last, 2, f\"=SUM(C2:C{last})\", total_money, value=sum(v[2] for v in vendors))\n\nsummary = wb.add_worksheet(\"Summary\")\ncategories = sorted({v[1] for v in vendors})\nsummary.write_row(0, 0, [\"Category\", \"Annual cost\"], bold)\nfor row, category in enumerate(categories, start=1):\n    summary.write(row, 0, category)\n    summary.write_formula(\n        row, 1, f\"=SUMIF(Vendors!$B$2:$B${last},A{row + 1},Vendors!$C$2:$C${last})\",\n        money, value=sum(v[2] for v in vendors if v[1] == category),\n    )\nsummary.set_column(\"A:B\", 16)\n\nchart = wb.add_chart({\"type\": \"bar\"})\nchart.add_series({\n    \"name\": \"Annual cost\",\n    \"categories\": [\"Summary\", 1, 0, len(categories), 0],\n    \"values\": [\"Summary\", 1, 1, len(categories), 1],\n})\nchart.set_title({\"name\": \"Annual cost by category\"})\nchart.set_legend({\"none\": True})\nsummary.insert_chart(\"D2\", chart)\n\nwb.close()\n```\n\n- Rows and columns are zero-based in XlsxWriter calls, but formulas use Excel’s A1 references, so row index `r` is Excel row `r + 1`. Off-by-one references are the most common bug here.\n- Put each table on its own sheet, starting at A1, with one header row. Downstream tools and pandas handle that shape best.\n- Apply number formats instead of writing preformatted strings: `'\"$\"#,##0.00'` for currency, `\"0.0%\"` for percentages (stored as 0.125, not 12.5), and `\"yyyy-mm-dd\"` for dates (write `datetime` objects).\n- Set column widths, freeze the header row, and add a table or `autofilter` so the sheet is usable the moment it opens.\n- In a model, keep inputs on their own sheet or in a clearly marked block, give assumptions a label and unit, and reference cells rather than hard-coding numbers inside formulas.\n- For newer functions such as `XLOOKUP` and `FILTER`, open the workbook with `xlsxwriter.Workbook(path, {\"use_future_functions\": True})`, or Excel shows `#NAME?`.\n- Sheet names have at most 31 characters and can’t contain `[ ] : * ? / \\`.\n\nFor large datasets, write CSV, or write the data through `with pd.ExcelWriter(path, engine=\"xlsxwriter\") as writer:` and `df.to_excel(writer, sheet_name=\"Data\", index=False)`, then format the sheet through `writer.sheets[\"Data\"]`. Excel caps a sheet at 1,048,576 rows.\n\n## Editing an existing workbook\n\nXlsxWriter only creates files, so edit with openpyxl. Load with `load_workbook(path)`, keeping the default `data_only=False`, so formulas survive. Loading with `data_only=True` and saving replaces every formula with its last value.\n\nopenpyxl discards every saved formula result when it writes a file, so after an edit, all formula cells show blank in the 3B preview until someone opens and saves the workbook in a spreadsheet app. Tell the user about that. When the user mainly needs to view the result in 3B and the workbook is only values and formulas, read it with openpyxl and rebuild it with XlsxWriter instead. A rebuild keeps only what you copy across, so styles, conditional formatting, charts, images, and data validation are lost unless you recreate them: tell the user what it drops.\n\nopenpyxl also doesn’t round-trip everything: shapes, form controls, slicers, and some chart formatting are lost on save. Keep macros in an `.xlsm` with `load_workbook(path, keep_vba=True)` and save it under the `.xlsm` extension. Check what the workbook contains before editing, warn the user when something will be lost, and save under a new name.\n\nopenpyxl writes formulas exactly as given, so prefix newer functions yourself or Excel shows `#NAME?`. Most take `_xlfn.`, such as `=_xlfn.XLOOKUP(...)`, but worksheet-only array functions take `_xlfn._xlws.`, such as `=_xlfn._xlws.FILTER(...)` and `=_xlfn._xlws.SORT(...)`.\n\nWhen inserting rows or columns, remember that openpyxl doesn’t rewrite formulas, defined names, or chart ranges that point at the shifted cells. Append below the data, or update those references yourself.\n\n## Check the result\n\nReopen the saved file with `load_workbook(path, data_only=True)` and print each sheet’s dimensions, header row, and a few data rows. Any formula cell that reads as `None` or an unexpected 0 is missing its result. Then call `showStorageFile` so the user can see the sheets, and summarize what each sheet holds and which cells are formulas.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}