Excel Python
Engineer Excel files from an explicit workbook contract. Preserve package
semantics, distinguish stored artifacts from Excel-runtime behavior, mutate the
smallest supported region, and prove the result by independent reopening and a
semantic comparison.
Boundary and ownership
| Required semantics |
Owner |
Rule |
| Workbook/package structure, formulas, Tables, names, styles, charts, preservation |
excel-python |
Inspect OOXML and use openpyxl or XlsxWriter deliberately. |
| Tabular extraction only |
Polars read_excel with Calamine when installed |
Use when workbook layout is merely an input boundary. |
| Joins, aggregation, dtypes, nulls, lazy plans, analytical computation |
polars-python |
Hand off dataframe decisions; return only for workbook delivery. |
| Recalculation, refresh, native PDF/rendering, authorized VBA, unsupported Excel objects |
installed-Excel runtime workflow |
Stop and escalate; this skill never simulates Excel. |
Inspect installed APIs before relying on drift-prone behavior. Run
python scripts/inspect_excel_env.py from the installed skill and read
library selection.
Ordered workflow
- Recover the workbook contract from the request, workbook, callers, and
downstream consumers. State sheet roles, Tables and names, row grain, keys,
units, input/output regions, formula-owned columns, editable areas,
presentation areas, compatibility, preservation, calculation, and delivery
requirements. Prefer
cell < range < defined name < Excel Table < workbook contract; use bare addresses only when no stable interface exists. Read
workbook contracts.
- Preserve the source. Resolve extension, output destination, trust boundary,
workbook date system, macros, links, and features that must survive.
- Before editing a valuable workbook, run
python scripts/inspect_workbook.py INPUT.xlsx. Treat its JSON as preflight evidence,
not proof that openpyxl can preserve every reported part. Unknown or
unsupported OOXML plus a preservation requirement blocks a blind round-trip.
- Choose the operation path: Polars/Calamine for table extraction, openpyxl
for supported existing-workbook inspection or minimal mutation, and
XlsxWriter or Polars
write_excel for new workbooks. Read ingestion,
existing workbooks, or
generation.
- Apply explicit type and precision,
formula, and untrusted text
policies before writing.
- Write to a temporary sibling, close successfully, then reopen independently.
For edits, run
python scripts/diff_workbooks.py BEFORE AFTER; classify each
difference as required, acceptable serialization variation, or unexpected.
- Run contract assertions and relevant project tests. For stakeholder output,
render or inspect representative sheets because valid OOXML can be unusable.
Read semantic validation.
Workbook contract invariants
- A cell format changes display, not stored arithmetic. Identifiers that can
exceed 15 significant digits are text. Exact rounding is a value operation,
not a number format. Define blank, empty string,
NaN, infinity, boolean,
date, datetime, timezone, currency, percentage, and basis-point policy.
- Preserve the 1900/1904 date system. Do not transfer raw serials across date
systems without conversion and verification.
- Formula text, cached value, and Excel-engine recalculation are three evidence
states:
FORMULA_TEXT_CHECKED, CACHE_INSPECTED, and RECALCULATED. Claim
only states actually established.
- XlsxWriter stores formulas in US-English syntax. It does not calculate them;
absent an explicit result it stores zero and requests recalculation on open.
- Externally sourced text is text. Do not allow leading
= or URL-like data to
become formulas or hyperlinks implicitly; use write_string() or disable
strings_to_formulas and strings_to_urls for text-first exports.
- For
.xlsm, use keep_vba=True, preserve the macro-enabled extension, never
execute VBA, and compare the VBA project hash before and after.
- Never execute macros, refresh connections, claim remote link freshness, or
claim Excel recalculation from an openpyxl/XlsxWriter save.
Preservation and scale gates
Inspect ZIP parts and relationships for VBA, drawings/shapes, charts,
chartsheets, pivots and caches, slicers, external links, connections/Power
Query artifacts, custom XML, embeddings, ActiveX/forms, comments/threaded
comments, media, custom properties, and unknown relationships. If a required
feature is unsupported or preservation is unknown, do not save with openpyxl;
retain the original and require an authorized Excel-native path. Read
OOXML preservation.
Fail before exceeding 1,048,576 rows or 16,384 columns per worksheet. Prefer a
summarized Excel view with Parquet/DuckDB/Polars for oversized analytical data.
XlsxWriter constant_memory requires sequential rows and disables Tables and
merged ranges; choose features before memory mode. openpyxl read-only/write-only
modes also omit normal APIs. Read performance and limits.
Generated workbook quality
Keep machine-readable raw data separate from presentation sheets. Use named
Tables, visible units, centralized number formats, filters, useful freeze panes,
clear input/formula/output styling, stable chart sources, labeled axes, sensible
widths, and no merged cells inside data regions. Use hidden sheets only when
their role is documented in the contract. Add an optional _meta or About
section when provenance matters: generator/schema version, generation and
as-of timestamps, source identifiers or hashes, parameters, and code revision.
Read presentation.
Completion
Do not declare completion until the source remains intact; preflight risks are
resolved; the output reopens; sheet/name/Table/formula/type/date/visibility and
selected style/value contracts pass; required VBA and high-risk package parts
are unchanged; the semantic diff contains no unexplained differences; visual
review ran when presentation is contractual; and recalculation/runtime evidence
is reported separately. Use evaluated recipes only
for their stated conditions.
References
- Library selection and adjacent-skill routing
- Workbook contracts
- Tabular ingestion
- Types and precision
- Formula semantics
- Inspection
- OOXML preservation
- Existing-workbook mutation
- Generation
- Presentation and provenance
- Performance and Excel limits
- Untrusted text and security
- Semantic validation and testing
- Evaluated core recipes
1---2name: excel-python3description: >-4 Use for writing, reviewing, debugging, or testing Python code that inspects,5 edits, extracts, validates, preserves, or generates Excel .xlsx or .xlsm6 workbooks. Trigger on workbook contracts, formulas and cached values, Excel7 Tables, defined names, OOXML parts, types and precision, macros, charts,8 hidden sheets, external links, and semantic workbook verification. Do not use9 for CSV-only work, dataframe computation with no workbook boundary, Excel UI10 automation, recalculation, connection refresh, or macro execution.11argument-hint: "[workbook task, preservation requirements, and output contract]"12metadata:13 source: https://skillmd.com/skills/schattenspiegel/excel-python14---1516# Excel Python1718Engineer Excel files from an explicit workbook contract. Preserve package19semantics, distinguish stored artifacts from Excel-runtime behavior, mutate the20smallest supported region, and prove the result by independent reopening and a21semantic comparison.2223## Boundary and ownership2425| Required semantics | Owner | Rule |26|---|---|---|27| Workbook/package structure, formulas, Tables, names, styles, charts, preservation | `excel-python` | Inspect OOXML and use openpyxl or XlsxWriter deliberately. |28| Tabular extraction only | Polars `read_excel` with Calamine when installed | Use when workbook layout is merely an input boundary. |29| Joins, aggregation, dtypes, nulls, lazy plans, analytical computation | `polars-python` | Hand off dataframe decisions; return only for workbook delivery. |30| Recalculation, refresh, native PDF/rendering, authorized VBA, unsupported Excel objects | installed-Excel runtime workflow | Stop and escalate; this skill never simulates Excel. |3132Inspect installed APIs before relying on drift-prone behavior. Run33`python scripts/inspect_excel_env.py` from the installed skill and read34[library selection](references/library-selection.md).3536## Ordered workflow37381. Recover the workbook contract from the request, workbook, callers, and39 downstream consumers. State sheet roles, Tables and names, row grain, keys,40 units, input/output regions, formula-owned columns, editable areas,41 presentation areas, compatibility, preservation, calculation, and delivery42 requirements. Prefer `cell < range < defined name < Excel Table < workbook43 contract`; use bare addresses only when no stable interface exists. Read44 [workbook contracts](references/workbook-contracts.md).452. Preserve the source. Resolve extension, output destination, trust boundary,46 workbook date system, macros, links, and features that must survive.473. Before editing a valuable workbook, run `python48 scripts/inspect_workbook.py INPUT.xlsx`. Treat its JSON as preflight evidence,49 not proof that openpyxl can preserve every reported part. Unknown or50 unsupported OOXML plus a preservation requirement blocks a blind round-trip.514. Choose the operation path: Polars/Calamine for table extraction, openpyxl52 for supported existing-workbook inspection or minimal mutation, and53 XlsxWriter or Polars `write_excel` for new workbooks. Read [ingestion](references/ingestion.md),54 [existing workbooks](references/existing-workbooks.md), or55 [generation](references/generation.md).565. Apply explicit [type and precision](references/types-and-precision.md),57 [formula](references/formulas.md), and [untrusted text](references/security.md)58 policies before writing.596. Write to a temporary sibling, close successfully, then reopen independently.60 For edits, run `python scripts/diff_workbooks.py BEFORE AFTER`; classify each61 difference as required, acceptable serialization variation, or unexpected.627. Run contract assertions and relevant project tests. For stakeholder output,63 render or inspect representative sheets because valid OOXML can be unusable.64 Read [semantic validation](references/validation-testing.md).6566## Workbook contract invariants6768- A cell format changes display, not stored arithmetic. Identifiers that can69 exceed 15 significant digits are text. Exact rounding is a value operation,70 not a number format. Define blank, empty string, `NaN`, infinity, boolean,71 date, datetime, timezone, currency, percentage, and basis-point policy.72- Preserve the 1900/1904 date system. Do not transfer raw serials across date73 systems without conversion and verification.74- Formula text, cached value, and Excel-engine recalculation are three evidence75 states: `FORMULA_TEXT_CHECKED`, `CACHE_INSPECTED`, and `RECALCULATED`. Claim76 only states actually established.77- XlsxWriter stores formulas in US-English syntax. It does not calculate them;78 absent an explicit result it stores zero and requests recalculation on open.79- Externally sourced text is text. Do not allow leading `=` or URL-like data to80 become formulas or hyperlinks implicitly; use `write_string()` or disable81 `strings_to_formulas` and `strings_to_urls` for text-first exports.82- For `.xlsm`, use `keep_vba=True`, preserve the macro-enabled extension, never83 execute VBA, and compare the VBA project hash before and after.84- Never execute macros, refresh connections, claim remote link freshness, or85 claim Excel recalculation from an openpyxl/XlsxWriter save.8687## Preservation and scale gates8889Inspect ZIP parts and relationships for VBA, drawings/shapes, charts,90chartsheets, pivots and caches, slicers, external links, connections/Power91Query artifacts, custom XML, embeddings, ActiveX/forms, comments/threaded92comments, media, custom properties, and unknown relationships. If a required93feature is unsupported or preservation is unknown, do not save with openpyxl;94retain the original and require an authorized Excel-native path. Read95[OOXML preservation](references/ooxml-preservation.md).9697Fail before exceeding 1,048,576 rows or 16,384 columns per worksheet. Prefer a98summarized Excel view with Parquet/DuckDB/Polars for oversized analytical data.99XlsxWriter `constant_memory` requires sequential rows and disables Tables and100merged ranges; choose features before memory mode. openpyxl read-only/write-only101modes also omit normal APIs. Read [performance and limits](references/performance.md).102103## Generated workbook quality104105Keep machine-readable raw data separate from presentation sheets. Use named106Tables, visible units, centralized number formats, filters, useful freeze panes,107clear input/formula/output styling, stable chart sources, labeled axes, sensible108widths, and no merged cells inside data regions. Use hidden sheets only when109their role is documented in the contract. Add an optional `_meta` or About110section when provenance matters: generator/schema version, generation and111as-of timestamps, source identifiers or hashes, parameters, and code revision.112Read [presentation](references/presentation.md).113114## Completion115116Do not declare completion until the source remains intact; preflight risks are117resolved; the output reopens; sheet/name/Table/formula/type/date/visibility and118selected style/value contracts pass; required VBA and high-risk package parts119are unchanged; the semantic diff contains no unexplained differences; visual120review ran when presentation is contractual; and recalculation/runtime evidence121is reported separately. Use [evaluated recipes](references/recipes-core.md) only122for their stated conditions.123124## References125126- [Library selection and adjacent-skill routing](references/library-selection.md)127- [Workbook contracts](references/workbook-contracts.md)128- [Tabular ingestion](references/ingestion.md)129- [Types and precision](references/types-and-precision.md)130- [Formula semantics](references/formulas.md)131- [Inspection](references/inspection.md)132- [OOXML preservation](references/ooxml-preservation.md)133- [Existing-workbook mutation](references/existing-workbooks.md)134- [Generation](references/generation.md)135- [Presentation and provenance](references/presentation.md)136- [Performance and Excel limits](references/performance.md)137- [Untrusted text and security](references/security.md)138- [Semantic validation and testing](references/validation-testing.md)139- [Evaluated core recipes](references/recipes-core.md)