analyze-data

name	analyze-data
description	Analyze any data file (CSV, Excel, Parquet, JSON, gzip) with plain-language instructions, computed via the DuckDB CLI. Inspect the file with a fixed profiler first, then run SQL — never guess column names or types.
argument-hint	<datafile> [plain-language instructions]
disable-model-invocation	true
allowed-tools	Bash(duckdb *), Bash(bash ${CLAUDE_SKILL_DIR}/scripts/profile.sh *), Bash(command -v duckdb), Bash(mkdir -p *)

Analyze data with DuckDB

Take a data file and answer questions about it in plain language. All computation runs through the DuckDB CLI (duckdb), which reads CSV, TSV, Excel, Parquet, JSON and gzip directly from the file — no database is created.

The language model does not do the arithmetic. It writes SQL; DuckDB computes. This keeps results correct and reproducible.

Arguments

$ARGUMENTS is: the first whitespace-delimited token is the data file path ($0), and everything after it is the natural-language analysis request.

If no instructions follow the path, just run the profile (step 2) and stop.

Procedure

Follow these steps in order. Do not skip step 2.

1. Ensure DuckDB is installed. Run command -v duckdb. If missing, tell the user to install it (brew install duckdb, or see https://duckdb.org) and stop.

2. Profile the file first (the deterministic core). Run the bundled pure function — same file in, same profile out:

   bash ${CLAUDE_SKILL_DIR}/scripts/profile.sh "<datafile>"
   

   It prints three sections: row count, the schema + per-column stats (SUMMARIZE), and the first 5 rows. Read them. Take column names and types only from this output — never guess them. If the request mentions a column that isn't in the schema, or anything is ambiguous, ask the user before querying. (The user may also ask you to remap the file into an expected shape first — e.g. rename/derive columns in a CTE — then run the analysis over that.)

3. Write and run the query. Compose one DuckDB SQL statement that answers the request, grounded in the real schema, and execute it:

   duckdb -markdown -c "COPY ( ... ) TO '/dev/stdout'"   # or simply:
   duckdb -markdown -c "<your SELECT>"
   

   Reference the file directly in FROM, e.g. FROM 'sales.csv', FROM read_xlsx('book.xlsx'), FROM 'events.parquet'. Use SQL from the DuckDB docs: https://duckdb.org/docs/current/sql/introduction.

4. Make it reproducible. Save the final query so the exact same analysis can be re-run byte-for-byte later:

   mkdir -p ./analysis && duckdb -markdown -c ".read ./analysis/<name>.sql"
   

   Write the SELECT to ./analysis/<name>.sql, then present the result table and a short plain-language summary. Point the user at the saved .sql as the reproducible artifact.

Notes

• Present numeric results from DuckDB verbatim. Do not recompute or "adjust" totals.
• Prefer one well-formed query over many small ones; DuckDB handles grouping, window functions, date bucketing (date_trunc('month', ...)) and CASE grouping.
• For "recurring vs one-off" style requests: recurrence = a counterparty/pattern that appears in most periods; everything else goes to an Ostatní / Other bucket via a CASE expression.
• Supporting file: scripts/profile.sh — the deterministic profiler. It is executed, not read into context.