Query

Runs SQL queries against DuckDB databases, either in session mode with attached databases or ad-hoc against files. It handles natural language questions by generating SQL using DuckDB's Friendly SQL idioms like FROM-first syntax, GROUP BY ALL, and direct file queries. The skill estimates result sizes before execution to avoid token-heavy outputs and warns you if you're about to pull back millions of rows without a LIMIT. It sandboxes ad-hoc queries with restricted file access and falls back gracefully when databases aren't accessible. Error handling is solid, automatically installing missing extensions and searching docs when things break. If you're already using DuckDB for data work, this gives you a conversational layer that knows the shortcuts.

skills.sh installs: 1.6K
GitHub stars: 616
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add duckdb/duckdb-skills --skill query --agent claude-code

Installs into .claude/skills of the current project.

Files

You are helping the user query data using DuckDB.

Input: $@

Follow these steps in order.

Step 1 — Resolve state and determine the mode

Look for an existing state file in either location:

STATE_DIR=""
test -f .duckdb-skills/state.sql && STATE_DIR=".duckdb-skills"
PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")"
PROJECT_ID="$(echo "$PROJECT_ROOT" | tr '/' '-')"
test -f "$HOME/.duckdb-skills/$PROJECT_ID/state.sql" && STATE_DIR="$HOME/.duckdb-skills/$PROJECT_ID"

If found, verify the databases it references are still accessible:

duckdb -init "$STATE_DIR/state.sql" -c "SHOW DATABASES;"

Now determine the mode:

Ad-hoc mode if: the --file flag is present, or the SQL references file paths/literals (e.g. FROM 'data.csv'), or STATE_DIR is empty.
Session mode if: STATE_DIR is set and the input references table names, is natural language, or is SQL without file references.

If no state file exists and no file is referenced, fall back to ad-hoc mode against :memory: — the user must reference files directly in their SQL.

SKILL.md on GitHub