Convert Excel to Markdown
Converts .xlsx workbooks into Markdown folders with sheet tables and extracted embedded images, then reads the Markdown output to perform the user's requested analysis instead of parsing zipped Excel XML directly.
When to invoke
- "Read this spreadsheet."
- "Summarize or analyze this .xlsx workbook."
- "Extract data from this budget, tracker, or export."
- "Convert a folder of Excel workbooks to Markdown."
- "Process this folder with .pdf, .docx, and .xlsx files."
Prerequisites and context
- The script supports
.xlsx only. For legacy .xls, ask the user to re-save as .xlsx using Excel: File > Save As > Excel Workbook (.xlsx).
- Before first use in an environment, follow
references/setup.md to ensure Python, pip, and markitdown are installed.
- The conversion script is
scripts/convert_excel_to_md.py.
- Always run the bundled script first; do not parse
.xlsx directly or write ad-hoc extraction code.
- After conversion, read the generated
.md files to perform the requested analysis.
Procedure
- Resolve the source path. If the file path cannot be fully resolved, use
ask_user or the host's confirmation mechanism to obtain the full absolute path before conversion.
- If the source is a folder with mixed
.pdf, .docx, and .xlsx files, invoke convert-pdf-to-md, convert-word-to-md, and convert-excel-to-md so no supported type is skipped.
- Run
scripts/convert_excel_to_md.py on the file or folder.
- Use default output next to the source unless the user explicitly provides an output path.
- Use
--recursive only when subfolders should be included.
- Read the resulting Markdown and image links before answering the user's data question.
Conversion commands
python scripts\convert_excel_to_md.py "C:\path\to\workbook.xlsx"
python scripts\convert_excel_to_md.py "C:\path\to\workbook.xlsx" -o "C:\path\to\output_folder"
python scripts\convert_excel_to_md.py "C:\path\to\folder"
python scripts\convert_excel_to_md.py "C:\path\to\folder" --recursive
python scripts\convert_excel_to_md.py "C:\path\to\folder" --recursive -o "C:\path\to\output_parent"
Use -o only when the user explicitly says where to save output, such as C:\output or D:\work. Do not choose -o based on the agent current working directory, session state folder, or implied location.
Output structure and limitations
| Feature |
Behavior |
| Workbook output |
A <name>/ folder is created next to the source .xlsx by default. |
| Markdown file |
<name>/<name>.md contains each sheet as its own ## <SheetName> Markdown table. |
| Images |
Real embedded raster pictures are extracted into <name>/img/ and inserted after each sheet table under #### Images in this sheet. |
| Image filenames |
sheet001_<sheetname>_img001.<ext>, sheet002_<sheetname>_img001.<ext>, and so on. |
| Placement accuracy |
Images are placed per sheet, not exact cell position, because MarkItDown anchors stable output at ## <SheetName>. |
| No images |
No img/ folder or image sections are created. |
| Charts |
Native Excel charts are not extracted; only real embedded pictures are extracted. |
| Batch mode |
Each .xlsx gets its own <name>/ output folder; with -o, generated folders are collected under the output parent and subfolder structure is preserved with --recursive. |
| Non-Excel files |
Folder conversion intentionally skips non-.xlsx files and reports NOTE: skipped N non-.xlsx file(s). |
Troubleshooting
| Symptom |
Likely cause |
Resolution |
ModuleNotFoundError: No module named 'markitdown' / exit code 2 |
MarkItDown is not installed. |
Follow references/setup.md. |
ERROR: Unsupported file type '.xls' / exit code 3 |
Legacy .xls, not .xlsx. |
Ask the user to re-save as .xlsx. |
ERROR: Input path not found / exit code 3 |
Wrong path or moved file. |
Confirm the correct absolute path with the user. |
FAILED <file> -> ... in batch output |
That workbook is corrupt, password-protected, or unreadable. |
Report failed files; other batch files may still succeed. |
NOTE: skipped N non-.xlsx file(s) |
Folder contains non-Excel files. |
Expected for this skill; invoke sibling skills for .pdf and .docx. |
| A sheet's charts do not appear as images |
Charts are chart objects, not embedded raster images. |
Expected limitation; explain if the user needs chart images. |
Progressive disclosure and bundled resources
references/setup.md: Python, pip, and MarkItDown setup.scripts/convert_excel_to_md.py: deterministic Excel-to-Markdown conversion with embedded picture extraction.scripts/requirements.txt: Python package requirements for the script.
Related primitives
| Name |
Type |
Use it when |
convert-pdf-to-md |
skill |
The input set contains .pdf files. |
convert-word-to-md |
skill |
The input set contains .docx files. |
Excel conversion invariants
IMPORTANT: the agent MUST convert before analysis. MarkItDown's XLSX output is self-contained in <name>\, such as workbook\, workbook.md, and workbook\img\. Image placement is per-sheet; native charts require Excel/LibreOffice rendering and are out of scope. Batch output can use -o "C:\path\to\output_parent" only when the user explicitly requests it.
Output template
### Excel to Markdown conversion result
**Status:** converted | partially converted | blocked
**Input:** `<file or folder>`
**Output:** `<name>/` or `<output_parent>/<name>/`
**Recursive:** yes | no
| Workbook | Markdown output | Images extracted | Notes |
| --- | --- | --- | --- |
| `<workbook.xlsx>` | `<name>/<name>.md` | `<count or none>` | `<success, skipped, or failure reason>` |
**Next analysis performed**
- <summary, extraction, comparison, chart review, or user-requested analysis>
**Validation**
- `python scripts\convert_excel_to_md.py ...`: pass | fail
Quality gate
1---2name: convert-excel-to-md-23description: Convert Excel .xlsx workbooks to Markdown with the bundled script so spreadsheet contents can be read, summarized, searched, extracted, compared, charted, or analyzed. Use whenever the user references a spreadsheet, workbook, budget, export, tracker, .xlsx file, or a folder of workbooks; invoke sibling converters for mixed .pdf, .docx, and .xlsx sets.4---56# Convert Excel to Markdown78Converts `.xlsx` workbooks into Markdown folders with sheet tables and extracted embedded images, then reads the Markdown output to perform the user's requested analysis instead of parsing zipped Excel XML directly.910## When to invoke1112- "Read this spreadsheet."13- "Summarize or analyze this .xlsx workbook."14- "Extract data from this budget, tracker, or export."15- "Convert a folder of Excel workbooks to Markdown."16- "Process this folder with .pdf, .docx, and .xlsx files."1718## Prerequisites and context1920- The script supports `.xlsx` only. For legacy `.xls`, ask the user to re-save as `.xlsx` using Excel: File > Save As > Excel Workbook (.xlsx).21- Before first use in an environment, follow `references/setup.md` to ensure Python, pip, and `markitdown` are installed.22- The conversion script is `scripts/convert_excel_to_md.py`.23- Always run the bundled script first; do not parse `.xlsx` directly or write ad-hoc extraction code.24- After conversion, read the generated `.md` files to perform the requested analysis.2526## Procedure27281. Resolve the source path. If the file path cannot be fully resolved, use `ask_user` or the host's confirmation mechanism to obtain the full absolute path before conversion.292. If the source is a folder with mixed `.pdf`, `.docx`, and `.xlsx` files, invoke `convert-pdf-to-md`, `convert-word-to-md`, and `convert-excel-to-md` so no supported type is skipped.303. Run `scripts/convert_excel_to_md.py` on the file or folder.314. Use default output next to the source unless the user explicitly provides an output path.325. Use `--recursive` only when subfolders should be included.336. Read the resulting Markdown and image links before answering the user's data question.3435## Conversion commands3637```powershell38python scripts\convert_excel_to_md.py "C:\path\to\workbook.xlsx"39python scripts\convert_excel_to_md.py "C:\path\to\workbook.xlsx" -o "C:\path\to\output_folder"40python scripts\convert_excel_to_md.py "C:\path\to\folder"41python scripts\convert_excel_to_md.py "C:\path\to\folder" --recursive42python scripts\convert_excel_to_md.py "C:\path\to\folder" --recursive -o "C:\path\to\output_parent"43```4445Use `-o` only when the user explicitly says where to save output, such as `C:\output` or `D:\work`. Do not choose `-o` based on the agent current working directory, session state folder, or implied location.4647## Output structure and limitations4849| Feature | Behavior |50| --- | --- |51| Workbook output | A `<name>/` folder is created next to the source `.xlsx` by default. |52| Markdown file | `<name>/<name>.md` contains each sheet as its own `## <SheetName>` Markdown table. |53| Images | Real embedded raster pictures are extracted into `<name>/img/` and inserted after each sheet table under `#### Images in this sheet`. |54| Image filenames | `sheet001_<sheetname>_img001.<ext>`, `sheet002_<sheetname>_img001.<ext>`, and so on. |55| Placement accuracy | Images are placed per sheet, not exact cell position, because MarkItDown anchors stable output at `## <SheetName>`. |56| No images | No `img/` folder or image sections are created. |57| Charts | Native Excel charts are not extracted; only real embedded pictures are extracted. |58| Batch mode | Each `.xlsx` gets its own `<name>/` output folder; with `-o`, generated folders are collected under the output parent and subfolder structure is preserved with `--recursive`. |59| Non-Excel files | Folder conversion intentionally skips non-.xlsx files and reports `NOTE: skipped N non-.xlsx file(s)`. |6061## Troubleshooting6263| Symptom | Likely cause | Resolution |64| --- | --- | --- |65| `ModuleNotFoundError: No module named 'markitdown'` / exit code 2 | MarkItDown is not installed. | Follow `references/setup.md`. |66| `ERROR: Unsupported file type '.xls'` / exit code 3 | Legacy `.xls`, not `.xlsx`. | Ask the user to re-save as `.xlsx`. |67| `ERROR: Input path not found` / exit code 3 | Wrong path or moved file. | Confirm the correct absolute path with the user. |68| `FAILED <file> -> ...` in batch output | That workbook is corrupt, password-protected, or unreadable. | Report failed files; other batch files may still succeed. |69| `NOTE: skipped N non-.xlsx file(s)` | Folder contains non-Excel files. | Expected for this skill; invoke sibling skills for `.pdf` and `.docx`. |70| A sheet's charts do not appear as images | Charts are chart objects, not embedded raster images. | Expected limitation; explain if the user needs chart images. |7172## Progressive disclosure and bundled resources7374- `references/setup.md`: Python, pip, and MarkItDown setup.75- `scripts/convert_excel_to_md.py`: deterministic Excel-to-Markdown conversion with embedded picture extraction.76- `scripts/requirements.txt`: Python package requirements for the script.7778## Related primitives7980| Name | Type | Use it when |81| --- | --- | --- |82| `convert-pdf-to-md` | skill | The input set contains `.pdf` files. |83| `convert-word-to-md` | skill | The input set contains `.docx` files. |8485## Excel conversion invariants8687`IMPORTANT`: the agent `MUST` convert before analysis. MarkItDown's `XLSX` output is `self-contained` in `<name>\`, such as `workbook\`, `workbook.md`, and `workbook\img\`. Image placement is `per-sheet`; native charts require `Excel/LibreOffice` rendering and are out of scope. Batch output can use `-o "C:\path\to\output_parent"` only when the user explicitly requests it.8889## Output template9091```markdown92### Excel to Markdown conversion result9394**Status:** converted | partially converted | blocked95**Input:** `<file or folder>`96**Output:** `<name>/` or `<output_parent>/<name>/`97**Recursive:** yes | no9899| Workbook | Markdown output | Images extracted | Notes |100| --- | --- | --- | --- |101| `<workbook.xlsx>` | `<name>/<name>.md` | `<count or none>` | `<success, skipped, or failure reason>` |102103**Next analysis performed**104- <summary, extraction, comparison, chart review, or user-requested analysis>105106**Validation**107- `python scripts\convert_excel_to_md.py ...`: pass | fail108```109110## Quality gate111112- [ ] The bundled script `scripts/convert_excel_to_md.py` was used before analysis.113- [ ] The input path was fully resolved; ambiguous paths were confirmed with `ask_user` or equivalent.114- [ ] `.xls` files were rejected with re-save guidance.115- [ ] Default output stayed next to the source unless the user explicitly requested `-o`.116- [ ] Mixed `.pdf`, `.docx`, and `.xlsx` sets invoked the sibling converters.117- [ ] Generated `.md` files were read before answering the user's content question.118- [ ] Failures in batch mode were reported without hiding successful conversions.
paulasilvatech