md-to-xlsx
You turn tabular data into a .xlsx workbook that behaves like one somebody built by hand:
numbers add up, dates sort, percentages show as percentages, and the header row stays put
with a filter on it. The script does the conversion with the Python standard library, so there
is nothing to install. Your job is to get the tables into shape, choose the flags, and tell
the user what was typed how. For prose documents, md-to-docx makes the Word version.
How to respond
Ask once for what's missing. You need the data: a
.md,.csv,.tsvor.jsonpath, or tables pasted in the chat (save them to a.mdfile). If the user has only prose with numbers in it, build the pipe tables first and show them before converting.To build the workbook, I need:
- The data: a file path (Markdown with tables, CSV or JSON), or paste it. (required)
- Formulas: if some cells start with
=, should they calculate? Default: no, they're kept as text.
Prepare the source. Fix what would convert badly, in a copy, and list each change:
- Give every table a short heading right above it. That heading becomes the sheet name.
Excel allows 31 characters and no
[ ] : * ? / \, and names must be unique. The script enforces this, but "Renewals due Q4–Q1" beats a name it had to cut down. - Two tables under the same heading become "Name" and "Name (2)". Give each its own heading.
- One header row only. A merged two-row header doesn't exist in a pipe table; flatten it to "Q3 spend", "Q3 change".
- Keep units out of number cells. Write
1,240in a column headed "Spend (k$)", not1,240k$, or the cell stays text. - European number formats (
1.234,50) stay text. Convert them to1234.50first, or tell the user those columns won't sum.
- Give every table a short heading right above it. That heading becomes the sheet name.
Excel allows 31 characters and no
Convert.
# Claude Code python3 "${CLAUDE_SKILL_DIR}/scripts/md_to_xlsx.py" review.md -o review.xlsx # Other IDEs (from the skill folder) python3 scripts/md_to_xlsx.py review.md -o review.xlsxOptions:
--title "..."sets the title in File > Properties.--formulaswrites cells starting with=as live formulas. Use it only when the user wrote those formulas or trusts the source. A formula from an export, a form or a scraped page can runHYPERLINKorWEBSERVICEcalls that leak data when the file is opened. OWASP calls this CSV injection.Read the summary and every
WARNline. The script prints one line per sheet with its size and how many cells became numbers, dates, booleans and text. Check that the counts match what the data should be. If a column of amounts shows up as text, a stray unit or a European decimal is the usual cause: fix it and rerun. Report renamed sheets, padded rows and formula cells to the user.Check that it opens. Reopen it with Python's
zipfileand parse each XML part, or on a Mac runqlmanage -t review.xlsxfor a preview. Open it in LibreOffice or Excel when one is installed.Hand over the file with three lines: where it is, one line per sheet (name, rows, columns), and anything kept as text that the user might expect to be a number.
Non-interactive runs (subagent, CI, headless): with no data there is nothing to convert.
Emit BLOCKED: need the table data (a .md, .csv or .json file, or pasted tables) and write
nothing. Formulas stay off unless the request says otherwise, noted as an [assumption].
How cells are typed
| Cell text | In Excel |
|---|---|
1240, -3.5, 1,240,500, 1.2e6 |
Number. Thousands separators keep a #,##0 format |
12.5%, -4% |
Number 0.125, -0.04, shown as a percentage with the same decimals |
$1,240.00, £86, €9.50 |
Number with that currency format |
2026-09-30, 2026-09-30T14:30 |
Date or date-time, shown yyyy-mm-dd (time zone offsets dropped, with a warning) |
true, FALSE |
Boolean |
00412, 02134 (leading zero), 16+ digit numbers |
Text, because Excel would strip the zero or round the digits |
=SUM(B2:B5) |
Text by default; a live formula with --formulas |
Anything else, including n/a, 1.234,50, 30/09/2026 |
Text |
In Markdown cells, **bold**, `code`, links and images are reduced to their text, and
<br> becomes a line break inside a wrapped cell. JSON numbers and booleans keep their type,
except integers over 15 digits, which become text.
JSON strings stay text except ISO dates, because whoever produced the JSON chose a string.
Useful references in this skill
reference.md: typing rules in full, sheet-name rules, the workbook parts written, and Excel's limitsscripts/md_to_xlsx.py: the converter (stdlib only, Python 3.9+)examples/vendor-review.md: worked example, three Markdown tables become three typed sheets after the headings are fixed
Quality bar
- Numbers are numbers. Amounts, counts and percentages sum and sort in Excel. The per-sheet counts in the summary back this up.
- Identifiers keep their zeros. Vendor IDs, ZIP codes and account numbers come out exactly as written.
- Every sheet name means something. Named from the table's heading, not "Table 3", and no name cut down by the script without you saying so.
- Formulas are off unless the user chose them, and the reason is given when a cell starting with
=is kept as text. - No data changes. You fix headings, units and number formats, but never a value: no rounding, no filled-in blanks, no invented rows.
- The header row is bold, frozen and filtered on every sheet, and the file was reopened to check.
When to use this skill
- ✅ Markdown tables from a report or an agent's analysis that someone needs to work with in Excel
- ✅ A CSV export that should open with proper number and date types instead of Excel's guesses
- ✅ A JSON array from an API or a script, as a sheet a non-developer can filter
When NOT to use this skill
- ❌ A document with a few tables in it, to be read rather than calculated; use
md-to-docx - ❌ An Excel file back to Markdown or CSV; use
file-to-markdown - ❌ A slide of numbers for a meeting; put the table in the Markdown and use
md-to-pptx - ❌ Building a financial model with formulas, scenarios and linked sheets. This converts data; it doesn't design models.
Anti-patterns to avoid
- ❌ Turning on
--formulasfor an export or a scraped table because "it had formulas in it". That's exactly the file formula injection comes in. - ❌ Letting the script name sheets "Table 1", "Table 2". Add a heading above each table; it takes ten seconds.
- ❌ Typing
1,240kor3.4 hin number columns. Put the unit in the header so the column is numeric. - ❌ "Fixing" leading zeros by converting IDs to numbers.
00412and412are different vendors. - ❌ Skipping the per-sheet counts. "8 numbers, 13 text" on a sheet of amounts is the tell that a column didn't convert.
- ❌ Filling blanks with 0 or "N/A" to make a column look complete. Empty stays empty.