Office XLSX
Use the bundled scripts in this skill package to produce editable .xlsx
workbooks. The builder writes formulas, styles, bar/column/line/pie charts,
real Excel tables, data validation, conditional formatting, and workbook
recalculation hints. The skill activation metadata includes Skill directory;
treat that as SKILL_DIR and run scripts from SKILL_DIR/scripts/.
Workbook Shape
For nontrivial workbooks, prefer:
- Summary or dashboard sheet first.
- Inputs / assumptions sheet next.
- Detail or source data sheets after that.
- Checks sheet only when formulas, reconciliations, or model integrity matter.
Workflow
- Normalize source data before writing the workbook.
- Use formulas for derived values instead of hardcoded calculated outputs.
Strings beginning with
= are written as Excel formulas.
- For structured workbook creation, create a JSON spec in the working
directory and run:
python3 "$SKILL_DIR/scripts/check_env.py"
python3 "$SKILL_DIR/scripts/build_xlsx.py" --spec spec.json --out output.xlsx
python3 "$SKILL_DIR/scripts/inspect_xlsx.py" --verify output.xlsx
python3 "$SKILL_DIR/scripts/formula_audit.py" output.xlsx
- For CSV/TSV conversion, run one or more inputs into one workbook:
python3 "$SKILL_DIR/scripts/csv_to_xlsx.py" --input data.csv --input lookup.tsv --sheet Data --sheet Lookup --out output.xlsx
python3 "$SKILL_DIR/scripts/inspect_xlsx.py" --verify output.xlsx
- If visual QA matters and LibreOffice is available, run:
python3 "$SKILL_DIR/scripts/render_preview.py" output.xlsx
- To patch an existing workbook without rebuilding it, create a patch JSON and
run:
python3 "$SKILL_DIR/scripts/patch_xlsx.py" --input existing.xlsx --patch patch.json --out output.xlsx
python3 "$SKILL_DIR/scripts/inspect_xlsx.py" --verify output.xlsx
python3 "$SKILL_DIR/scripts/formula_audit.py" output.xlsx --write-cache cached-output.xlsx
Patch actions:
{
"actions": [
{"action": "append_rows", "sheet": "Data", "rows": [["New", 123, "=B2*2"]]},
{"action": "set_cell", "sheet": "Summary", "cell": "B2", "value": "=SUM(Data!B:B)"}
]
}
- When formulas matter, use
formula_audit.py --write-cache and deliver the
cached workbook unless the audit reports unsupported formulas that require
Excel/LibreOffice recalculation. For broad formula coverage, run:
python3 "$SKILL_DIR/scripts/recalculate_xlsx.py" output.xlsx --out recalculated.xlsx
python3 "$SKILL_DIR/scripts/inspect_xlsx.py" --verify recalculated.xlsx
- Deliver the
.xlsx path or attach it with send_attachment.
Spec Shape
{
"title": "Workbook title",
"sheets": [
{
"name": "Summary",
"rows": [["Metric", "Value"], ["Revenue", 1200000], ["Margin", "=B2*0.42"]],
"tables": [{"name": "SummaryTable", "ref": "A1:B3"}],
"data_validations": [{"range": "A2:A10", "type": "list", "formula1": ["Revenue", "Margin"]}],
"conditional_formats": [{"range": "B2:B10", "type": "colorScale"}],
"charts": [
{"type": "column", "title": "Summary", "categories": "$A$2:$A$3", "values": "$B$2:$B$3", "anchor": "D2"},
{"type": "line", "title": "Trend", "categories": "$A$2:$A$3", "values": "$B$2:$B$3", "anchor": "D18"}
],
"column_formats": ["text", "currency"],
"column_widths": [24, 16],
"freeze_top_row": true,
"autofilter": true
}
]
}
Quality Bar
- Keep important values visible; avoid tiny columns and clipped headers.
- Use one workbook, not many disconnected CSV-like sheets, when relationships
between tabs matter.
- Prefer real Excel tables, filters, validations, conditional formats, and
charts when the workbook is meant to be used repeatedly.
- Keep formulas editable, audit formulas before delivery, and write cached
values for supported formulas when possible. Supported audit functions include
common arithmetic, comparisons,
SUM, AVERAGE, MIN, MAX, COUNT,
MEDIAN, ROUND, ABS, and simple IF.
- When patching an existing workbook, preserve unrelated package parts and rerun
inspect_xlsx.py plus formula_audit.py; use recalculate_xlsx.py when the
formula surface exceeds the bundled evaluator.
- If preview rendering fails because LibreOffice or a PDF-to-PNG renderer is
missing, state exactly which verification passed; do not imply visual QA
passed.
1---
2name: office-xlsx
3description: "Use when the user asks to create, inspect, verify, analyze, format, or deliver Excel `.xlsx` workbooks, Google Sheets-targeted spreadsheet artifacts, trackers, budgets, models, tables, dashboards, formulas, CSV/TSV-to-XLSX conversions, or spreadsheet-ready data packs."
4requires:
5 bins: [python3]
6install:
7 - kind: brew
8 formula: python
9 bins: [python3]
10 label: "Install Python 3 via Homebrew"
11 os: [darwin]
12allowed-tools:
13 - read
14 - write
15 - edit
16 - apply_patch
17 - exec
18 - ls
19 - grep
20 - pdf
21 - web_search
22 - web_fetch
23 - send_attachment
24---
25
26# Office XLSX
27
28Use the bundled scripts in this skill package to produce editable `.xlsx`
29workbooks. The builder writes formulas, styles, bar/column/line/pie charts,
30real Excel tables, data validation, conditional formatting, and workbook
31recalculation hints. The skill activation metadata includes `Skill directory`;
32treat that as `SKILL_DIR` and run scripts from `SKILL_DIR/scripts/`.
33
34## Workbook Shape
35
36For nontrivial workbooks, prefer:
37
381. Summary or dashboard sheet first.
392. Inputs / assumptions sheet next.
403. Detail or source data sheets after that.
414. Checks sheet only when formulas, reconciliations, or model integrity matter.
42
43## Workflow
44
451. Normalize source data before writing the workbook.
462. Use formulas for derived values instead of hardcoded calculated outputs.
47 Strings beginning with `=` are written as Excel formulas.
483. For structured workbook creation, create a JSON spec in the working
49 directory and run:
50
51```bash
52python3 "$SKILL_DIR/scripts/check_env.py"
53python3 "$SKILL_DIR/scripts/build_xlsx.py" --spec spec.json --out output.xlsx
54python3 "$SKILL_DIR/scripts/inspect_xlsx.py" --verify output.xlsx
55python3 "$SKILL_DIR/scripts/formula_audit.py" output.xlsx
56```
57
584. For CSV/TSV conversion, run one or more inputs into one workbook:
59
60```bash
61python3 "$SKILL_DIR/scripts/csv_to_xlsx.py" --input data.csv --input lookup.tsv --sheet Data --sheet Lookup --out output.xlsx
62python3 "$SKILL_DIR/scripts/inspect_xlsx.py" --verify output.xlsx
63```
64
655. If visual QA matters and LibreOffice is available, run:
66
67```bash
68python3 "$SKILL_DIR/scripts/render_preview.py" output.xlsx
69```
70
716. To patch an existing workbook without rebuilding it, create a patch JSON and
72 run:
73
74```bash
75python3 "$SKILL_DIR/scripts/patch_xlsx.py" --input existing.xlsx --patch patch.json --out output.xlsx
76python3 "$SKILL_DIR/scripts/inspect_xlsx.py" --verify output.xlsx
77python3 "$SKILL_DIR/scripts/formula_audit.py" output.xlsx --write-cache cached-output.xlsx
78```
79
80Patch actions:
81
82```json
83{
84 "actions": [
85 {"action": "append_rows", "sheet": "Data", "rows": [["New", 123, "=B2*2"]]},
86 {"action": "set_cell", "sheet": "Summary", "cell": "B2", "value": "=SUM(Data!B:B)"}
87 ]
88}
89```
90
917. When formulas matter, use `formula_audit.py --write-cache` and deliver the
92 cached workbook unless the audit reports unsupported formulas that require
93 Excel/LibreOffice recalculation. For broad formula coverage, run:
94
95```bash
96python3 "$SKILL_DIR/scripts/recalculate_xlsx.py" output.xlsx --out recalculated.xlsx
97python3 "$SKILL_DIR/scripts/inspect_xlsx.py" --verify recalculated.xlsx
98```
99
1008. Deliver the `.xlsx` path or attach it with `send_attachment`.
101
102## Spec Shape
103
104```json
105{
106 "title": "Workbook title",
107 "sheets": [
108 {
109 "name": "Summary",
110 "rows": [["Metric", "Value"], ["Revenue", 1200000], ["Margin", "=B2*0.42"]],
111 "tables": [{"name": "SummaryTable", "ref": "A1:B3"}],
112 "data_validations": [{"range": "A2:A10", "type": "list", "formula1": ["Revenue", "Margin"]}],
113 "conditional_formats": [{"range": "B2:B10", "type": "colorScale"}],
114 "charts": [
115 {"type": "column", "title": "Summary", "categories": "$A$2:$A$3", "values": "$B$2:$B$3", "anchor": "D2"},
116 {"type": "line", "title": "Trend", "categories": "$A$2:$A$3", "values": "$B$2:$B$3", "anchor": "D18"}
117 ],
118 "column_formats": ["text", "currency"],
119 "column_widths": [24, 16],
120 "freeze_top_row": true,
121 "autofilter": true
122 }
123 ]
124}
125```
126
127## Quality Bar
128
129- Keep important values visible; avoid tiny columns and clipped headers.
130- Use one workbook, not many disconnected CSV-like sheets, when relationships
131 between tabs matter.
132- Prefer real Excel tables, filters, validations, conditional formats, and
133 charts when the workbook is meant to be used repeatedly.
134- Keep formulas editable, audit formulas before delivery, and write cached
135 values for supported formulas when possible. Supported audit functions include
136 common arithmetic, comparisons, `SUM`, `AVERAGE`, `MIN`, `MAX`, `COUNT`,
137 `MEDIAN`, `ROUND`, `ABS`, and simple `IF`.
138- When patching an existing workbook, preserve unrelated package parts and rerun
139 `inspect_xlsx.py` plus `formula_audit.py`; use `recalculate_xlsx.py` when the
140 formula surface exceeds the bundled evaluator.
141- If preview rendering fails because LibreOffice or a PDF-to-PNG renderer is
142 missing, state exactly which verification passed; do not imply visual QA
143 passed.
shiwenwen