Excel

Table of contents

1. How it works with an AI agent

User: "Build an FY2026 budget spreadsheet with quarterly totals
       and a summary sheet"
  |
  v
AI Agent (CoDev Code / OpenCode / Claude Code / Codex / Cursor / ...)
  | 1. Sees trigger signals (Excel, spreadsheet, .xlsx, budget,
  |    formula...) -> loads SKILL.md
  | 2. Routes the task: no input file -> CREATE
  |    (existing file -> READ / EDIT / FIX / VALIDATE)
  | 3. Reads references/create.md + format.md
  | 4. Copies the bundled minimal template and writes the
  |    SpreadsheetML XML directly - every derived value as a real
  |    Excel formula (<f>SUM(B2:B9)</f>)
  | 5. Packs: xlsx_pack.py -> output.xlsx
  | 6. Validates: formula_check.py (static) -> exit code 0
  |    (optionally libreoffice_recalc.py + re-check for dynamic proof)
  | 7. Delivers the file + validation report
  v
Finished .xlsx + validation report

The key point: steps 2–6 are orchestrated by the LLM following SKILL.md. The user is involved only at the start (describe the request) and the end (acceptance).

The skill routes every task down one of five paths:

Two rules the skill enforces on itself are worth knowing as a user:

• Formula-first: every calculated cell must be a real Excel formula (SUM, IF, cross-sheet references…), never a hardcoded number.
• No open-and-resave on existing files: editing goes through surgical XML changes, because a library round-trip drops VBA macros, pivot tables and sparklines. Styles, charts, named ranges, data validation and conditional formatting all survive an edit untouched.

2. Prerequisites

Set these up first — Install skills walks through the install on Windows, macOS and Ubuntu step by step; its Install the skills into an agent section covers installing the skill into each agent (CoDev Code, OpenCode, Claude Code, Codex, Cursor) by hand.

The machine running the agent needs:

• Python 3.10–3.14 (required). The core pipelines — create, edit, fix, validate — use only the Python standard library.
• pandas + openpyxl (optional — the READ/analysis path)
• LibreOffice soffice (optional — dynamic formula recalculation via libreoffice_recalc.py)

3. How to use it: talk to the agent

The skill self-activates when your prompt contains its signals: Excel, spreadsheet, .xlsx, .csv, pivot table, financial model, formula… (any request to produce or work with tabular data in Excel form qualifies).

Golden rule — provide these 4 groups of information:

1. What: analyze / create new / edit / repair / validate (the agent can infer, but explicit is better)
2. Which files: input and output files — a plain name plus "in this folder" (a.xlsx), or a full path (C:\temp\a.xlsx, ~/models/a.xlsx)
3. Data/structure: sheets, columns, rows, the raw values, which cells must be formulas
4. Presentation: number formats (decimal places, percent, currency), borders, the financial color convention

On that last point: the skill ships a financial-modeling color standard it applies to formatted workbooks — blue font for hardcoded inputs/assumptions, black for formulas computed on the same sheet, green for cross-sheet references. Name it ("apply the financial color convention") when you want it enforced.

4. Prompt recipes per task type

4.1. Analyze data (READ)

Analyze sales_2026.xlsx in this folder and answer: which region grew fastest
quarter-over-quarter? Show revenue per region per quarter with 2 decimal
places, and flag any data quality issues (nulls, duplicates, mixed types).

The reader handles .xlsx, .xlsm, .csv and .tsv (CSV encodings are auto-detected). Analysis never modifies the source file. Be explicit about decimal places — the skill applies the format you name to every number it reports.

4.2. Create a new spreadsheet (CREATE)

Create budget_fy2026.xlsx in this folder:
- Sheet "Budget": columns Quarter | Personnel | Marketing | Infrastructure | Total,
  four quarterly rows plus a TOTAL row with an accounting-style top border
- Every Total cell must be a real SUM formula, not a typed-in number
- Sheet "Summary": headline figures referencing the Budget sheet
- Apply the financial color convention (inputs blue, formulas black,
  cross-sheet references green)

Tip: the formula-first rule means derived values arrive as live formulas — say which cells are inputs and which are computed, and name the number formats (percent, currency, decimals) you expect.

4.3. Edit an existing file (EDIT)

# Add a column:
In budget_fy2026.xlsx in this folder, add column G "% of Total" to the Budget
sheet: G2:G9 = F divided by the grand total, percent format 0.0%,
G10 = SUM(G2:G9), and give row 10 a medium top border across ALL columns.
Change nothing else.
 
# Insert a row:
In budget.xlsx in this folder, insert a "Utilities" row right after the
"Office Rent" row of sheet "Budget FY2025" with values 3000 / 3000 / 3500 /
3500 and a SUM formula in column F; copy the style of the row above. Totals
must update.
 
# Fill cells:
model.xlsx in this folder has an empty cell B3 on the "Overview" sheet. Fill
it with =SUM('Sales Data'!D2:D13). Keep every other cell byte-identical.

Important tip: locate rows by label text ("the Office Rent row"), never by row number alone — spreadsheets drift, and the skill is instructed to find the row by its label before touching anything. When a row shifts, the helper scripts cascade the change through formulas, merged cells, conditional formatting, chart series and pivot source ranges.

4.4. Repair broken formulas (FIX)

q3.xlsx in this folder shows #REF! errors on the Summary sheet. Find every
broken formula, repair the references, and prove the fix with a formula check
report. All original sheets and data must survive unchanged.

4.5. Validate and audit (VALIDATE)

# Formula validation, static + dynamic:
Run a full formula validation on model.xlsx in this folder: the static check
plus a LibreOffice recalculation, and give me the error report broken down by
sheet.
 
# Formatting audit:
Audit model.xlsx in this folder against the financial color standard and
number-format rules, and list every violation with its cell address.

5. Acceptance — make the agent prove it

SKILL.md mandates validation before delivery. You are entitled to (and should) ask for evidence:

"Run the validation and show me the results"

A passing delivery includes:

• formula_check.py → exit code 0 — no error-value cells (#REF!, #DIV/0!, …), no references to missing sheets or named ranges, shared formulas intact. Ask for --report to get the JSON summary (total formulas, errors by type).
• For edit tasks: a read-back verification — the skill's own integrity rules require re-opening the output and confirming the original sheets and a sample of original data are still present, with only the requested cells changed.
• For formatting tasks: style_audit.py → exit code 0 (color-role, number-format and style-integrity checks).
• For the strongest proof: libreoffice_recalc.py + a formula re-check — this catches runtime-only errors (a #DIV/0! that appears only when formulas actually execute) that static validation cannot see.

Finally, open the file in Excel or LibreOffice for a visual check. Freshly written files carry formulas without cached results, so computed cells show their values once the application opens and recalculates the workbook.

6. Troubleshooting

7. Skill limitations

• Handles .xlsx/.xlsm (plus .csv/.tsv for reading); the legacy binary .xls format is not supported.
• No password-protected/encrypted files.
• Creating charts or pivot tables from scratch is not covered; existing ones are preserved during edits (their source ranges are updated when rows shift).
• Static validation cannot catch errors that only appear at calculation time — dynamic proof requires LibreOffice.
• Output files carry formulas, not cached results — values appear when Excel or LibreOffice opens the file (or after a libreoffice_recalc.py pass).

8. Appendix: the scripts the agent runs under the hood

So you can read the agent's logs — every command is python3 <skill>/scripts/<script>:

Formula templates in --formula accept a {row} placeholder, expanded per row (e.g. '=F{row}/$F$10', 'F=SUM(B{row}:E{row})').

What formula_check.py examines: error-value cells (all 7 Excel error types), formulas referencing sheets missing from the workbook, references to undefined named ranges, shared-formula integrity, and malformed error cells. What it cannot examine: errors that only materialize when formulas execute — that is what the libreoffice_recalc.py + re-check pipeline is for.