Skip to main content
skill CX Codex

spreadsheets — Claude Code skill: what it does, how to install

spreadsheets — a skill for CSV, TSV and .xlsx files: it inspects structure, edits only the rows you ask for and recalculates formulas. Use it when the table is the main input or output.

MIT 267 installs ★ 107 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add PaulRBerg/agent-skills --skill spreadsheets -a claude-code
Open on GitHub

What spreadsheets does

The skill kicks in when CSV, TSV or Excel (.xlsx) is the file the task revolves around: designing or reviewing text-table schemas, validating, transforming, converting, recalculating formulas, fixing existing sheets. If a table only shows up on the side, it stays out of the way.

Its rules are strict. Money amounts stay strings and are computed with decimal.Decimal or DuckDB DECIMAL(38, 18), never floats. Only the requested rows, columns, formulas and formatting change. Writes go to a sibling temp file, get validated, then replace the original. Cells from outside sources that begin with =, + or @ are escaped. For new text tables it prefers TSV in UTF-8 without a BOM.

Three scripts ship with it: peek.py for a quick look and strict checks, profile.py for a JSON profile (structure, header quality, formula prefixes), and recalc.py to recompute .xlsx formulas. Joins and pivots go through DuckDB, counts and frequencies through qsv, exact edits through Python. All scripts run via uv run, so uv has to be installed. Any .xlsx job starts with references/xlsx.md.

What it helps with

  • inspect an unfamiliar CSV before touching it
  • recalculate formulas in an .xlsx and confirm the file still opens clean
  • append rows to a TSV so a rerun adds no duplicates
  • join transaction exports in DuckDB without losing decimal precision
  • escape cells starting with = in an outside export before it reaches Excel

Example prompts for the agent

  • Use the spreadsheets skill to profile transactions.csv before I change anything
  • Add a totals column to report.xlsx, recalc the formulas and leave everything else alone
  • Join these two TSV files on id with DuckDB and keep the amounts exact

How to install spreadsheets

1Skills CLI (Vercel)

npx skills add PaulRBerg/agent-skills --skill spreadsheets -a claude-code

2Manually: put the files in place

~/.claude/skills/spreadsheets/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/spreadsheets/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about spreadsheets

How do I install spreadsheets in Claude Code?

Run npx skills add PaulRBerg/agent-skills --skill spreadsheets -a claude-code. The skill file lands at ~/.claude/skills/spreadsheets/SKILL.md.

What does spreadsheets do?

It handles CSV, TSV and .xlsx files: profiling, transforming, converting, schema checks and formula recalculation. Edits stay minimal, writes are atomic, and amounts avoid floats.

What does spreadsheets need to run, and when does it stay inactive?

The peek.py, profile.py and recalc.py scripts run through uv run. Column statistics show up when qsv is installed. When a table is incidental to the task, the skill does not trigger.

Source text

SKILL.md · MIT
---
argument-hint: "[file]"
name: spreadsheets
description:
  "Use when CSV, TSV, or Excel (.xlsx) is the primary input/output: design or review text-table schemas, inspect,
  transform, validate, convert, or recalc formulas, or create/fix spreadsheets. Do not trigger when tabular data is
  incidental."
---

# Spreadsheets

Handle tabular data with exact values, minimal diffs, recipient-scoped data handling, atomic writes, and structural
validation.

## Invariants

1. Keep precision-sensitive amounts as strings and compute with `decimal.Decimal` or DuckDB `DECIMAL(38, 18)`, never
   binary floats.
2. Touch only requested rows, columns, formulas, and formatting. Existing file conventions override house defaults.
3. For newly authored text tables, prefer TSV, UTF-8 without BOM, LF, one trailing newline, lowercase `snake_case`
   headers, ISO dates, `.` decimals, and `-` nulls.
4. Read unknown text tables with BOM-tolerant UTF-8. Never write a BOM.
5. Write in place atomically through a sibling temporary file, validate it, then replace the target.
6. Escape external cells beginning with `=`, `+`, or `@`. A bare `-` null is exempt. Formula-prefix cells in trusted
   authored data are observations, not proof of injection.
7. Treat transaction, bank, exchange, and tax data as user-owned. Use unredacted samples in internal agent reports when
   materially useful. For public or third-party disclosures, or when the user asks, use `--redact-samples`.

## Factual Profiling

Resolve helper paths from this `SKILL.md`. Profile unknown data before choosing a transformation tool:

```sh
uv run "<skill-dir>/scripts/profile.py" <file>
```

The JSON output has `schema_version: 2`. It reports structural facts, header quality, cardinality/statistics when qsv is
available, frequency facts, formula-prefix cells, workbook metadata, and local tool availability. It contains no tool
recommendations and does not infer identifiers from uniqueness. Choose the tool from the requested transformation,
provenance, output format, and preservation requirements.

Use `--external-data` only when the cells came from an external or otherwise untrusted source and will be written to a
formula-capable consumer. With that flag, formula-prefix cells affect `status`. Without it, legitimate formulas such as
`=SUM(...)` remain factual observations and do not fail the profile.

## Tool Routing

| Need                                        | Tool                                             |
| ------------------------------------------- | ------------------------------------------------ |
| Fast structural preview/validation          | `uv run "<skill-dir>/scripts/peek.py" <file>`    |
| Factual local quality profile               | `uv run "<skill-dir>/scripts/profile.py" <file>` |
| Counts, stats, frequencies, select, dedupe  | `qsv`                                            |
| Joins, pivots, aggregation, conversion      | DuckDB with `all_varchar = true`                 |
| Exact custom transforms                     | `uv run` Python, stdlib `csv`, `decimal.Decimal` |
| New text table or intentional schema change | Read `references/text-table-design.md` first     |
| Any `.xlsx`/`.xlsm` input or output         | Read `references/xlsx.md` first                  |
| Exact transformation/validation recipes     | Read `references/recipes.md` only when needed    |

Prefer `qsv --cache-threshold 0` where supported. When qsv stdout must remain TSV, use `-o out.tsv`. Otherwise, stdout
defaults to CSV.

## Workflow

1. For a new text table or intentional schema change, read `references/text-table-design.md` and record the intended
   table interface plus migration surface.
2. Inspect with `peek.py`. When cardinality, formula prefixes, metadata, or available tooling matters, add `profile.py`.
   For a no-shape-change edit, save the peek JSON. For intentional row/schema changes, record the expected width and
   invariants.
3. Decide whether formula-prefix cells are dangerous from provenance and output context. Decide the smallest tool that
   preserves values and formatting. Avoid pandas unless necessary. If you use it, load every column as strings.
4. Apply the transformation atomically. For idempotent appends with legitimate duplicate rows, use multiset difference
   rather than set deduplication.
5. Validate:
   - unchanged shape: `peek.py --strict --expect-like <before-report>`.
   - changed shape: `peek.py --strict --expect-columns <n>` plus task-specific counts/keys.
   - authored house TSV: add `--house`.
   - formulas: `uv run "<skill-dir>/scripts/recalc.py" <file.xlsx>` and require success.
6. Report paths, row/column effects, validation, and any workbook features that could not be preserved.

For human output, lead with `### 📊 Spreadsheet — ✅ updated` only after the write and required validation pass, or
`### 📊 Spreadsheet — 🔎 inspected, no files written` for read-only work. On required validation failure, use
`### 📊 Spreadsheet — ⛔ not deliverable`. Include profile JSON only when it materially supports the report, and keep
JSON, cells, headers, formulas, paths, commands, and diagnostics undecorated.

## Generated Financial Artifacts

Treat generated financial tables and reports as outputs. Before editing, identify their source inputs and the
project-provided validation and regeneration commands. Edit only the sources, validate them, then regenerate affected
outputs. Never hand-edit generated tables or reports. Cap financial output to counts and file references unless raw rows
materially support the task or were requested. Perform an external-disclosure review before sending financial data
outside the agent workspace.

Completion requires the requested artifact, an intentional diff, atomic replacement where applicable, and structural
plus domain validation evidence. A new or changed text-table schema also requires a defined table interface and a
complete migration of affected producers, consumers, existing rows, generated artifacts, and validators.

© PaulRBerg · MIT · PaulRBerg/agent-skills

Similar skills

All skills for Data and databases →

From the same set16

The whole set →

Project sponsors

Companies that keep this analytics open