hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-excel
hyper-excel
VerifiedUse this skill when the user asks to read, analyze, create, or modify Excel workbooks (.xlsx, .xlsm) or turn CSV data into spreadsheets - inspecting sheets and formulas, editing cells while keeping existing formatting and formulas intact, building formatted reports with charts, or auditing formulas for broken ranges and error values. Do not use for plain dataframes, PDF or slide output, or VBA macro authoring.
references/readers-and-writers.md
View on GitHub# Readers and Writers
> What each tool actually keeps when it touches an `.xlsx`. The bundled-tool rows were run on this machine on 2026-11-13. The third-party-library rows marked `LOCAL` were run here too; the rest cite the library's own documentation and are marked as such.
## Contents
1. The package, so losses make sense
2. Measured: openpyxl 3.1.5 round-trip
3. Measured: the bundled tools
4. Other writers, by mechanism
5. Deciding
6. What no tool here does
## The package, so losses make sense
An `.xlsx` is a zip of XML parts. A workbook with a chart, an image, a table, a comment, a defined name, and a print area has these parts:
```
[Content_Types].xml _rels/.rels
xl/workbook.xml xl/_rels/workbook.xml.rels
xl/styles.xml xl/theme/theme1.xml
xl/worksheets/sheet1.xml xl/worksheets/_rels/sheet1.xml.rels
xl/drawings/drawing1.xml xl/drawings/_rels/drawing1.xml.rels
xl/charts/chart1.xml xl/media/image1.png
xl/tables/table1.xml xl/comments/comment1.xml
docProps/app.xml docProps/core.xml
```
A writer that only understands worksheets rewrites `sheet1.xml`, `workbook.xml`, `[Content_Types].xml`, and the rels files, and regenerates `styles.xml` from whatever style model it holds. Anything its model does not include stops existing. That is the whole mechanism behind "the chart disappeared".
## Measured: openpyxl 3.1.5 round-trip
Conditions: `uv run --with openpyxl --python 3.13`, macOS arm64, 2026-11-13. Load and save, no edits.
**Simple file** (generated by `build_workbook.py`, one column chart, no macros):
| Observation | Result |
|---|---|
| parts before / after | 11 / 14 |
| parts missing | none |
| parts added | `docProps/app.xml`, `docProps/core.xml`, `xl/theme/theme1.xml` |
| parts changed | 11 of 11 — every part rewritten, including `chart1.xml` and `styles.xml` |
So on a file this shape, openpyxl keeps the content but rewrites the entire package. The chart survived; the bytes did not.
**Rich file** (chart, image, table, data validation, comment, merged cells, print area, defined name, freeze panes):
| Artifact | After round-trip |
|---|---|
| chart | kept (`_charts` = 1) |
| image | kept (`_images` = 1) |
| table | kept (`tables` = 1) |
| data validation | kept |
| cell comment | kept |
| merged cells, print area, freeze, defined name | kept |
openpyxl's model covers those, so they survive. This is why "does openpyxl lose my chart" has no single answer: it depends on whether the artifact is in its model.
**Pivot parts**, injected as `xl/pivotCache/pivotCacheDefinition1.xml` and `xl/pivotTables/pivotTable1.xml` into the rich file: after load and save, both parts were **gone**. openpyxl 3.1.5 does define `openpyxl.pivot.table.TableDefinition` and `openpyxl.pivot.cache.CacheDefinition`, but this injected stub was not in the shape its reader accepts, so it was dropped rather than preserved. Treat a pivot as at risk through openpyxl and verify the parts after any round trip; do not assume either that it is always kept or always lost.
**Macros**:
| Call | `xl/vbaProject.bin` after save |
|---|---|
| `load_workbook(path)` | gone |
| `load_workbook(path, keep_vba=True)` | kept, byte-identical (`sha256` equal), `macroEnabled` content type preserved |
The default call silently strips VBA. `keep_vba=True` is mandatory for `.xlsm`, and even then only the VBA part is guaranteed: part shapes openpyxl does not model, such as an unrecognized pivot stub, still go.
## Measured: the bundled tools
| Operation | Parts touched | Verified by |
|---|---|---|
| `inspect` | none (read-only) | — |
| `patch --set-value` on a file with pivot parts | only `xl/worksheets/sheet1.xml` | `untouchedPartsPreserved: true`, 18 of 19 parts digest-identical |
| `patch` on `.xlsm` | worksheet part only | `vbaProject.bin` sha256 unchanged |
| `recalc` | worksheet parts + `xl/workbook.xml` (`fullCalcOnLoad`) | formulas still present, `data_only` read-back returns values |
| `build` | new file | 19 parts, opens in openpyxl |
The single-part touch count is the reason to prefer `patch` for any edit to an existing file that has charts, pivots, or macros.
## Other writers, by mechanism
| Writer | Model | What it drops or rewrites |
|---|---|---|
| pandas `to_excel` (openpyxl engine) | values and basic styles only | charts, images, comments, pivots, macros, conditional formats; writes a new file so the question is "what did the source lose" |
| xlsxwriter | write-only | cannot read an existing file at all; good for generation, unusable for editing |
| LibreOffice headless convert | full engine | rewrites the whole package; keeps most content but changes ids, styles, and chart serialization |
| Numbers / Excel (GUI) | full engine | authoritative, but not scriptable without a GUI session |
| raw zip edit (this skill) | bytes | nothing, provided the part you rewrite stays schema-valid |
`uv run --with openpyxl` is the cheapest independent read-back available here; it is not the editor of record.
## Deciding
- Editing an existing file with charts, pivots, macros, or an unknown origin → `patch`.
- Generating a new file → `build` (charts and conditional formats included) then `recalc`.
- Need a pivot → compute the rows and write them; do not promise a native pivot. See `large-data-and-pivots.md`.
- Need an independent check → openpyxl read-back, and say the check was openpyxl rather than Excel.
## What no tool here does
- Calculate with Excel's engine. The evaluator covers a documented function set and reports the rest as unevaluated. Ranges keep their row/column shape for `ROWS`, `COLUMNS`, `INDEX`, `VLOOKUP`, and `HLOOKUP`; `ISERROR`/`ISERR`/`ISNA` inspect an error instead of propagating it; a failed `MATCH` or lookup returns `#N/A`, which is what `IFNA` and `ISNA` test for; `POWER`/`^` return `#NUM!` for a negative base with a fractional exponent rather than a complex number.
- Render or print. Layout, page breaks, and print fidelity need a real engine.
- Run VBA.
- Read `.xls` or `.xlsb`.
## Sources
> Checked 2026-11-13.
| Claim | Source |
|---|---|
| Every openpyxl part count, missing part, and preserved artifact listed above | measured on this machine 2026-11-13 with openpyxl 3.1.5 via `uv run --with openpyxl`; scripts and results reproduced in the session |
| The bundled tool's touched-part counts | `patch_workbook.py` / `recalc_cached.py` output, read on 2026-11-13 |
| OOXML part layout | <https://learn.microsoft.com/en-us/office/open-xml/spreadsheet/structure-of-a-spreadsheetml-document> |
| pandas `to_excel` uses openpyxl as its `.xlsx` engine | <https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_excel.html> |
| xlsxwriter is write-only by design | <https://xlsxwriter.readthedocs.io/working_with_memory.html> |
### Evidence grade
`LOCAL` for the rows this skill's own tools produced, and for openpyxl 3.1.5 where it was run here. The pandas, xlsxwriter, LibreOffice, and Numbers rows are reasoned from their documented behavior, and LibreOffice is not installed on this machine, so those are `DOC`-grade evidence, not measurements. Version numbers and the date are stated so every claim can be re-checked.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |