Translate between Excel (.xlsx) files and Markdown with high-fidelity round-trip. Use this skill whenever the user wants to convert a spreadsheet to Markdown, review or diff a workbook as text, edit cell values or formulas in Markdown and regenerate the .xlsx, or keep a canonical text version of a workbook alongside the .xlsx. Triggers: 'xlsx to markdown', 'excel to md', 'convert this workbook to markdown', 'edit this spreadsheet as text', 'rebuild this xlsx from markdown', 'export spreadsheet as markdown tables', 'round-trip my excel file'. Preserves sheets, formulas, merged cells, number formats, fills, fonts, column widths, freeze panes, named ranges, data validations, and charts via a sidecar meta.json. Not a replacement for the base xlsx skill when building a complex financial model from scratch — use that skill for new models, and use this one for round-trip translation.
Translate between Excel (.xlsx) files and Markdown with high-fidelity round-trip. Use this skill whenever the user wants to convert a spreadsheet to Markdown, review or diff a workbook as text, edit cell values or formulas in Markdown and regenerate the .xlsx, or keep a canonical text version of a workbook alongside the .xlsx. Triggers: 'xlsx to markdown', 'excel to md', 'convert this workbook to markdown', 'edit this spreadsheet as text', 'rebuild this xlsx from markdown', 'export spreadsheet as markdown tables', 'round-trip my excel file'. Preserves sheets, formulas, merged cells, number formats, fills, fonts, column widths, freeze panes, named ranges, data validations, and charts via a sidecar meta.json. Not a replacement for the base xlsx skill when building a complex financial model from scratch — use that skill for new models, and use this one for round-trip translation.
compatibility
Requires kiss project structure with .kiss/ directory
Round-trip translation between .xlsx and Markdown.
Inputs
An .xlsx file (for export to Markdown) or a .md file produced
by this skill (for rebuild to .xlsx).
Optional sidecar <name>.meta.json produced on the prior export —
required for high-fidelity rebuild (preserves formulas, formats,
merged cells, validations, charts, etc.).
Optional environment variables for auto mode: KISS_XLSX_OP,
KISS_XLSX_INPUT, KISS_XLSX_OUTPUT, KISS_XLSX_VALUES_ONLY,
KISS_XLSX_NO_META, KISS_XLSX_RECALC.
Outputs
On export (to-md): <name>.md (one Markdown table per sheet) and
<name>.meta.json next to the input unless --no-meta is passed.
On rebuild (to-xlsx): the destination .xlsx reconstructed from
the Markdown + sidecar.
On round-trip check: a diff of the original Markdown against
Markdown re-extracted from the rebuilt .xlsx.
On recalc: the workbook with cached formula values refreshed.
Context Update
Does not mutate .kiss/context.yml. Operates on user-supplied file
paths only.
User Input
$ARGUMENTS
Consider the user input before proceeding (if not empty). If the
input clearly states the operation and file (e.g. "convert model.xlsx
to markdown"), skip questions that are already answered.
Mode behaviour
Interactive (default — KISS_AGENT_MODE unset or interactive):
Ask one question at a time. Offer lettered options. Always recommend a
default and state why. After gathering answers, show the exact command
and ask for confirmation before instructing the user to run it.
Auto (KISS_AGENT_MODE=auto or user says "in auto mode"):
Read answer keys from the environment (see table below). Apply defaults
for any missing key and log each default as a decision of kind
default-applied. Do not ask questions; output the command immediately.
Auto mode answer keys
Key
Meaning
Default
KISS_XLSX_OP
to-md / to-xlsx / roundtrip / recalc
to-md
KISS_XLSX_INPUT
Input file path
(required — ask if missing)
KISS_XLSX_OUTPUT
Output file path
Derived from input name
KISS_XLSX_VALUES_ONLY
true / false — show cached values instead of formulas
false
KISS_XLSX_NO_META
true / false — skip sidecar (lossy)
false
KISS_XLSX_RECALC
true / false — recalculate formulas after rebuild
false
Interactive workflow
Detect intent from $ARGUMENTS. If operation and input file
are already clear, jump to step 5.
Ask operation:
A) Export .xlsx → Markdown (default)
B) Rebuild .xlsx from Markdown
C) Round-trip check (export, rebuild, diff)
D) Recalculate formulas in an existing .xlsx
Ask input file path (the .xlsx for A/C/D; the .md for B).
Ask output file path — propose the derived default
(e.g. model.md for model.xlsx) and let the user accept or
override. (Not needed for D.)
Ask about the key option for the chosen operation:
A) Show cached values instead of formulas? (--values-only) Default: no.
B) Recalculate formulas after rebuild? (--recalc) Default: no.
C/D) No extra options.
Show the full command and ask for confirmation before running.
When to use
User wants to edit cell values or formulas as text and rebuild the .xlsx.
User wants a text-friendly diff of a spreadsheet in git.
User asks to "export this Excel to markdown" or "rebuild this workbook from markdown".
User wants to review a workbook's contents without opening Excel.
For authoring a complex financial model or chart-heavy workbook from scratch, use the base xlsx skill.
Quick reference
Task
Command
xlsx to Markdown
python scripts/xlsx_to_md.py input.xlsx output.md
Markdown to xlsx
python scripts/md_to_xlsx.py input.md output.xlsx
Recalculate formulas
python scripts/recalc.py output.xlsx
Round-trip check
python scripts/roundtrip_check.py input.xlsx
The python … invocations work identically on macOS, Linux, and Windows — forward slashes in script paths are accepted by Python on all three platforms. The platform difference is only in setup (creating the venv) and activation.
Setup (cross-platform)
The scripts auto-prefer a project-local ./.venv in your current working directory. Run the bootstrap helper once per workspace:
macOS / Linux (bash):
cd /path/to/your/workspace # where your .xlsx lives
bash <skill-dir>/scripts/bash/setup_env.sh
Windows (PowerShell):
cd C:\path\to\your\workspace # where your .xlsx lives
pwsh <skill-dir>\scripts\powershell\setup_env.ps1
The helper creates ./.venv next to your files (not inside the skill folder) and pip installs openpyxl and PyYAML from scripts/requirements.txt. Subsequent script runs are then automatic — each script detects the venv and re-execs under it.
If the venv is missing when you run a script, you get a clear setup hint and the script exits. Pass --system-python on the command line to force the current interpreter:
# macOS / Linux
python scripts/xlsx_to_md.py input.xlsx output.md --system-python
# Windows
python scripts\xlsx_to_md.py input.xlsx output.md --system-python
LibreOffice (soffice) is an optional system dependency, used only for --recalc. The scripts find it on PATH and additionally fall back to:
<name>.md — the editable Markdown with one section per sheet.
<name>.assets/ — embedded images and chart snapshots.
<name>.meta.json — per-cell formatting, merges, column widths, data validation, named ranges, chart XML.
Edit the .md. Change cell values, rewrite formulas, add rows, reorder sheets. Edits to formatting should go in meta.json.
Rebuild to .xlsx. The script reads the Markdown, applies the sidecar metadata, and optionally recalculates formulas via LibreOffice so cached values are fresh.
Markdown format
Full spec in references/format-spec.md. Highlights:
Formulas are written as backticked inline code starting with `=`. Values are written plain. Number formats (currency, %, etc.) live in the sidecar.
## Script usage### `xlsx_to_md.py`
macOS / Linux (bash):
```bash
python scripts/xlsx_to_md.py model.xlsx model.md
python scripts/xlsx_to_md.py model.xlsx model.md --assets-dir media
python scripts/xlsx_to_md.py model.xlsx model.md --no-meta # lossy text dump
python scripts/xlsx_to_md.py model.xlsx model.md --values-only # show cached values, not formulas
--template — start from an existing .xlsx (preserves charts, named ranges, and protected sheets exactly).
--recalc — run recalc.py after writing to force LibreOffice to recalculate formulas.
recalc.py
Lightweight wrapper that invokes LibreOffice to recalculate formulas and scan for errors. Returns JSON like the base xlsx skill's recalc.
macOS / Linux (bash):
python scripts/recalc.py model.xlsx
Windows (PowerShell):
python scripts\recalc.py model.xlsx
Conventions the skill enforces on rebuild
The Markdown representation doesn't encode the financial-modeling conventions the base xlsx skill requires (blue inputs, black formulas, etc.). Those live in the sidecar. If you edit a formula, its text color in the sidecar stays black; if you add a new hardcoded input, add a cell-style entry in meta.json under that sheet/cell if you want it highlighted in blue. The rebuild does not auto-color cells.
Known limitations
VBA/macros in .xlsm files are not round-tripped via Markdown; use --template with the macro-enabled file.
Pivot tables are stored in the sidecar; data changes under a pivot's source range require a recalc pass and (in Excel) a pivot refresh. Use the base xlsx skill to author pivots from scratch.
Charts are copied from the template. Edits to chart data go through the underlying data range, not the chart XML.
Extremely wide sheets (hundreds of columns) produce unwieldy Markdown tables. Consider splitting the sheet or using --values-only for reviews.
Dependencies
Python deps are installed automatically by setup_env.sh / setup_env.ps1 into the project-local ./.venv. The list is in scripts/requirements.txt:
openpyxl
PyYAML
If you want to install them manually instead of using the bootstrap helper:
LibreOffice (soffice) — required only for --recalc and as a side-effect in --template-driven recalculation. The scripts find it on PATH and additionally fall back to standard install paths on macOS / Linux / Windows.
Composition with the base xlsx skill
For new workbooks, formula-heavy models, or reformatting work, use the base xlsx skill. Use this skill when the Markdown representation itself is the deliverable or the intermediate format for edits.
