Converts Excel (.xlsx) workbooks into Markdown tables and extracts embedded images for easier data analysis and processing.
- GitHub stars
- 41,038
- Files
- 4
- Last commit
- Nov 11, 2026
- License
- MIT
- Allowed tools
- —
What does the convert-excel-to-md skill do?
convert-excel-to-md converts Excel (.xlsx) workbooks into Markdown tables and extracts embedded images for easier data analysis and processing.
Summary generated from the skill's SKILL.md.
About the convert-excel-to-md skill
Transforming Excel workbooks into Markdown tables is what this skill enables for developers and analysts who need to process spreadsheet data through text-based AI models. Because the .xlsx format is a zipped XML bundle that is difficult to read as plain text, this tool uses a conversion script to produce structured Markdown files. It is designed for agents that need to summarize, search, or extract specific values from budgets, trackers, or data exports.
When an agent encounters a .xlsx file, it runs the conversion to create a Markdown file where each sheet is represented by a heading and a table. Unlike standard converters, this skill also identifies and extracts embedded raster images, placing them in a dedicated folder and linking them directly under the relevant sheet heading in the Markdown output. It relies on the markitdown package and a Python script to perform these tasks.
This skill is intended for .xlsx files only and cannot process legacy .xls formats. If a user provides a folder containing mixed file types like PDFs or Word documents, the agent should use this skill alongside sibling tools to ensure no data is skipped. It handles single files or entire directories, including subfolders when the recursive flag is used.
What an agent can do with it
- 1Summarize spreadsheet dataConvert a budget workbook into Markdown so the agent can provide a summary of the financial figures.
- 2Extract embedded imagesRetrieve raster pictures embedded within an Excel sheet and save them alongside the converted text.
- 3Batch process workbooksConvert every Excel file found within a specific directory and its subdirectories into Markdown format.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the convert-excel-to-md skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the convert-excel-to-md skill in Claude Code
~/.claude/skills/convert-excel-to-md/SKILL.md
$ npx degit github/awesome-copilot/skills/convert-excel-to-md ~/.claude/skills/convert-excel-to-mdInstall the convert-excel-to-md skill in Claude Code (project)
.claude/skills/convert-excel-to-md/SKILL.md
$ npx degit github/awesome-copilot/skills/convert-excel-to-md .claude/skills/convert-excel-to-mdInstall the convert-excel-to-md skill in Codex
~/.agents/skills/convert-excel-to-md/SKILL.md
$ npx degit github/awesome-copilot/skills/convert-excel-to-md ~/.agents/skills/convert-excel-to-mdInstall the convert-excel-to-md skill in Gemini CLI
~/.gemini/skills/convert-excel-to-md/SKILL.md
$ npx degit github/awesome-copilot/skills/convert-excel-to-md ~/.gemini/skills/convert-excel-to-mdInstall the convert-excel-to-md skill in Claude.ai
npx degit github/awesome-copilot/skills/convert-excel-to-md convert-excel-to-md && zip -r convert-excel-to-md.zip convert-excel-to-md # claude.ai → Customize → Skills → + → Create skill → Upload a skill → convert-excel-to-md.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablegithub/awesome-copilot/skills/convert-excel-to-md is public and reachablegithub.com/github/awesome-copilot/tree/HEAD/skills/convert-e ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-11github.com/github/awesome-copilot/commits ↗Pass
- No download-and-run or credential theft in scripts1 script read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/github/awesome-copilot/blob/HEAD/skills/convert-e ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/github/awesome-copilot/blob/HEAD/skills/convert-e ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 132 linesgithub.com/github/awesome-copilot/blob/HEAD/skills/convert-e ↗Pass
SKILL.md
View on GitHubConvert Excel to Markdown
When to use this skill
Trigger this skill any time there is a .xlsx file that needs to be
understood or processed — for example, a user attaches a spreadsheet and
asks questions about it, wants a summary of the data, wants specific rows or
values pulled out, or wants multiple workbooks in a folder processed
together. Excel's native .xlsx format is a zipped XML bundle that is not
reliably readable as plain text, so always convert it to Markdown first
using the script in this skill rather than trying to open or parse the file
directly.
This skill only supports .xlsx. If asked to convert a legacy .xls file,
tell the user it isn't supported and ask them to re-save it as .xlsx
(Excel: File > Save As > Excel Workbook (.xlsx)) first.
Mixed file types: When the user references a folder or set of documents
containing multiple supported file types (.pdf, .docx, .xlsx), this
skill handles only .xlsx files. The agent MUST also invoke the sibling
skills in parallel:
convert-pdf-to-mdfor any.pdffilesconvert-word-to-mdfor any.docxfiles
Never process a folder and silently skip a supported file type. All three skills must be invoked together when mixed types are present.
Setup (once per environment)
Before the first conversion in a given environment, follow
references/setup.md step by step to ensure Python,
pip, and the markitdown package are installed. Do this proactively rather
than guessing whether the environment is ready — the script itself will
also fail with a clear pointer back to that file if markitdown turns out
to be missing, so it's safe to just try the conversion first if you're
reasonably confident setup was already done.
Usage
The conversion script lives at scripts/convert_excel_to_md.py.
Output structure: MarkItDown's XLSX converter renders each sheet as its
own ## <SheetName> Markdown table — it has no support for embedded images
at all. This script separately extracts real embedded images (raster
pictures, not charts) and maps them to the sheet they belong to, writing a
self-contained folder per document:
<name>/
img/
sheet001_<sheetname>_img001.<ext>
sheet002_<sheetname>_img001.<ext>
...
<name>.md (each sheet's images appear right after its table,
under a "#### Images in this sheet" heading)
This is per-sheet placement, not exact cell position — the finest
granularity MarkItDown's stable output anchors (the ## <SheetName>
headings) allow. If a workbook has no embedded images, no img/ folder or
image sections are created. Native Excel charts are not extracted as
images (only actual embedded pictures are — charts would need to be
rendered by Excel/LibreOffice, which this lightweight skill does not do).
Single file:
python scripts\convert_excel_to_md.py "C:\path\to\workbook.xlsx"
This creates a workbook\ folder next to the source file (containing
workbook.md and, if present, workbook\img\). To control the destination
folder explicitly:
python scripts\convert_excel_to_md.py "C:\path\to\workbook.xlsx" -o "C:\path\to\output_folder"
A folder of workbooks (batch mode):
python scripts\convert_excel_to_md.py "C:\path\to\folder"
Add --recursive to also include subfolders:
python scripts\convert_excel_to_md.py "C:\path\to\folder" --recursive
Each .xlsx found gets its own <name>\ output folder next to it by
default. Pass -o "C:\path\to\output_parent" to collect all the generated
<name>\ folders under a separate parent directory instead (subfolder
structure is preserved when combined with --recursive).
After conversion, read the resulting .md file(s) to perform the actual
analysis the user asked for — the script's job is only to produce accurate
Markdown (and images), not to interpret the content.
Deciding where output goes
Default — always output next to the source file. The <name>/ folder
is created in the same directory as the source .xlsx. This is the required
default for every case. Do NOT override it unless the user explicitly asks
for a different location.
Only use -o when the user explicitly provides an output path (e.g.,
"save the output to C:\output", "put the results in D:\work"). Do NOT
pass -o based on the agent's current working directory, the session state
folder, or any implied location.
If the source file path cannot be fully resolved — for example, the
user provides only a filename with no directory, or the path is ambiguous —
use ask_user to confirm the full absolute path before running the
conversion. Never guess or assume the directory.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
ModuleNotFoundError: No module named 'markitdown' / exit code 2 |
MarkItDown 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 file moved | Confirm the correct path with the user |
FAILED <file> -> ... in batch output |
That specific file is corrupt, password-protected, or otherwise unreadable | Report which file(s) failed; other files in the batch still succeed |
NOTE: skipped N non-.xlsx file(s) |
Folder contains non-Excel files | Expected — those files are intentionally ignored |
| A sheet's charts don't appear as images | Charts are chart objects, not embedded pictures — this skill only extracts real embedded raster images | Expected; mention this limitation if the user specifically needs chart images |
Files in this skill
4convert-excel-to-md skill questions
How do I install the convert-excel-to-md skill in Claude Code?
Run npx degit github/awesome-copilot/skills/convert-excel-to-md ~/.claude/skills/convert-excel-to-md. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the convert-excel-to-md skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
Does this skill support legacy .xls files?
No, it only supports .xlsx files. You must ask the user to re-save legacy files as .xlsx first.
Can the tool extract Excel charts as images?
No, it only extracts real embedded raster images. Native Excel charts are not extracted as images.
How are multiple sheets handled in the output?
Each sheet is rendered as its own Markdown table under a specific heading.
Can I convert an entire folder of Excel files at once?
Yes, the skill supports batch mode for folders and can process subfolders recursively.