Claude Skill

spreadsheets

Imported from paulrberg/agent-skills/skills/spreadsheets.

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download PaulRBerg-agent-skills-skills_spreadsheets-47581b8.zip · 22 KB

Install

skills CLI npx skills add https://github.com/PaulRBerg/agent-skills/tree/main/skills/spreadsheets
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install paulrberg-agent-skills@llmmart
Git git clone https://github.com/PaulRBerg/agent-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole paulrberg/agent-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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:

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.

Files (agent-skills)
  • agents
    • openai.yaml 42 B
      Loading…
  • references
    • recipes.md 2.4 KB
      Loading…
    • text-table-design.md 5.2 KB
      Loading…
    • xlsx.md 8.8 KB
      Loading…
  • scripts
    • peek.py 20.8 KB
      Loading…
    • profile.py 11.8 KB
      Loading…
    • recalc.py 9 KB
      Loading…
  • SKILL.md 5.9 KB
    ---
    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.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.