enkly-ai/pkg/skillkit/skills/xlsx.md

xlsx — Excel workbooks

Best practices for create_spreadsheet / read_spreadsheet / edit_spreadsheet: sheets, cell values, and sparse edits.

Content model

A workbook is one or more sheets, each a row-major grid of plain-text cell values. Row 1 is the top row, column A is the leftmost column — the grid you pass is literally what lands in the file, top-to-bottom, left-to-right. Each value is classified the same way on both create_spreadsheet and edit_spreadsheet:

• Starts with = (e.g. "=SUM(A1:A4)", "=B2*C2") → stored as a live Excel formula, same as typing it into a cell in Excel. Excel computes and displays the result when the file is opened; this tool never evaluates formulas itself, so read_spreadsheet right after writing one shows the formula text (prefixed =), not a computed number — that's expected, not a bug.
• Otherwise parses as a plain number ("92", "3.5", "-1") → stored as a numeric cell.
• Anything else, including something that merely looks numeric-ish like "$92" or "92%", is stored as text.

If you want a literal computed total rather than a live formula (e.g. because the person asked for a static report, not a workbook they'll keep editing), compute it yourself — with solve_ml_math for anything nontrivial — and write the plain number instead of a formula string.

Single sheet vs. multiple sheets

create_spreadsheet has two forms:

• Single sheet: rows (+ optional sheet_name, defaults to "Sheet1").
• Multiple sheets: sheets, an array of {name, rows} — one entry per tab, in the order they should appear. Use this whenever the request implies more than one tab ("a workbook with a summary sheet and a detail sheet", "separate sheets per quarter") — don't flatten multi-sheet data onto one sheet with a column that says which sheet it "would" be.

Pick one form, not both, in a single create_spreadsheet call.

Reading and editing a specific sheet

read_spreadsheet and edit_spreadsheet both take an optional sheet field: a 1-based index ("2") or a sheet name (case-insensitive). Omitting it means the first sheet. When a workbook has more than one sheet, read_spreadsheet's result starts with a line naming which sheet you got and listing every sheet's name — read that line before assuming you're looking at the sheet you meant, especially on a user-uploaded file whose sheet order you don't already know.

edit_spreadsheet writes a sparse set of cells by A1-style reference (e.g. "B12") to one sheet; every other cell on that sheet is left exactly as it was, and a reference past the current grid extends it rather than erroring. There's no "edit multiple sheets in one call" — make one edit_spreadsheet call per sheet that needs a change.

Always read_spreadsheet first if you're not sure what's already in a sheet or what the other sheets are called, the same way you'd read_file before edit_file.

Limitations (so you don't promise more than the tool does)

• No cell formatting (bold, colors, borders, column widths, number formats like currency or percentages).
• No charts.
• No sheet deletion or reordering, and no renaming a sheet after creation.
• read_spreadsheet returns display strings only — no distinction between a cell's underlying value and how Excel would format it. For a formula cell, it shows Excel's own cached result when one exists (always true for a real Excel-authored or user-uploaded file), or the formula text itself (prefixed =) when nothing has computed it yet (always true immediately after this tool writes one).

If someone explicitly asks for formatting or a chart, say plainly that today's tool doesn't support it rather than quietly writing a plain, unformatted workbook and calling it done.