How to use the Convert Excel to Markdown agent skill

What an agent skill is and what this one does

An agent skill is a folder of instructions and optional scripts that an AI agent can load when a task matches it. This skill covers .xlsx workbooks. An .xlsx file is a compressed bundle of XML, which agents cannot read reliably as plain text, so the skill tells the agent to run a conversion script first.

The script converts each sheet into a Markdown table and saves any embedded pictures as image files. It writes everything into a folder next to the original workbook. The agent then reads that Markdown to summarize, search, compare or extract data.

• Handles .xlsx files only. Legacy .xls files are rejected; re-save them as .xlsx first.
• Extracts embedded raster pictures, but not native Excel charts.
• Output is a plain Markdown snapshot, so formulas and formatting are not preserved.

Install the skill (ZIP download or Claude apps)

Download the ZIP for this skill from this page and unzip it. For Claude Code, place the unzipped skill folder in ~/.claude/skills/ to make it available for you everywhere, or in a project's .claude/skills/ folder to limit it to that project.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills

Set up Python and markitdown once

The script needs Python 3, pip and Microsoft's markitdown package with Excel support. The skill's references/setup.md file lists the exact steps, which you should follow in order. The package requirement is listed in scripts/requirements.txt as markitdown[xlsx] with a minimum version of 0.1.0.

The setup file asks for Python 3.10 or newer. If the script fails with a missing markitdown module, return to that file.

• Check Python with python --version
• Check pip with python -m pip --version
• If pip is missing, run python -m ensurepip --upgrade

Trigger the skill with natural requests

You do not need to say 'convert' or 'markdown'. The skill is written to trigger on requests to read, summarize, review, extract data from, compare, chart or analyze a spreadsheet, workbook, budget, data export or tracker that is a .xlsx file.

If you reference a folder that contains .pdf, .docx and .xlsx files, the agent is meant to invoke the sibling skills convert-pdf-to-md and convert-word-to-md alongside this one.

• 'Summarize the monthly budget in Q3-budget.xlsx.'
• 'Pull every row from the Orders sheet where the status is late.'
• 'Compare these two trackers and list what changed.'
• 'Process all the workbooks in this folder.'

How the conversion runs

For a single file, the script creates a folder named after the workbook next to the source file. That folder holds the Markdown file and, if the workbook has embedded pictures, an img folder. Each sheet appears as its own table under a sheet heading, and its images appear after its table.

For a folder, the script converts each .xlsx it finds. Add --recursive to include subfolders. Non-Excel files are skipped and reported. Output stays next to each source file unless you pass -o with a path you choose.

• Default output: next to the source file, always.
• -o sets a destination only when you give an explicit path.
• Image placement is per sheet, not exact cell position.

Safety: scripts and network

This skill runs a Python script on your machine. The listed requirements say it runs scripts and does not use the network. Still, review scripts/convert_excel_to_md.py before you use it on sensitive or confidential spreadsheets, because the script executes locally and processes your data.

If you do not want code run locally, or do not want data handled this way, do not use this skill for that file.

• Read the script before first use on confidential data.
• The skill is listed as not using the network.
• Original workbooks are read, not changed; output goes to new files.

Tips for better results

Give the full path to the workbook. If the agent cannot resolve the path, it is supposed to ask you to confirm it rather than guess. Expect that charts will not show up as images, and say so if you need chart images. If a batch has a corrupt or password-protected file, the others still convert and that file is reported.

• Use full absolute paths, such as C:\path\to\workbook.xlsx.
• Ask a specific question, such as which rows exceed a value, for better answers.
• If a file fails, check whether it is password-protected or corrupt.