SKILL.md 全文

Frontmatter

name	xlsx
description	"Use this skill any time a spreadsheet file is the primary input, output, or required supporting data source. This includes opening, reading, extracting, analyzing, editing, repairing, creating, formatting, charting, or converting .xlsx, .xlsm, .xltx, .xltm, .xls, .csv, or .tsv files; cleaning messy tabular data; or turning spreadsheet contents into structured JSON/CSV for another primary artifact workflow. Trigger especially when the user references a spreadsheet file by name or path. If another skill owns the final deliverable, use xlsx only for spreadsheet extraction/analysis/repair and hand the structured result back to that workflow."
license	Proprietary. LICENSE.txt has complete terms

XLSX creation, editing, and analysis

| Task | Approach | |---|---| | Fast inspect/extract workbook data | python scripts/extract_workbook.py file.xlsx --mode inspect or --mode extract | | Create or edit with formulas/formatting | openpyxl — see gotchas below | | Bulk data in or out | pandas (read_excel, to_excel) | | Quick look at a sheet | markitdown file.xlsx — ## SheetName per sheet; reads .xlsm too. No cell coordinates, so don't plan edits from it | | Read a model (formulas and values) | two load_workbook passes — see gotchas |

openpyxl, pandas, and markitdown are preinstalled — do not run pip install first; write the script and import directly. Only if an import fails (or the markitdown command is missing): pip install the missing package.

Script paths below are relative to this skill's directory.

Fast extraction path

For reading, summarizing, filtering, routing, or passing spreadsheet data to another workflow, start with:

python scripts/extract_workbook.py input.xlsx --mode inspect
python scripts/extract_workbook.py input.xlsx --mode extract --sheet "Sheet1" --max-rows 5000
python scripts/extract_workbook.py input.xlsx --mode model --include-formulas

The script outputs JSON with workbook metadata, sheet dimensions, header candidates, sample rows, merged ranges, hidden rows/columns, optional rows, and optional formula cells with cached values. It supports .xlsx, .xlsm, .xltx, .xltm, .xls, .csv, and .tsv. It tries openpyxl first, repairs empty xl/styles.xml fills once, and falls back to LibreOffice conversion for legacy or problem files. Do not spend multiple turns debugging openpyxl parser internals before using this script. Use --mode inspect for a quick overview, --mode extract for row data, and --mode model when formula strings and cached values matter. Use --sheet repeatedly for targeted extraction after the first inspect pass.

Parallelism

Parallelize independent spreadsheet reads and inspections. This is mandatory for non-trivial tasks.

• If the user provides multiple spreadsheets, run extract_workbook.py --mode inspect for them in parallel.
• If the final deliverable belongs to another skill, extract spreadsheet data in parallel with the other skill's independent source/template inspections.
• After the first inspect pass, extract independent target sheets or independent source files in parallel.
• Do not parallelize writes, in-place edits, recalc.py, or two commands that mutate the same workbook.
• Avoid the slow pattern "read one sheet, think, read another sheet, think" unless the first result is required to choose the second command.

Requirements for every output

• Professional font (Arial, Times New Roman) throughout, unless the user says otherwise.
• Zero formula errors. Never ship while recalc.py reports errors_found. If you think an error predates you, prove it: load the original with data_only=True and look at that cell. An error you introduced looks exactly like one you inherited.
• Use formulas, never hardcoded results. Write sheet['B10'] = '=SUM(B2:B9)', not the Python-computed total. The sheet must recalculate when its inputs change.
• Follow the user's spec literally. Exact tab names, exact column headers, and the formula they spelled out. A redesign that computes something else fails, however elegant.
• Document every assumption and hardcoded number where the reader will see it — a cell comment, or an adjacent cell at a table's end. Cite a real source when one exists (Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]); when the number came from the user, say so plainly.
• **A workbook you create for someone to fill in** needs a short legend naming which cells to edit, and one example row of realistic values showing the expected format. Never add such a row to a file you were asked to edit.
• Editing an existing file: match its conventions exactly. They override every guideline here. Find its designated input cells first — a distinct font color, fill, or shading marks them — write only there, and leave every existing formula untouched.

Recalculate (mandatory whenever the file contains formulas)

openpyxl writes formulas as strings with no cached values. Until you recalculate, every formula cell reads back as None to anything reading cached values — pandas, load_workbook(data_only=True), and most previewers.

python scripts/recalc.py output.xlsx [timeout_seconds]   # default 30

LibreOffice computes every formula, the file is rewritten in place, and you get JSON: status (success | errors_found), total_formulas, total_errors, and an error_summary naming up to 100 cells per error type (locations_truncated says how many it withheld — trust total_errors, not the length of the list). Fix what it names and run it again. JSON with an error key instead of a status means nothing was recalculated, and only that case exits non-zero — errors_found exits 0, so never treat a clean exit as a clean workbook. **A green recalc proves your formulas evaluate, not that they are right.** An off-by-one range or a reference to the wrong row yields a clean, error-free file with wrong numbers. Write 2–3 formulas first and check they pull the values you expect, before building out a grid. A workbook that links to another file loses those links if you re-save it with openpyxl and then recalculate. Such a formula reads ='[1]Returns Analysis'!$B$2 — the [1] is an index into the workbook's external-reference list, naming a separate file on disk, not a sheet. That file is rarely present here, so the cell's cached value is the only thing holding its data. openpyxl strips that value on save; LibreOffice then has to resolve the reference for real, fails, writes #NAME?, and deletes every link. recalc.py refuses to run in that state — copy those cells' values out of the original before you save over them (--force overrides, and accepts the loss).

Choosing formulas that survive verification

LibreOffice implements fewer functions than Excel, and one it cannot evaluate becomes a literal #NAME? baked into the file you deliver.

• Prefer Excel-2007-era functions — SUMIFS, INDEX, MATCH, IFERROR, SUMPRODUCT — which need no prefix.
• Six post-2007 functions work, but only with an _xlfn. prefix, because openpyxl writes your formula into the XML verbatim and Excel stores post-2007 names prefixed (its UI hides the prefix): _xlfn.TEXTJOIN, _xlfn.CONCAT, _xlfn.IFS, _xlfn.SWITCH, _xlfn.MAXIFS, _xlfn.MINIFS. Written bare, each yields #NAME?.
• Never use XLOOKUP, XMATCH, SORT, FILTER, UNIQUE, or SEQUENCE. The runtime's LibreOffice cannot evaluate them under any prefix. Newer builds do evaluate them, but they are spilling array functions and an openpyxl-written file has no spill metadata, so only the top-left cell of the range gets a value — and recalc.py reports total_errors: 0 on the truncated result. Use INDEX/MATCH for lookups, and sort, filter, and de-duplicate in Python before writing the cells.
• A formula LibreOffice could not parse is written back lowercased — a quick tell beside a #NAME?.

openpyxl gotchas

• Parser/style failures: if openpyxl or pandas.read_excel fails with style XML errors such as Fill() takes no arguments, stop hand-debugging and use scripts/extract_workbook.py; it repairs empty fills once and then tries LibreOffice conversion.
• Reading a model takes two loads. data_only=True yields cached values with the formulas gone; the default yields formula strings with no values. One pass cannot give you both.
• data_only=True is destructive if you save. That workbook has no formulas left, so saving replaces every one with a literal — permanently.
• data_only=True on a file openpyxl just wrote returns None everywhere — run recalc.py first. (A formula whose result is "" also reads back as None.)
• Merged cells: read/write the top-left anchor only. Every other cell in the range is a MergedCell; do not call attributes such as .column_letter on it. Use get_column_letter(cell.column) on normal cells, or use the merged ranges returned by extract_workbook.py.
• .xlsm loses its macros unless you pass keep_vba=True to load_workbook.
• A sheet name containing a space must be quoted in a cross-sheet reference: ='Assumptions Inputs'!$B$5. Unquoted, it evaluates to #VALUE!.
• markitdown is content-only. It is useful for quick human-readable sheet text, but it has no stable cell coordinates and should not drive edits.
• Legacy .xls and templates: prefer extract_workbook.py for reads because it can convert through LibreOffice. For edits, convert intentionally and preserve the original file separately unless the user asked for conversion.

Financial models

Unless the user says otherwise, or the existing file already does something else. Color: blue text (0,0,255) for hardcoded inputs and scenario levers · black for formulas · green (0,128,0) for links to another sheet · red (255,0,0) for links to another file · yellow fill (255,255,0) for key assumptions and cells the user should fill in. Numbers: currency $#,##0, with the unit named in the header (Revenue ($mm)) · zeros render as -, including in percentages ($#,##0;($#,##0);-) · negatives in parentheses · percentages 0.0%, stored as fractions (0.15 renders 15.0%; storing 15 renders 1500.0%) · valuation multiples 0.0x · years as text ("2024", never 2,024). Structure: every assumption in its own labeled cell, referenced by the formulas that use it (=B5(1+$B$6), never =B51.05) · formulas consistent across every projection period, since a lone edited cell mid-row is the commonest silent error · guard denominators that can be zero.

Dependencies

openpyxl, pandas, markitdown (pip, preinstalled — install only if an import fails or the command is missing) · LibreOffice (soffice, auto-configured for sandboxed environments via scripts/office/soffice.py)