DuckDB CLI

Reviewed 2026-10-14dataPrompt / Rule# duckdb # sql # csv # parquet # data

Official DuckDB skills: query files and databases with the duckdb CLI, read CSV/Parquet/JSON, search DuckDB docs and install extensions.

Security Reviewed

Official instruction-only DuckDB skills that run the duckdb CLI via Bash; only query's ad-hoc mode is sandboxed, and the upgrade path uses a curl | sh installer after asking.

Install DuckDB CLI in Google Antigravity

Antigravity loads skills from .agents/skills/ in your project or ~/.gemini/config/skills/ for all projects (official docs). Full guide

EasiestOption 1: paste this to your Antigravity agent

Install the "DuckDB CLI" skill for Google Antigravity.
Follow the steps at https://www.antigravityskills.org/install/duckdb-cli.md (source: https://github.com/duckdb/duckdb-skills).
Before running anything, show me what you will download and whether it includes scripts, and wait for my OK.
Install it into this project (.agents/skills/) unless I say global. When done, check that Antigravity lists it as an installed skill.

The agent reads the install file, shows you what it will download and waits for your OK.

Option 2: install it yourself

1. Install the DuckDB CLI
```
duckdb --version
```
If it is missing, the install-duckdb skill lists: macOS brew install duckdb; Linux curl -fsSL https://install.duckdb.org | sh; Windows winget install DuckDB.cli (Windows is not fully supported per the README).

2. Download the repository

git clone --depth 1 https://github.com/duckdb/duckdb-skills /tmp/duckdb-skills && git -C /tmp/duckdb-skills log -1 --format=%h

We reviewed commit 7feda8e; a different hash means the skills changed after our review.

3. Copy the skills into this project (workspace skills)
```
mkdir -p .agents/skills && cp -r /tmp/duckdb-skills/skills/{attach-db,convert-file,duckdb-docs,install-duckdb,query,read-file,s3-explore,spatial} .agents/skills/
```
Run from your project root (bash or zsh). This copies 8 of the 9 folders and leaves out read-memories, which only reads Claude Code session logs. Copy just query and read-file if you want the minimum.

4. Or install them for all projects (global skills)

mkdir -p ~/.gemini/config/skills && cp -r /tmp/duckdb-skills/skills/{attach-db,convert-file,duckdb-docs,install-duckdb,query,read-file,s3-explore,spatial} ~/.gemini/config/skills/

Use this instead of the previous step. For the Antigravity CLI the global folder is ~/.gemini/antigravity-cli/skills/.

5. Check that Antigravity sees them
Antigravity 2.0 app: start a new conversation and ask "What skills do you have?"; query, read-file and the others should be listed. Antigravity CLI: run /skills (/skills reload in a session that was already open).

The duckdb-skills README only documents the Claude Code plugin and does not mention Antigravity. These steps copy the plain SKILL.md folders into Antigravity's standard skill folders; the /duckdb-skills:<name> references inside them are Claude Code names, so ask for a skill by what you want done.

Using Claude Code, Cursor or Codex? See other assistants below.

What is DuckDB CLI?

duckdb-skills is the DuckDB organization's official set of agent skills for people who want to ask questions of CSV, Parquet, JSON, Excel or SQLite files, or of DuckDB databases, without loading them into a server first. The skills tell the agent how to drive the duckdb command-line tool. It is packaged as a Claude Code plugin, but each skill is a plain SKILL.md folder. What we counted at commit 7feda8e (2026-04-14, still the latest commit on 2026-10-14): 17 files in the repo; 9 skill folders (attach-db, convert-file, duckdb-docs, install-duckdb, query, read-file, read-memories, s3-explore, spatial) with 967 SKILL.md lines / 36,328 bytes in total; 1 shell script (install-duckdb/eval.sh, a test harness); plugin version 0.2.4. The README documents only 6 of the 9 skills; convert-file, s3-explore and spatial are not in it. convert-file maps 9 output extensions (Parquet, CSV, TSV, JSON, JSONL, XLSX, GeoJSON, GeoPackage, Shapefile).

How to use DuckDB CLI?

Install the DuckDB CLI first. In Claude Code, add the marketplace and install the plugin, then call skills like /duckdb-skills:query FROM 'exports.csv' WHERE amount > 100. In Antigravity, copy the skill folders into .agents/skills/ and ask in plain words, for example "what are the top 5 customers by revenue in sales.parquet?". The skills share one state.sql file (in .duckdb-skills/ in the project or in ~/.duckdb-skills/<project>/), so a database attached with attach-db is available to query later.

Key features of DuckDB CLI

✓query: raw SQL or natural-language questions, written in DuckDB's Friendly SQL
✓query (ad-hoc mode only): runs in :memory: with allowed_paths limited to the referenced files, external access off and configuration locked
✓query: estimates result size and asks before returning more than 1M rows
✓read-file: CSV, JSON, Parquet, Avro, Excel, spatial, SQLite and more, locally or from S3, GCS, Azure or HTTPS
✓convert-file: one COPY command to Parquet (default), CSV, JSON, XLSX, GeoJSON and other formats
✓duckdb-docs: full-text search over DuckDB and DuckLake docs via hosted search indexes
✓install-duckdb: installs or updates extensions, including name@repo community extensions

When to use DuckDB CLI

1Asking questions of a CSV or Parquet file without importing it
2Exploring and querying a .duckdb database
3Converting data files between formats
4Looking up DuckDB syntax or an error message in the docs

Installation & Setup Guide

Agent Rules / Prompt Setup

Follow these steps (taken from the project's own docs) to configure DuckDB CLI in your development environment.

Step 1: Claude Code: add the marketplace (README)claude

/plugin marketplace add duckdb/duckdb-skills

Run inside Claude Code.

Step 2: Claude Code: install the plugin (README)claude

/plugin install duckdb-skills@duckdb-skills

Skills then appear as /duckdb-skills:<skill-name>. Update later with /plugin marketplace update duckdb-skills and /plugin update duckdb-skills@duckdb-skills.

Step 3: Cursor: not documented by the projectcursor

The README only covers Claude Code, so we do not list a Cursor path.

Usage Example & Verification

Prompt / Request Example

1) README example: /duckdb-skills:query "what are the top 5 customers by revenue?" (in Antigravity, ask it in plain words and name the file, e.g. "...in sales.parquet")
-> What happens: if a state.sql exists, the agent reads the schema of the attached tables and writes a GROUP BY query; otherwise it runs ad-hoc against the file you named, in the sandboxed :memory: mode.

2) README example: /duckdb-skills:read-file variants.parquet what columns does it have?
-> What happens: the read-file skill opens the file with its read_any macro and reports columns and types, then suggests the query skill for follow-up questions.

3) Our example: "Convert exports.csv to Parquet with zstd compression."
-> What happens: the convert-file skill runs one duckdb COPY ... TO 'exports.parquet' with CODEC 'zstd' and reports the output size with ls -lh. Note that this writes a new file in your project.

Installation Confirmation Method

Ask "What skills do you have?" in a new Antigravity conversation (CLI: /skills) and look for query and read-file. Then run duckdb --version in a terminal and ask "what columns does data.csv have?" about a file in your project.

Security Review

Static review

Reviewed Date

2026-10-14

Audited Ref / Commit

7feda8e01e22bc0886c86123f3884947e36d8c69

Reviewer

antigravityskills.org (static code review)

Official instruction-only DuckDB skills that run the duckdb CLI via Bash; only query's ad-hoc mode is sandboxed, and the upgrade path uses a curl | sh installer after asking.

Full review: scope, findings, risks

Audit Scope:Static review of duckdb/duckdb-skills at commit 7feda8e (2026-04-14, HEAD on 2026-10-14): README.md, .claude-plugin/plugin.json and marketplace.json, all 9 skills/*/SKILL.md (frontmatter, commands, URLs, sandbox settings), skills/query/SKILL.md and skills/convert-file/SKILL.md in full, skills/install-duckdb/eval.sh, LICENSE. The spatial reference files were counted but not read in full.

Key Findings:Instruction-only skills; every SKILL.md has allowed-tools: Bash. The only script is install-duckdb/eval.sh, a test harness that calls claude --print. Network: duckdb.org and ducklake.select search indexes (duckdb-docs), duckdb.org/data/latest_stable_version.txt and install.duckdb.org (install-duckdb), stac.overturemaps.org (spatial), plus any remote file you ask for. Sandbox settings appear only in query's ad-hoc mode. Writes state.sql and any converted files. read-memories reads ~/.claude/projects/*/*.jsonl. No API keys.

Identified Operational Risks & Permissions:install-duckdb can pipe a remote install script to sh (after asking). Session-mode queries and the other skills run without the ad-hoc sandbox. read-memories reads your Claude Code conversation logs.

Static review at commit 7feda8e. All 9 folders under skills/ are SKILL.md instructions with allowed-tools: Bash; the one script, skills/install-duckdb/eval.sh, is an evaluation harness that runs claude --print and duckdb LOAD and is not used by the skills. skills/query/SKILL.md runs ad-hoc queries in :memory: with SET allowed_paths, enable_external_access=false, allow_persistent_secrets=false and lock_configuration=true, and asks before returning more than 1M rows; we found these settings in no other skill, and session-mode queries run against the databases in state.sql without them. skills/install-duckdb/SKILL.md fetches https://duckdb.org/data/latest_stable_version.txt and, if you agree, upgrades with brew, winget or curl -fsSL https://install.duckdb.org | sh. skills/duckdb-docs/SKILL.md queries hosted search indexes at duckdb.org and ducklake.select and can cache them locally. read-file, convert-file and s3-explore load httpfs and create secrets with PROVIDER credential_chain for cloud URLs, which uses your existing cloud credentials. skills/read-memories/SKILL.md reads Claude Code session logs in ~/.claude/projects. State is written to state.sql in the project or home directory.

Operational Notes & Known Limitations

Known Limitations

•Requires the DuckDB CLI (duckdb) on PATH; install-duckdb only prints install commands if it is missing
•README: tested on macOS and Linux; Windows is not yet fully supported
•Written for Claude Code: all 9 SKILL.md files declare an argument-hint, they use Claude Code argument placeholders such as $@, $0 and $1, and they call each other as /duckdb-skills:<name>. In Antigravity the agent has to take the arguments from your message instead
•Only the query skill's ad-hoc mode sets the sandbox (allowed_paths, enable_external_access=false, lock_configuration=true). We found no such settings in the other 8 skills, and session-mode queries run against your attached databases without them
•read-memories reads Claude Code session logs in ~/.claude/projects/; it does nothing useful in Antigravity
•Generic folder names (query, read-file, spatial) can clash with other skills in the same skills folder
•Antigravity is not mentioned in the repository (we searched). Difference from the sqlite-mcp-server page: that is an archived MCP server for one SQLite file; these skills drive the DuckDB CLI and can read many file formats, including SQLite

Frequently Asked Questions

Is the DuckDB skill safe?

In our static review of commit 7feda8e the skills are instructions that run the duckdb CLI through Bash. Only query's ad-hoc mode is sandboxed. duckdb-docs and read-file can fetch remote data, install-duckdb can upgrade DuckDB with curl | sh after asking, and the skills write a state.sql file.

How do I install the DuckDB skills in Antigravity?

Install the DuckDB CLI, clone duckdb/duckdb-skills, copy the skill folders (we suggest all except read-memories) into .agents/skills/ or ~/.gemini/config/skills/, then ask "What skills do you have?" (CLI: /skills). The README does not mention Antigravity.

Does it need an API key?

No. S3, GCS or Azure files use your own cloud credentials through DuckDB's credential_chain if you query them.

Where is session state stored?

In .duckdb-skills/state.sql in the project or ~/.duckdb-skills/<project>/state.sql; you are asked the first time. It holds ATTACH, LOAD, secret and macro statements.