claudeskill/skills/excel-to-markdown/SKILL.md

name, description

name

description

excel-to-markdown

Convert Excel (.xlsx, .xls) files to Markdown table format. Use for converting Excel documents to Markdown for display or documentation, extracting and analyzing Excel data in a structured format, processing Excel files with automatic data range detection, generating Markdown tables with optional row/column numbering, or handling partial conversions with specific row/column ranges. Triggered by requests like "convert this Excel to Markdown", "export Excel as MD", "analyze this spreadsheet", or when working with .xlsx/.xls files that need to be viewed or processed as text.

Excel to Markdown Converter

Overview

Convert Excel spreadsheets to Markdown table format with automatic data range detection and flexible output options. The converter handles complex multi-sheet workbooks, preserves cell formatting, and can display row/column numbers for easy reference.

Quick Start

Basic Conversion

Convert an entire Excel file to Markdown:

python3 scripts/excel_to_markdown.py input.xlsx -o output.md

Specify Worksheet

Convert a specific worksheet by name or index:

# By worksheet name
python3 scripts/excel_to_markdown.py input.xlsx -o output.md --sheet "Sheet2"

# By worksheet index (1-based)
python3 scripts/excel_to_markdown.py input.xlsx -o output.md --sheet 2

Convert with Row/Column Numbers

Display Excel row and column identifiers for reference:

python3 scripts/excel_to_markdown.py input.xlsx -o output.md --show-rows --show-cols

Specify Data Range

Convert only a specific portion of the spreadsheet:

# Convert first 10 rows and 5 columns
python3 scripts/excel_to_markdown.py input.xlsx -o output.md -r 10 -c 5

# Start from row 2, column 3, convert 20 rows
python3 scripts/excel_to_markdown.py input.xlsx -o output.md --start-row 2 --start-col 3 -r 20

Command Line Options

Option	Description
input_file	Path to the Excel file (required)
-o, --output	Output Markdown file path (optional, prints to console if not specified)
-r, --max-rows	Maximum number of rows to convert (auto-detect if not specified)
-c, --max-cols	Maximum number of columns to convert (auto-detect if not specified)
--show-rows	Display row numbers in the first column
--show-cols	Display column letters (A, B, C...) in the first row
--start-row	Starting row number (default: 1)
--start-col	Starting column number (default: 1)
--sheet	Worksheet name or index (default: first worksheet)

Features

Automatic Data Range Detection

The converter automatically scans the spreadsheet to identify the actual data range (up to 100 rows and 100 columns by default), ignoring empty trailing rows and columns.

Cell Content Handling

• Empty cells are rendered as blank
• Pipe characters (|) in cell content are escaped as \|
• Newlines within cells are converted to <br> tags
• All cell values are trimmed of leading/trailing whitespace

Multi-Sheet Support

By default, the converter processes the first worksheet in the workbook. You can specify a different worksheet using the --sheet parameter:

• By name: --sheet "Sheet2" or --sheet "Data"
• By index: --sheet 2 (1-based indexing)

If the specified worksheet is not found, an error will display the list of available worksheets.

Common Use Cases

1. Data Analysis

Extract Excel data for analysis or processing:

python3 scripts/excel_to_markdown.py sales_data.xlsx -o sales_analysis.md

Then analyze the Markdown output or provide insights based on the structured data.

2. Documentation

Convert spreadsheets to Markdown for inclusion in documentation:

python3 scripts/excel_to_markdown.py specifications.xlsx -o specs.md --show-rows --show-cols

The row/column numbers make it easy to reference specific cells in documentation.

3. Quick Preview

Quickly view Excel contents without opening a spreadsheet application:

python3 scripts/excel_to_markdown.py report.xlsx

4. Partial Data Extraction

Extract specific sections from large spreadsheets:

# Get header row and first 10 data rows
python3 scripts/excel_to_markdown.py large_file.xlsx -o sample.md -r 11

Script Location

The converter script is located at: scripts/excel_to_markdown.py

Dependencies

The script requires openpyxl for Excel file processing:

pip install openpyxl