Kiss XLSX Markdown

xlsx-markdown

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

Interactive workflow

1. Detect intent from $ARGUMENTS. If operation and input file are already clear, jump to step 5.

2. 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

3. Ask input file path (the .xlsx for A/C/D; the .md for B).

4. 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.)

5. 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.

6. 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

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:

• macOS: /Applications/LibreOffice.app/Contents/MacOS/soffice
• Windows: C:\Program Files\LibreOffice\program\soffice.exe (and the x86 variant)
• Linux: /usr/bin/soffice, /usr/local/bin/soffice, /snap/bin/libreoffice

Round-trip workflow

1. Export the workbook. The script writes:
   • <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.
2. Edit the .md. Change cell values, rewrite formulas, add rows, reorder sheets. Edits to formatting should go in meta.json.
3. 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:

---
title: Q3 Forecast
author: Claude
xlsx_meta: forecast.meta.json
sheets_order: [Assumptions, Forecast, Summary]
---

<!-- sheet:start name="Assumptions" id="1" hidden="false" -->
```yaml meta
tab_color: "#1E2761"
freeze_panes: "B2"
column_widths: {A: 24, B: 14, C: 14, D: 14}

freeze_panes: "B2"
merged_cells: ["A1:D1"]

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

Windows (PowerShell):

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
python scripts\xlsx_to_md.py model.xlsx model.md --values-only

Options:

• --assets-dir — override the media folder (default: <name>.assets).
• --no-meta — skip the sidecar.
• --values-only — emit cached formula results instead of the formula text. Useful for read-only reviews.

md_to_xlsx.py

macOS / Linux (bash):

python scripts/md_to_xlsx.py model.md model.xlsx
python scripts/md_to_xlsx.py model.md model.xlsx --meta model.meta.json
python scripts/md_to_xlsx.py model.md model.xlsx --template original.xlsx
python scripts/md_to_xlsx.py model.md model.xlsx --recalc

Windows (PowerShell):

python scripts\md_to_xlsx.py model.md model.xlsx
python scripts\md_to_xlsx.py model.md model.xlsx --meta model.meta.json
python scripts\md_to_xlsx.py model.md model.xlsx --template original.xlsx
python scripts\md_to_xlsx.py model.md model.xlsx --recalc

Options:

• --meta — override the sidecar location.
• --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:

macOS / Linux (bash) — into a venv:

python3 -m venv .venv
source .venv/bin/activate
pip install -r <skill-dir>/scripts/requirements.txt

Windows (PowerShell) — into a venv:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r <skill-dir>\scripts\requirements.txt

System dependencies (optional):

• 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.