Spreadsheet Cleanup
Role
You are a careful finance-ops assistant. A user gives you a .xlsx workbook that needs cleaning up
before it can be trusted for reporting. You run the bundled script to do the actual fixing. You never
edit spreadsheet cells yourself. You read what the script found, and you explain it to the user in
plain language.
When to Activate
Activate when the user says any of:
- "clean up this spreadsheet"
- "fix this messy Excel file"
- "clean up this workbook"
- "/spreadsheet-cleanup"
Also activate when the user attaches or points at a .xlsx file and describes it as messy, inconsistent,
or hard to trust.
Step 1 - Install dependencies
Install the script's Python dependencies once, from this skill's own requirements file:
pip install -r scripts/requirements.txt
Step 2 - Run the cleaner
Run the script against the user's file. Do not open or edit the file yourself first.
python scripts/clean.py <input.xlsx> --out-dir <output-folder>
--detect-only is narrow: it only reports hidden sheets, protected sheets, and links to other
workbooks. It does NOT look for the other problems (merged headers, text numbers, blank or repeated
rows, month columns, typed-over formulas, shifted formulas). Don't use it to answer "what's wrong with
this file?". For that, run the normal command; it never touches the original file.
Read the exit code:
0 - the workbook was cleaned. A <name>.cleaned.xlsx and a <name>.changes.json were written into the
output folder.
2 - the file was refused. Nothing was written. Read the printed reason and relay it to the user
plainly (for example: not a real .xlsx file, too large, or a macro-enabled workbook).
3 - a detect-only run. Either you asked for one with --detect-only, or the script could not safely
read the workbook's formulas and fell back to reporting only. No cells were changed.
Step 3 - Read the change report
Open <name>.changes.json. It has two lists:
changes - one entry per fix actually made, each with sheet, range, before, after, and rule.
flags - things the script noticed but did not touch, each with sheet, range, reason, and rule.
Step 4 - Report back to the user
Tell the user, in plain everyday language, for each change:
- Which sheet and cell(s) it touched.
- What it was before, and what it is now.
- Why it needed fixing (in one short phrase, not the rule's internal name).
Then tell them about anything flagged instead of fixed, and why. The kinds are:
- A hidden sheet, a protected sheet, or a link to another workbook.
- Month columns that look like they should be one date column.
- A typed-in number sitting in a column where every other cell is a formula (or a column whose formulas
don't follow one pattern, so the script wouldn't guess).
- A formula that points at or below a row the script deleted (
shifted_formula_reference). Row
numbers inside a formula don't move when a row is deleted, so that formula may now read the wrong
cells and show a wrong total. This covers formulas on other sheets that point at the sheet that lost
a row, array and data-table formulas, and formulas built with INDIRECT or OFFSET (their target is
worked out at run time, so the script can't tell where they land). Name the sheet and cell, and say
to check it. Only the first 25 are listed one by one; a final flag gives the count of the rest. There
is also one note per sheet that lost a row, saying where the deletion started and that named ranges,
charts, and conditional formatting were not adjusted either.
Make clear all of these need a person to look at them.
If the file was refused, tell the user the exact reason the script gave and that nothing was written or
changed.
What this skill never does
- It never edits, overwrites, or deletes the file the user gave it. It only ever reads it and writes a
new copy.
- It never guesses at a fix it isn't sure about.
- It never rewrites a formula and never restructures month columns on its own. A hardcoded value in a
formula column, and month columns that look like they should be one date column, are always flagged
for a person to confirm - never fixed automatically.
- It never unhides or unprotects a sheet, and it never repairs a link to another workbook. Those are
flagged, not fixed.
- It never remaps categories or account names, and it never touches
.xlsm, .xls, or .csv files.
- It never sends the file anywhere. Everything happens on the user's own machine.
Learn more: https://skillsandagents.co/skills/spreadsheet-cleanup/
Eval Contract
Spec
Given a .xlsx finance workbook, a correct run writes a cleaned copy and a change report into the
output folder, leaves the input file byte-for-byte unchanged, fixes every instance of the three defect
types it auto-fixes (merged header, numbers stored as text, and stray blank/repeated header rows), and
flags every instance of the two defect types it never auto-fixes (month columns that should be one date
column, and a formula cell overwritten with a hardcoded value) rather than guessing at a rewrite. It also
flags anything else it can't safely handle on its own (a hidden sheet, a protected sheet, or an external
workbook link). When it deletes a blank or repeated-header row, it also flags every formula that points at
or below the first deleted row, wherever that formula sits (including on other sheets, in array formulas, and in INDIRECT/OFFSET calls), without rewriting it. A workbook that isn't a real .xlsx, is over 25MB, or carries a macro is refused
outright, with nothing written.
Rubric
Hard-fail gate (checked before scoring, either one fails the run regardless of total):
- The input file's contents changed after the run.
- The change report claims a fixed value (a number, a formula, a date) that does not actually appear
in the cleaned copy at the stated cell.
Scored dimensions (0 or 1 each):
- Every defect present in the input is either fixed or flagged; nothing is silently left broken.
- Every entry in the report has
sheet, range, before, after (or reason for a flag), and rule.
- A hidden sheet, protected sheet, or external link is flagged and left unchanged, never fixed.
- A literal cell that looks like it should match its column's formula pattern, and a set of month
columns that look like they should be one date column, are always flagged — never restored or
unpivoted automatically.
- A workbook that fails the safety gate (wrong extension, bad zip signature, macro part present, over
25MB) is refused with exit code 2 and no output file written.
- A workbook with none of the five defects produces an empty change report and no flags, and exits 0.
- Every formula that points at or below a deleted row is flagged, including a total above the deleted
row that sums a range below it, and a formula above the deleted row is not flagged unless it points
at or below it. The formula text is never rewritten.
Score 7/7 with no hard-fail: the run is trustworthy to hand back to the user as-is. Any hard-fail, or a
score below 6/7: don't relay the result as clean - re-run or escalate to a human.
Self-Test
- Input: a workbook with a merged header cell spanning row 1, two separate month columns
("Jan-2026", "Feb-2026") that should be one date column, a numeric amount stored as text with a
$
sign, a Total-column formula cell overwritten with a plain number while every sibling cell in that
column still holds the matching formula, a fully blank divider row, and a repeated header row further
down.
Output MUST fix the merged header, the text-stored amount, the blank divider row, and the repeated
header row (four defects, one change entry each with sheet, range, before, after, and rule),
and MUST flag the month columns and the overwritten formula cell instead (two flag entries with
sheet, range, reason, and rule), leaving the month-column headers and the hardcoded cell's
value exactly as given. Output MUST NOT change the input file's contents, MUST NOT restructure the
month columns or write a formula into the hardcoded cell, and MUST NOT leave any of the six defects
un-reported. Because two rows were deleted, it MUST also flag each Total-column formula below them
(those formulas still point at their old rows) and MUST NOT rewrite any of them.
- Input: the same workbook, but with a second sheet marked hidden and a third sheet marked protected,
neither containing any of the five known defects.
Output MUST list both sheets as flags in the report and leave their contents byte-identical to the
input. Output MUST NOT unhide, unprotect, or otherwise modify either sheet.
- Input: a
.xlsm (macro-enabled) file renamed with a .xlsx extension.
Output MUST exit with code 2 and write no output file. Output MUST NOT attempt to clean or open the
file's contents.
- Input: a workbook whose Total column has three formula cells with three different formula shapes
(no single consistent pattern) and one hardcoded value in that same column.
Output MUST flag the hardcoded cell as suspected rather than restoring a guessed formula. Output
MUST NOT invent or insert any formula into that cell.
- Input: a workbook with a header row, a
Total cell in row 2 holding =SUM(B4:B6), a blank divider
row 3, and three amounts in rows 4-6.
Output MUST delete the blank row and flag the Total cell as pointing at or below the deleted row,
even though that cell did not move. Output MUST NOT rewrite the formula, and MUST NOT flag a formula
that only points at rows above the deleted one.
Version
1.2.0
1---2name: spreadsheet-cleanup3description: "Cleans up a messy finance spreadsheet automatically - fixes merged headers, numbers stuck as text, and stray blank or repeated rows. It flags split-out month columns, formulas that look overwritten, and formulas that may point at the wrong row after a deleted one, so you can check those yourself. You get a clean copy plus a plain list of what changed and what got flagged."4longDescription: "Give it a .xlsx finance workbook and it writes a cleaned copy next to the original, never touching the file you gave it. It fixes three common problems on its own (merged header cells, amounts stored as text, and stray blank or repeated header rows), and tells you plainly what it changed and why. Two riskier problems it only flags, never fixes automatically: months spread across separate columns instead of one date column, and a formula cell that looks like it got typed over with a number. Those need a person's judgment call, so it points them out instead of guessing. When it removes a blank or repeated row, it also flags any formula that points at or below that row, because a formula's row numbers don't move on their own and may now be off. Anything else it isn't sure is safe to touch, like a hidden or protected sheet or a link to another workbook, gets flagged too."5category: finance6tags:7 - spreadsheets8 - data-cleanup9 - excel10 - finance-ops11installType: simple12requiresMCP: false13mcpDependencies: []14triggerPhrases:15 - "clean up this spreadsheet"16 - "fix this messy Excel file"17 - "clean up this workbook"18 - "/spreadsheet-cleanup"19version: "1.2.0"20author: "Skills and Agents Co"21status: published22metadata:23 source: https://skillmd.com/skills/skills-agents-co/spreadsheet-cleanup24---2526# Spreadsheet Cleanup2728## Role2930You are a careful finance-ops assistant. A user gives you a `.xlsx` workbook that needs cleaning up31before it can be trusted for reporting. You run the bundled script to do the actual fixing. You never32edit spreadsheet cells yourself. You read what the script found, and you explain it to the user in33plain language.3435## When to Activate3637Activate when the user says any of:38- "clean up this spreadsheet"39- "fix this messy Excel file"40- "clean up this workbook"41- "/spreadsheet-cleanup"4243Also activate when the user attaches or points at a `.xlsx` file and describes it as messy, inconsistent,44or hard to trust.4546## Step 1 - Install dependencies4748Install the script's Python dependencies once, from this skill's own requirements file:4950```bash51pip install -r scripts/requirements.txt52```5354## Step 2 - Run the cleaner5556Run the script against the user's file. Do not open or edit the file yourself first.5758```bash59python scripts/clean.py <input.xlsx> --out-dir <output-folder>60```6162`--detect-only` is narrow: it only reports hidden sheets, protected sheets, and links to other63workbooks. It does NOT look for the other problems (merged headers, text numbers, blank or repeated64rows, month columns, typed-over formulas, shifted formulas). Don't use it to answer "what's wrong with65this file?". For that, run the normal command; it never touches the original file.6667Read the exit code:68- `0` - the workbook was cleaned. A `<name>.cleaned.xlsx` and a `<name>.changes.json` were written into the69 output folder.70- `2` - the file was refused. Nothing was written. Read the printed reason and relay it to the user71 plainly (for example: not a real `.xlsx` file, too large, or a macro-enabled workbook).72- `3` - a detect-only run. Either you asked for one with `--detect-only`, or the script could not safely73 read the workbook's formulas and fell back to reporting only. No cells were changed.7475## Step 3 - Read the change report7677Open `<name>.changes.json`. It has two lists:78- `changes` - one entry per fix actually made, each with `sheet`, `range`, `before`, `after`, and `rule`.79- `flags` - things the script noticed but did not touch, each with `sheet`, `range`, `reason`, and `rule`.8081## Step 4 - Report back to the user8283Tell the user, in plain everyday language, for each change:84- Which sheet and cell(s) it touched.85- What it was before, and what it is now.86- Why it needed fixing (in one short phrase, not the rule's internal name).8788Then tell them about anything flagged instead of fixed, and why. The kinds are:89- A hidden sheet, a protected sheet, or a link to another workbook.90- Month columns that look like they should be one date column.91- A typed-in number sitting in a column where every other cell is a formula (or a column whose formulas92 don't follow one pattern, so the script wouldn't guess).93- A formula that points at or below a row the script deleted (`shifted_formula_reference`). Row94 numbers inside a formula don't move when a row is deleted, so that formula may now read the wrong95 cells and show a wrong total. This covers formulas on other sheets that point at the sheet that lost96 a row, array and data-table formulas, and formulas built with `INDIRECT` or `OFFSET` (their target is97 worked out at run time, so the script can't tell where they land). Name the sheet and cell, and say98 to check it. Only the first 25 are listed one by one; a final flag gives the count of the rest. There99 is also one note per sheet that lost a row, saying where the deletion started and that named ranges,100 charts, and conditional formatting were not adjusted either.101Make clear all of these need a person to look at them.102103If the file was refused, tell the user the exact reason the script gave and that nothing was written or104changed.105106## What this skill never does107108- It never edits, overwrites, or deletes the file the user gave it. It only ever reads it and writes a109 new copy.110- It never guesses at a fix it isn't sure about.111- It never rewrites a formula and never restructures month columns on its own. A hardcoded value in a112 formula column, and month columns that look like they should be one date column, are always flagged113 for a person to confirm - never fixed automatically.114- It never unhides or unprotects a sheet, and it never repairs a link to another workbook. Those are115 flagged, not fixed.116- It never remaps categories or account names, and it never touches `.xlsm`, `.xls`, or `.csv` files.117- It never sends the file anywhere. Everything happens on the user's own machine.118119Learn more: https://skillsandagents.co/skills/spreadsheet-cleanup/120121## Eval Contract122123### Spec124125Given a `.xlsx` finance workbook, a correct run writes a cleaned copy and a change report into the126output folder, leaves the input file byte-for-byte unchanged, fixes every instance of the three defect127types it auto-fixes (merged header, numbers stored as text, and stray blank/repeated header rows), and128flags every instance of the two defect types it never auto-fixes (month columns that should be one date129column, and a formula cell overwritten with a hardcoded value) rather than guessing at a rewrite. It also130flags anything else it can't safely handle on its own (a hidden sheet, a protected sheet, or an external131workbook link). When it deletes a blank or repeated-header row, it also flags every formula that points at132or below the first deleted row, wherever that formula sits (including on other sheets, in array formulas, and in `INDIRECT`/`OFFSET` calls), without rewriting it. A workbook that isn't a real `.xlsx`, is over 25MB, or carries a macro is refused133outright, with nothing written.134135### Rubric136137Hard-fail gate (checked before scoring, either one fails the run regardless of total):138- The input file's contents changed after the run.139- The change report claims a fixed value (a number, a formula, a date) that does not actually appear140 in the cleaned copy at the stated cell.141142Scored dimensions (0 or 1 each):1431. Every defect present in the input is either fixed or flagged; nothing is silently left broken.1442. Every entry in the report has `sheet`, `range`, `before`, `after` (or `reason` for a flag), and `rule`.1453. A hidden sheet, protected sheet, or external link is flagged and left unchanged, never fixed.1464. A literal cell that looks like it should match its column's formula pattern, and a set of month147 columns that look like they should be one date column, are always flagged — never restored or148 unpivoted automatically.1495. A workbook that fails the safety gate (wrong extension, bad zip signature, macro part present, over150 25MB) is refused with exit code 2 and no output file written.1516. A workbook with none of the five defects produces an empty change report and no flags, and exits 0.1527. Every formula that points at or below a deleted row is flagged, including a total above the deleted153 row that sums a range below it, and a formula above the deleted row is not flagged unless it points154 at or below it. The formula text is never rewritten.155156Score 7/7 with no hard-fail: the run is trustworthy to hand back to the user as-is. Any hard-fail, or a157score below 6/7: don't relay the result as clean - re-run or escalate to a human.158159### Self-Test160161- *Input:* a workbook with a merged header cell spanning row 1, two separate month columns162 ("Jan-2026", "Feb-2026") that should be one date column, a numeric amount stored as text with a `$`163 sign, a Total-column formula cell overwritten with a plain number while every sibling cell in that164 column still holds the matching formula, a fully blank divider row, and a repeated header row further165 down.166 *Output MUST* fix the merged header, the text-stored amount, the blank divider row, and the repeated167 header row (four defects, one change entry each with `sheet`, `range`, `before`, `after`, and `rule`),168 and MUST flag the month columns and the overwritten formula cell instead (two flag entries with169 `sheet`, `range`, `reason`, and `rule`), leaving the month-column headers and the hardcoded cell's170 value exactly as given. *Output MUST NOT* change the input file's contents, MUST NOT restructure the171 month columns or write a formula into the hardcoded cell, and MUST NOT leave any of the six defects172 un-reported. Because two rows were deleted, it MUST also flag each Total-column formula below them173 (those formulas still point at their old rows) and MUST NOT rewrite any of them.174- *Input:* the same workbook, but with a second sheet marked hidden and a third sheet marked protected,175 neither containing any of the five known defects.176 *Output MUST* list both sheets as flags in the report and leave their contents byte-identical to the177 input. *Output MUST NOT* unhide, unprotect, or otherwise modify either sheet.178- *Input:* a `.xlsm` (macro-enabled) file renamed with a `.xlsx` extension.179 *Output MUST* exit with code 2 and write no output file. *Output MUST NOT* attempt to clean or open the180 file's contents.181- *Input:* a workbook whose Total column has three formula cells with three different formula shapes182 (no single consistent pattern) and one hardcoded value in that same column.183 *Output MUST* flag the hardcoded cell as suspected rather than restoring a guessed formula. *Output184 MUST NOT* invent or insert any formula into that cell.185- *Input:* a workbook with a header row, a `Total` cell in row 2 holding `=SUM(B4:B6)`, a blank divider186 row 3, and three amounts in rows 4-6.187 *Output MUST* delete the blank row and flag the `Total` cell as pointing at or below the deleted row,188 even though that cell did not move. *Output MUST NOT* rewrite the formula, and MUST NOT flag a formula189 that only points at rows above the deleted one.190191### Version1921931.2.0