# Excel Debug Extraction

Iteratively debug Excel structure with exploratory scripts before writing extraction logic

- Repository: https://github.com/HKUDS/AgentPilot (7784 stars)
- Category: Documents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add HKUDS/AgentPilot --skill excel-debug-extraction -g -a claude-code -y`
Codex: `npx skills add HKUDS/AgentPilot --skill excel-debug-extraction -g -a codex -y`
Cursor: `npx skills add HKUDS/AgentPilot --skill excel-debug-extraction -g -a cursor -y`
Gemini CLI: `npx skills add HKUDS/AgentPilot --skill excel-debug-extraction -g -a gemini-cli -y`

## Description

Iteratively debug Excel structure with exploratory scripts before writing extraction logic

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Excel Debug-First Extraction Workflow

When working with poorly-structured, complex, or unfamiliar Excel files, use this iterative debugging approach to map the data layout before writing your final extraction logic.

## When to Use This Skill

- Excel files with inconsistent formatting or merged cells
- Files received from external sources with unknown structure
- Complex workbooks with multiple sheets and interdependencies
- When initial parsing attempts fail or produce unexpected results

## Workflow Steps

### Step 1: Initial Structure Reconnaissance

Before writing extraction logic, create a debug script to explore the file structure:

```python
# debug_structure.py
from openpyxl import load_workbook

wb = load_workbook('file.xlsx')
print(f"Sheets: {wb.sheetnames}")

for sheet_name in wb.sheetnames:
    ws = wb[sheet_name]
    print(f"\n=== Sheet: {sheet_name} ===")
    print(f"Dimensions: {ws.dimensions}")
    
    # Print first 10 rows to understand header structure
    for row in ws.iter_rows(min_row=1, max_row=10, values_only=True):
        print([str(cell)[:50] for cell in row])
```

### Step 2: Map Column Positions

Identify where key data fields are located:

```python
# debug_columns.py
from openpyxl import load_workbook

wb = load_workbook('file.xlsx')
ws = wb['Sheet1']

# Examine header row to find column indices
header_row = 1
column_map = {}

for col in ws.iter_cols(min_row=header_row, max_row=header_row):
    for cell in col:
        if cell.value:
            column_map[str(cell.value)] = cell.column_letter

print("Column mapping:", column_map)

# Sample data rows to verify structure
for row_num in range(2, min(6, ws.max_row + 1)):
    row_data = [ws.cell(row=row_num, column=col).value 
                for col in range(1, ws.max_column + 1)]
    print(f"Row {row_num}: {row_data}")
```

### Step 3: Identify Row Patterns

Understand how data rows are structured (e.g., summary rows, detail rows, blank separators):

The rest: https://github.com/HKUDS/AgentPilot/blob/HEAD/openspace/benchmarks/gdpval/skills/excel-debug-extraction/SKILL.md