# CSV Excel File

> Guidelines for handling CSV/Excel files Use when this capability is needed.

- Skill: `tomevault-io/csv-excel-file` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/csv-excel-file`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/csv-excel-file/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/csv-excel-file

---


# CSV/Excel Handling Specifications

## Goals

- Safely load tabular data without crashing.
- Detect and handle messy spreadsheets (multiple blocks, missing headers, merged cells artifacts).
- Produce reliable outputs (clean dataframe for clean table or structured JSON for messy spreadsheet) with validated types.

## Encoding, Delimiters, and Locale

- CSV encoding: Try UTF-8; if garbled, attempt common fallbacks (e.g., gbk, cp1252) based on context.
- Delimiters: Detect common separators (,, \t, ;, |) during inspection.
- Locale formats: Be cautious with comma decimal separators and thousands separators.

## Inspection (always first)

- Identify file type, encoding (CSV), and sheet names (Excel) before full reads.
- Prefer small reads to preview structure:
  - CSV: pd.read_csv(..., nrows=20); if uncertain delimiter: sep=None, engine="python" (small nrows only).
  - Excel: pd.ExcelFile(path).sheet_names, then pd.read_excel(..., sheet_name=..., nrows=20).
- Use df.head(n) and df.columns to check:
  - Missing/incorrect headers (e.g., columns are numeric 0..N-1)
  - "Unnamed: X" columns
  - Unexpected NaN/NaT, merged-cell artifacts
  - Multiple tables/blocks in one sheet (blank rows separating sections)

## Preprocessing

- Treat as messy if any of the following is present:
  - Columns contain "Unnamed:" or mostly empty column names
  - Header row appears inside the data (first rows look like data + later row looks like header)
  - Multiple data blocks (large blank-row gaps, repeated header patterns)
  - Predominantly NaN/NaT in top rows/left columns
  - Notes/metadata blocks above/beside the table (titles, footnotes, merged header areas)
- If messy spreadsheets are detected:
  - First choice: use  `clean_messy_spreadsheet` tool to extract key tables/fields and output JSON.
  - Only fall back to manual parsing if tool fails, returns empty/incorrect structure, or cannot locate the target table.

## Querying

- Never load entire datasets blindly.
- Use minimal reads:
  - `nrows`, `usecols`, `dtype` (or partial dtype mapping), `parse_dates` only when necessary.
  - Sampling: `skiprows` with a step pattern for rough profiling when file is huge.
- For very large CSV:
  - Prefer `chunksize` iteration; aggregate/compute per chunk.
- For Excel:
  - Read only needed `sheet_name`, and consider narrowing `usecols`/`nrows` during exploration.

## Data Quality & Type Validation

- After load/clean:
  - Validate types:
    - Numeric columns: coerce with pd.to_numeric(errors="coerce")
    - Datetime columns: pd.to_datetime(errors="coerce")
  - Report coercion fallout (how many became NaN/NaT).
  - Standardize missing values: treat empty strings/“N/A”/“null” consistently.

# Best Practices

- Always inspect structure before processing.
- Handle encoding issues appropriately
- Keep reads minimal; expand only after confirming layout.
- Log decisions: chosen sheet, detected header row, dropped columns/rows, dtype conversions.
- Avoid silent data loss: when dropping/cleaning, summarize what changed.
- Validate data types after loading

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/agentscope-ai) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->