| name | excel-xlsx-format-preserving-repair |
|---|---|
| description | Preserve formatting and Excel-for-Mac compatibility when editing existing .xlsx workbooks, especially when prior outputs opened with repair prompts or subtle style drift. Can also extend to other Microsoft Office formats as needed. |
Use this skill when editing an existing .xlsx
and the user cares that the result looks like the original and opens cleanly in Microsoft Excel. It is especially relevant for financial/model workbooks, row/column deletion, formula rewrites, files from email threads, or any workbook that previously triggered an Excel repair dialog.
Treat the workbook as an Office Open XML package. Change only the parts required for the requested edit, and copy every other ZIP member through unchanged.
Do not use a LibreOffice or Excel round-trip as the first solution when formatting fidelity matters. Those tools can make a workbook openable, but they may rewrite styles.xml
, theme files, workbook metadata, dimensions, default fonts, and other formatting details. Use round-trips only as diagnostics or explicit fallback, and say when they were used.
If the normal spreadsheet tooling cannot preserve an existing workbook's look, use direct package manipulation with zipfile
plus an XML parser instead of rebuilding the workbook through a high-level library.
Inspect the original package before editing.
- Unzip/read with
zipfile
; recordxl/styles.xml
,xl/theme/theme1.xml
, andxl/sharedStrings.xml
size/hash. - Identify target sheets via
xl/workbook.xml
andxl/_rels/workbook.xml.rels
. - Inspect relevant rows/cells directly in
xl/worksheets/sheetN.xml
.
- Unzip/read with
Preserve formatting by copying structure, not recreating it.
- Copy original rows/cells when possible; update only
r
references, formulas, labels, and values that must change. - Preserve row attributes, column definitions,
s
style ids, number formats, merged cells, conditional formats, data validations, page setup, print settings, sheet protection, and drawing/media parts unless the request requires changing them. - Keep shared strings unless text changes require a deliberate update; inline strings are acceptable for small new labels if that matches the local pattern.
- Copy original rows/cells when possible; update only
Keep formulas, but prefer cached values over broken formulas.
- Expand shared formulas before moving rows if the serializer or transform cannot safely preserve shared-formula anchors.
- Rewrite row/column references only when you can map them correctly.
- If a formula references removed content and cannot be rewritten safely, remove the formula and keep its cached value.
- For unsupported
_xlfn.*
dynamic-array formulas, infer purpose from cached spill values. If the formula is not needed, replace the spill range with normal values and remove dynamic-array metadata such ascm
from those cells. #
Preserve namespace prefixes that
mc:Ignorable
names.- XML serializers may drop unused namespace declarations or rename them to
ns0
,ns1
, etc. Excel for Mac can reject the workbook even when unzip/zip tests pass. - Register known Excel namespaces before serialization, and after serialization verify every prefix in
mc:Ignorable
is declared on that XML root. - Common prefixes seen in modern Excel files include:
mc
:http://schemas.openxmlformats.org/markup-compatibility/2006
x14ac
:http://schemas.microsoft.com/office/spreadsheetml/2009/9/ac
x15
:http://schemas.microsoft.com/office/spreadsheetml/2010/11/main
x15ac
:http://schemas.microsoft.com/office/spreadsheetml/2010/11/ac
xr
:http://schemas.microsoft.com/office/spreadsheetml/2014/revision
xr2
:http://schemas.microsoft.com/office/spreadsheetml/2015/revision2
xr3
:http://schemas.microsoft.com/office/spreadsheetml/2016/revision3
xr6
:http://schemas.microsoft.com/office/spreadsheetml/2016/revision6
xr10
:http://schemas.microsoft.com/office/spreadsheetml/2016/revision10
xcalcf
:http://schemas.microsoft.com/office/spreadsheetml/2018/calcfeatures
- XML serializers may drop unused namespace declarations or rename them to
Remove stale calculation chains after structural edits.
- Delete
xl/calcChain.xml
. - Remove its
<Override PartName="/xl/calcChain.xml" ...>
from[Content_Types].xml
. - Remove its relationship from
xl/_rels/workbook.xml.rels
. - Set or update workbook
calcPr
withcalcMode="auto"
,fullCalcOnLoad="1"
, andforceFullCalc="1"
.
- Delete
Be careful with view metadata.
- To make a sheet open at the top, set
sheetView topLeftCell="A1"
. - If panes are frozen, do not set the pane
topLeftCell
toA1
. It should be the first scrollable cell below/right of the split. Example:xSplit="3"
andySplit="4"
means panetopLeftCell="D5"
. - Rebuild selections consistently for frozen panes, for example
A1
,D1
,A5
, and activeD5
.
- To make a sheet open at the top, set
Always validate more than one layer:
zipfile.ZipFile(output).testzip()
returns clean.- XML parses for every edited part.
- Every
mc:Ignorable
prefix is declared on the same XML root. xl/styles.xml
,xl/theme/theme1.xml
, and unchanged shared strings match the original byte-for-byte when formatting preservation is expected.- No formulas contain obvious error tokens such as
#REF!
,#VALUE!
, or#NAME?
. - Expected labels/rows/cells exist after the transform.
-
Clear matching Excel repair logs before the open test:
~/Library/Containers/com.microsoft.Excel/Data/tmp/Repair Result to <filename>* -
Open the final file in Microsoft Excel itself and verify:
-
no repair prompt appears,
-
no new matching repair log is created,
-
the expected workbook window is visible,
-
the expected sheet count or target sheet is present.
AppleScript can be unreliable when multiple Excel instances are running. If tell application "Microsoft Excel"
reports zero workbooks but the window is visible, inspect the UI with Computer Use and check the repair-log folder before concluding failure.
In the final response, name the final workbook path and state the concrete validations that passed. If a compatibility fallback changed formatting-relevant package parts, say so directly.
When sending the final workbook through the Gmail connector, its displayed schema may say attachment_files
is a string, but the backend may require an array of absolute paths. If a single-path send fails schema validation, retry with attachment_files: ["/absolute/path/to/file.xlsx"]
.