---
name: excel-operations
description: Read, write, and manipulate Excel (.xlsx) and CSV files
---

## When to use
Use when the user asks to:
- Read data from Excel or CSV files
- Create new spreadsheets
- Update existing spreadsheet data
- Perform calculations or data transformations
- Export data to CSV/Excel format
- Validate spreadsheet structure

## Workflow

### 1. Identify the file
Determine file path and format (.xlsx, .csv, .tsv).

### 2. Read the data

OpenClaw's `read` is for text files. For Excel/CSV:

**For CSV** (plain text):
```bash
read path/to/data.csv
```

**For .xlsx** (binary): Use Python or other tools:
```bash
python -c "
import pandas as pd, json, sys;
df = pd.read_excel('data.xlsx');
print(df.to_json(orient='records'))
"
```

Or install `xlsx2csv` and convert first:
```bash
xlsx2csv data.xlsx temp.csv
read temp.csv
```

### 3. Process the data
- Parse into structured format (list of objects, 2D array)
- Validate headers/columns if needed
- Perform transformations (filter, map, aggregate)

### 4. Write results

**For CSV**:
```bash
write output.csv --data "$csv_string"
```

**For .xlsx**: Use Python:
```bash
python -c "
import pandas as pd, json, sys;
data = json.loads(sys.argv[1]);
pd.DataFrame(data).to_excel('output.xlsx', index=False)
" "$structured_data"
```

## Supported Formats
- **.xlsx** (Excel Open XML) — full support for sheets, formulas, formatting
- **.csv** (Comma-separated) — plain text, delimiter detection
- **.tsv** (Tab-separated) — tab delimiter

## Common Operations

### Read specific sheet
```bash
read file.xlsx --sheet "Sheet2"
```

### Read with range
```bash
read file.xlsx --range "A1:D100"
```

### Write with formatting
```bash
write report.xlsx \
  --data "$table" \
  --header true \
  --autofit columns
```

### Append to existing file
```bash
write file.xlsx --data "$new_rows" --append true
```

## Data Structures

**Reading returns**:
```json
{
  "headers": ["Name", "Email", "Score"],
  "rows": [
    {"Name": "Alice", "Email": "a@example.com", "Score": 95},
    ...
  ]
}
```

**Writing accepts**:
- JSON array of objects
- 2D array (array of arrays)
- CSV string (if format=csv)

## Examples

<Good>
User: "Tạo báo cáo điểm từ scores.csv"
Assistant:
1. Đọc scores.csv
2. Tính toán điểm trung bình, xếp loại
3. Ghi vào report.xlsx với định dạng đẹp
4. Trả về đường dẫn file và tóm tắt kết quả
</Good>

<Bad>
Ghi đè file gốc mà không backup, không thông báo.
</Bad>

## Error Handling
- **File not found**: Kiểm tra đường dẫn, dùng `glob` để tìm
- **Format mismatch**: Đảm bảo file đúng định dạng, kiểm tra extension
- **Large files**: Có thể cần chunk processing, kiểm tra memory limits
- **Corrupted data**: Catch parse errors, report specific row/column

## Validation Checklist
- [ ] File exists and is readable
- [ ] Format matches extension
- [ ] Headers are present and correct
- [ ] Data types are correct (numbers, dates, strings)
- [ ] No missing values in required columns
- [ ] Output file is well-formed and complete