How to use the Data Analysis with DuckDB agent skill

What an agent skill is and what this one does

An agent skill is a folder with a SKILL.md file that gives an AI agent instructions for a specific kind of task. When a request matches the skill's description, the agent follows those instructions and can run the scripts the skill includes.

This skill is triggered when you upload Excel or CSV files and ask for data analysis, statistics, summaries, pivot tables, SQL queries or structured data exploration. It uses a single Python script, scripts/analyze.py, which loads your spreadsheets into DuckDB.

• Inspect file structure: sheet names, columns, types, non-null counts, row counts and the first 5 rows
• Run SQL queries, including totals, groupings, filters, joins across files and window functions
• Generate summaries: mean, median, stddev, percentiles and null counts for numeric columns; count, unique, top value and frequency for text columns
• Support multi-sheet Excel workbooks, where each sheet becomes a table
• Export results to CSV, JSON or Markdown

Install the data-analysis skill

Option one: download the ZIP for this skill from this page and unzip it into ~/.claude/skills/ to make it available for your user, or into a project's .claude/skills/ folder to make it available only in that project.

Option two: in the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

The skill ships with AGENTS.md, scripts/analyze.py and SKILL.md. Keep the scripts folder intact so the agent can run analyze.py.

Install the Python packages it needs

The skill needs Python with the duckdb package, and the openpyxl package for Excel files. Install both with the same Python interpreter that will run the script. The skill's own instructions give this command.

If a package is missing, the script exits with a setup instruction. It does not install anything itself or change your environment.

Trigger the skill with natural requests

You do not need special syntax. Upload your file and describe what you want in ordinary words. The agent decides to use the skill when your request involves Excel or CSV analysis.

Be specific about the question and the output you want. The skill's instructions ask the agent to identify the file location, the analysis goal and the output format before it starts.

• Analyze my sales_2024.xlsx and show the top products by revenue and monthly trends.
• Give me summary statistics for each numeric column in this CSV.
• Join orders.csv with customers.csv on customer_id and list spend by region.
• Filter the Sales sheet to amounts over 1000 and save the result as a CSV.
• Count the rows in each sheet of this workbook and show the distinct values in the category column.

Run the commands the agent uses

The agent calls analyze.py with a few parameters: --files (space-separated paths), --action (inspect, query or summary), --sql for queries, --table for summaries and --output-file for exports. The examples below come from the skill's instructions. They use the path /mnt/skills/public/data-analysis/, so if you install the skill elsewhere the path in the commands will differ.

First, inspect the file. Then run a query, or a summary of one table.

• Inspect: --action inspect shows sheets or filenames, columns, types, counts and sample rows.
• Query: --action query with --sql runs any DuckDB SQL against your data.
• Summary: --action summary with --table gives statistics for one sheet or file.

Export results to CSV, JSON or Markdown

Add --output-file with a path ending in .csv, .json or .md. The format is detected from the extension. Bare filenames are written to the current working directory, and missing parent folders in a path are created automatically. An existing file at the target path is overwritten without warning.

JSON exports need unique column names, so use SQL aliases for repeated names. JSON also rejects NaN and Infinity values, so filter or replace them in SQL first.

• Use aliases such as SELECT a.id AS left_id, b.id AS right_id when joining tables with the same column names
• Replace non-finite ratios with CASE WHEN isfinite(ratio) THEN ratio ELSE NULL END AS ratio

Understand table names when you query

Each Excel sheet becomes a table named after the sheet. Each CSV becomes a table named after the file without its extension, so data.csv becomes data. When several files are loaded together, their tables can be joined in one query.

Names with spaces or special characters are sanitized, so sales-2026 becomes sales_2026. Use the SQL names that inspect prints, or wrap a unique original name in double quotes. Repeated names get suffixes such as report_1 in input order.

Safety, data handling and limits

The skill runs a script, so the listing marks it as running scripts. The listing also says it does not use the network. The skill's own notes say your data is processed and cached locally in temp storage, and that behaviour depends on the host environment. Check that this is acceptable before you upload anything sensitive.

The instructions assume your files are in the uploads folder under /mnt/user-data. The skill is not designed for live database connections or for files outside that expected location.

• Avoid uploading very sensitive datasets to an agent environment unless your organisation allows it
• Do not expect it to connect to live databases
• Output files overwrite existing files at the same path without a warning
• Keep your original spreadsheets; the skill reads them but this guide does not describe changing them