| name | xlsx |
| description | Create and edit Excel .xlsx workbooks (sheets, cells, formulas, formatting) via Python `openpyxl`. Use to generate spreadsheets or write/update cells. Reading is via os.fs.read_document. |
| version | 1.0.1 |
| requires_tools | ["os.shell.run","os.fs.read_document"] |
| dangerous | false |
| platforms | ["darwin","linux"] |
xlsx
Create and modify .xlsx workbooks with the openpyxl Python library.
Reading an existing spreadsheet to plain text is best done with the built-in
os.fs.read_document tool (no install). Use the scripts below to write:
new workbooks, cell values, formulas, and basic formatting.
The pattern is python3 -c "<inline script>" (or python3 script.py for longer
logic). Keep scripts short and idempotent; always write to a fresh output path.
Setup health check (run first, every session)
Verify with one solo step:
[{ "tool": "os.shell.run", "args": { "cmd": "python3", "args": ["-c", "import openpyxl; print(openpyxl.__version__)"] } }]
Outcome map:
exit 0 + version → ready, proceed.ModuleNotFoundError: openpyxl → enter Setup playbook → "openpyxl missing".command not found: python3 → reply that Python 3 is required and stop.
Setup playbook (when prerequisites are missing)
openpyxl missing
Reply (solo reply step):
"The openpyxl library is not installed. I can install it: python3 -m pip install --user openpyxl. Install it?"
On yes:
[{ "tool": "os.shell.run", "args": { "cmd": "python3", "args": ["-m", "pip", "install", "--user", "openpyxl"] } }]
If pip is externally managed (PEP 668), use pipx run --spec openpyxl python or
a venv; ask the user which they prefer.
When to use
- "Create an Excel file with these rows", "build a budget spreadsheet".
- "Add a column / formula", "update cell B2", "add a second sheet".
- Generating reports/exports as
.xlsx.
When NOT to use
- Reading an
.xlsx to summarise — use os.fs.read_document.
- CSV-only work — prefer plain
os.fs.write with comma-separated text.
- Charts / pivot tables / macros — out of scope on v1.
Common operations
Create a workbook with a header row and two data rows:
[{ "tool": "os.shell.run", "args": { "cmd": "python3", "args": ["-c", "import openpyxl; wb=openpyxl.Workbook(); ws=wb.active; ws.title='Report'; ws.append(['Name','Amount']); ws.append(['Coffee',4.5]); ws.append(['Tea',3]); ws['B4']='=SUM(B2:B3)'; wb.save('report.xlsx'); print('wrote report.xlsx')"] } }]
Append rows to an existing workbook:
[{ "tool": "os.shell.run", "args": { "cmd": "python3", "args": ["-c", "import openpyxl; wb=openpyxl.load_workbook('report.xlsx'); ws=wb.active; ws.append(['Juice',5]); wb.save('report.xlsx'); print('appended')"] } }]
For anything longer than a couple of statements, write a .py file with
os.fs.write first, then run it with python3 script.py.
Rules
- Always
wb.save(<new path>) and report the path; never silently overwrite.
- Formulas go in as strings starting with
= (e.g. '=SUM(A1:A9)').
- Quote numbers as numbers, not strings, so Excel treats them numerically.
- For reads, defer to
os.fs.read_document — do not reinvent parsing.
