| name | kiss-xlsx-markdown |
| description | 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 |
| metadata | {"author":"github-kiss","source":"agent-skills/kiss-xlsx-markdown/kiss-xlsx-markdown.md"} |
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
| 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
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:
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
- 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.
- 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:
---
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}
| Assumption | 2024 | 2025 | 2026 |
|---|
| Growth rate | 15.0% | 18.0% | 20.0% |
| Gross margin | 62.0% | 63.0% | 64.0% |
| Headcount | 120 | 150 | 180 |
freeze_panes: "B2"
merged_cells: ["A1:D1"]
| Forecast ($K) | 2024 | 2025 | 2026 |
|---|
| Revenue | 10,000 | =B2*(1+Assumptions!B2) | =C2*(1+Assumptions!C2) |
| COGS | =B2*(1-Assumptions!B3) | =C2*(1-Assumptions!C3) | =D2*(1-Assumptions!D3) |
| Gross profit | =B2-B3 | =C2-C3 | =D2-D3 |
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:
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.
